Avaya™ Interaction Center
Release 6.0
Core Services Programmer’s Guide
DXX-1024-02
Issue 1.0
June 2002
Every effort was made to ensure that the information in this book was complete and accurate at the time of printing. However, information is subject to change.
Preventing Toll Fraud
“Toll fraud” is the unauthorized use of your telecommunications system by an unauthorized party (for example, a person who is not a corporate employee, agent, subcontractor, or working on your company's behalf). Be aware that there may be a risk of toll fraud associated with your system and that, if toll fraud occurs, it can result in substantial additional charges for your telecommu-nications services.
Avaya Fraud Intervention
If you suspect that you are being victimized by toll fraud and you need technical support or assistance, call Technical Service Center Toll Fraud Intervention Hotline at +1 800 643 2353.
Providing Telecommunications Security
Telecommunications security (of voice, data, and/or video communications) is the prevention of any type of intrusion to (that is, either unauthorized or mali-cious access to or use of your company's telecommunications equipment) by some party.
Your company's “telecommunications equipment” includes both this Avaya product and any other voice/data/video equipment that could be accessed via this Avaya product (that is, “networked equipment”).
An “outside party” is anyone who is not a corporate employee, agent, subcon-tractor, or working on your company's behalf. Whereas, a “malicious party” is anyone (including someone who may be otherwise authorized) who accesses your telecommunications equipment with either malicious or mischievous intent.
Such intrusions may be either to/through synchronous (time-multiplexed and/or circuit-based) or asynchronous (character-, message-, or packet-based) equip-ment or interfaces for reasons of:
• Utilization (of capabilities special to the accessed equipment) • Theft (such as, of intellectual property, financial assets, or toll-facility
access)
• Eavesdropping (privacy invasions to humans)
• Mischief (troubling, but apparently innocuous, tampering)
• Harm (such as harmful tampering, data loss or alteration, regardless of motive or intent)
Be aware that there may be a risk of unauthorized intrusions associated with your system and/or its networked equipment. Also realize that, if such an intru-sion should occur, it could result in a variety of losses to your company (includ-ing but not limited to, human/data privacy, intellectual property, material assets, financial resources, labor costs, and/or legal costs).
Your Responsibility for Your Company's Telecommunications Security
The final responsibility for securing both this system and its networked equip-ment rests with you - an Avaya customer's system administrator, your telecom-munications peers, and your managers. Base the fulfillment of your
responsibility on acquired knowledge and resources from a variety of sources including but not limited to:
• Installation documents
• System administration documents • Security documents
• Hardware-/software-based security tools • Shared information between you and your peers • Telecommunications security experts
To prevent intrusions to your telecommunications equipment, you and your
Fax: +1 800 457 1764 International Fax: 410 891 0207 Email: [email protected] Write: GlobalWare Solutions Attention: Avaya Account Manager 200 Ward Hill Avenue
Haverhill, MA 01835 USA
Order: Document No. DXX-1024-02, Issue 1.0, June 2002 To order product documentation online, go to
http://www.avayadocs.com, click on Online Services, and select the appropri-ate product group.
Warranty
Avaya Inc. provides a limited warranty on this product. Refer to the “Limited Use Software License Agreement” or other applicable documentation provided with your package to establish the terms of the limited warranty.
Avaya Web Page
http://www.avaya.com
Trademarks
Avaya, Conversant, CustomerQ, Definity, DefinityOne, Nabnasset, Quintus, and WebQ are registered trademarks or trademarks of Avaya Inc. in the United States or other countries or both.
Portions of Avaya Interaction Center include technology used under license as listed below, and are copyright of the respective companies and/or their licen-sors:
ActivePerl is a trademark of ActiveState Tool Corp. This product includes software developed by the Apache Software Foundation
(http://www.apache.org/). Cognos, Impromptu and Powerplay are registered trademarks of Cognos Incorporated. YACC++ is a registered trademark of Compiler Resources, Inc. APEX, ComponentOne, VideoSoft, True DBGrid, VSVIEW, SizerOne, VS-OCX, VSFlexGrid, VSFORUM, VSREPORTS, VSDOCX, VSSPELL, and TrueDBList are either registered trademarks or trademarks of ComponentOne LLC. CT Connect, Dialogic, Intel, and Pentium are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries. Hummingbird is a registered trademark of Hummingbird, Ltd. SearchServer is a trademark of Hummingbird, Ltd. RISC System/6000 and DirectTalk/2 are trademarks of International Business Machines Corporation in the United States or other countries or both. IBM, OS/2, AS/400, CICS, WebSphere, CT, VisualAge, and DirectTalk are registered trademarks of International Business Machines Corporation in the United States or other countries or both. Lotus and Lotus Sametime are trademarks or registered trademarks of Lotus Development Corporation and/or IBM Corporation in the United States, other countries, or both. VisualX is a registered trademark of Intergroup Technologies, Inc. ActiveX, Visio, Internet Explorer, Windows, Windows NT, Windows 2000, Win32s, SQL Server, Visual Basic, Visual C++, Outlook, and FrontPage are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. TimesTen is a registered trademark of TimesTen Performance Software. Oracle is a registered trademark, and Oracle8i and
Oracle® SQL/Services are trademarks or registered trademarks of Oracle Corporation. Rogue Wave and .h++ are registered trademarks of Rogue Wave Software Inc. SourcePro is a trademark of Rogue Wave Software, Inc. Siebel is a trademark of Siebel Systems, Inc. BasicScript is a registered trademark of Summit Software Company. Sun, iPlanet, Java, Solaris JRE, J2EE, JavaServer Pages, and all Java-based trademarks are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. SPARC is a registered trademark of SPARC International, Inc. Products bearing SPARC trademarks are based on an architecture
devel-3
B
EFORE
Y
OU
B
EGIN
. . . 7
1
C
ORE
S
ERVICES
O
VERVIEW
. . . 11
Core Services Descriptions . . . 11
CORBA Implementation . . . 12
2
G
ENERIC
S
ERVER
M
ETHODS
. . . 13
IDL Specification . . . 13
3
T
HE
ORB S
ERVER
. . . 33
Overview . . . 33
Automatically Starting and Stopping Servers . . . 33
Timing Server Restart Attempts . . . 34
Updating Server Configuration . . . 34
Directing Requests to a Specific Server . . . 34
Configuration . . . 35
IDL Specification . . . 35
Alarms . . . . 43
4
T
HE
A
LARM
S
ERVER
. . . 45
Overview . . . 45
Sharing Alarms Across a WAN . . . 45
Configuring the Alarm Server . . . 46
Predefined Data Elements . . . 46
Generating Alarms . . . . 47
Alarm Monitoring . . . . 48
IDL Specification . . . 50
5
T
HE
D
IRECTORY
S
ERVER
. . . 55
Overview . . . 55
Use of the DS by Client Applications . . . 55
Wide Area Network Considerations . . . 56
Configuration . . . 57
Usage and Performance . . . 58
Sizing Recommendations . . . 59
Directory Structure . . . 59
Database Schema . . . 59
Data Structure . . . 59
Avaya IC Defined Records . . . 60
Server Record . . . 61
User Record . . . 61
Using the Directory Server . . . 63
Creating Records . . . 63
Selecting and Releasing Records . . . 63
Reading Records . . . 64
Updating Records . . . 64
Deleting Records . . . 65
Selection Criteria . . . 65
Selection Criteria Syntax . . . 65
Selection Criteria Wildcards . . . 66
IDL Specification . . . 67
6
T
HE
D
ATA
C
ONNECTOR
S
ERVER
. . . 105
Overview . . . 105
Data Server Architecture . . . 106
Single Database Login . . . 106
Client Authentication . . . 107
Issue 1.0 June 2002 5 Contents
Database Events . . . 110
Running in Different Timezones . . . 110
DISPLAYTIME=”DBMSTIME” . . . 111
Timestamps . . . 112
ODBC Data Source Interface Notes . . . 112
ODBC Setup . . . 112
Adding an ODBC Data Source . . . 113
7
A
VAYA
IC ORB R
OUTINES
. . . 117
BOA Routines (Basic Object Adapter) . . . 117
Context Routines . . . 118
Hybrid API Routines . . . 118
Hybrid DDE API Routines . . . 118
Hybrid Common API Routines . . . 118
Hybrid Client Routines . . . 119
Hybrid Server Routines . . . 119
Memory Routines . . . 120
Miscellaneous Routines . . . 121
NVList Routines (Named Value List) . . . 121
ORB Routines (Object Request Broker) . . . 122
ORB Object Routines (Server Objects) . . . 122
Request Routines . . . 123
Session Routines . . . 123
Support Routines . . . 124
Internal Network Routines . . . 125
Timed Routines . . . 125
8
A
VAYA
IC T
OOLKIT
F
UNCTIONS
. . . 127
Function Descriptions . . . 127
7
B
EFORE
Y
OU
B
EGIN
Typographical Conventions
This guide uses the following font conventions:
Notes, Tips, and Cautions
Note: A note calls attention to important information.
Tip: A tip offers additional how-to advice.
Caution: A caution points out actions that may lead to data loss or other serious problems.
Contacting Technical Support
If you are having trouble using Avaya software, you should:
1 Retry the action. Carefully follow the instructions in written or online documentation.
2 Check the documentation that came with your hardware for maintenance or hardware-related issues.
Font Type Meaning
code This font signifies commands, information that you enter into the computer, or
information contained in a file on your computer.
italics This font is used to add emphasis to important words and for references to other chapter names and manual titles.
It also indicates variables in a command string.
jump Blue text in online documents indicates a hypertext jump to related information. To view the related material, click on the blue text.
3 Note the sequence of events that led to the problem and the exact messages displayed. Have the Avaya documentation available.
4 If you continue to have a problem, contact Avaya Technical Support by: w Logging in to the Avaya Technical Support Web site
(http://www.avaya.com/support/qq).
w Calling or faxing one of the following numbers from 8:30 a.m. to 8:30 p.m. (Eastern Standard Time), Monday through Friday (excluding holidays):
w Toll free in the U.S. only: 1-888-TECH-SPT (1-888-832-4778) w Direct line for international and domestic calls: 512-425-2201 w Direct line for faxes: 512-719-8225
w Sending email with your question or problem to [email protected]. You may be asked to email one or more files to Technical Support for analysis of your application and its environment.
Note: If you have difficulty reaching Avaya Technical Support through the above URL or email address, please go to www.avaya.comfor further information.
Product Documentation
Most Avaya product documentation is available in both printed and online form. However, some reference material is available only online, and certain information is available only in printed form. A PDF document with detailed information about all of the documentation for the Avaya Interaction Center is included in the Doc directory on the product CD-ROM. This PDF document is
also included on the separate documentation CD-ROM.
Readme File
The Readme file is an HTML file included on the Avaya Interaction Center software CD-ROM. This file contains important information that was collected too late for inclusion in the printed documentation. The Readme file can include installation instructions, system requirements, information on new product features and enhancements, suggested work-arounds to known problems, and other information critical to successfully installing and using your Avaya software. You may also receive a printed Addendum to the Readme, containing similar information
uncovered after the manufacture of the product CD-ROM. You should review the Readme file and the Readme Addendum before you install your new Avaya software.
Educational Services
Issue 1.0 June 2002 9
Printed Documentation
You can purchase printed copies of these manuals separately. For details, see “Ordering Information,” on the back of this manual’s title page.
License to Print the Electronic Documentation
Online copies of documentation are included on the CD-ROM that accompanies every software release. An Avaya customer who has licensed software (a “Licensee”) is entitled to make this online documentation available on an internal network or “intranet” solely for the Licensee's use for internal business purposes. Licensees are granted the right to print the documentation
corresponding to the software they have purchased solely for such purposes.
Right-To-Print License Terms
Documents must be printed “as-is” from the provided online versions. Making changes to documents is not permitted. Documents may be printed only by any employee or contractor of Licensee that has been given access to the online documentation versions solely for Licensee's internal business purposes and subject to all applicable license agreements with Avaya. Both online and printed versions of the documents may not be distributed outside of Licensee enterprise or used as part of commercial time-sharing, rental, outsourcing, or service bureau use, or to train persons other than Licensee's employees and contractors for Licensee's internal business purposes, unless previously agreed to in writing by Avaya. If Licensee reproduces copies of printed
documents for Licensee's internal business purposes, then these copies should be marked “For internal use only within <Licensee> only.” on the first page or cover (where <Licensee> is the name of Licensee). Licensee must fully and faithfully reproduce any proprietary notices contained in the documentation. The copyrights to all documentation provided by Avaya are owned by Avaya and its licensors. By printing any copy of online documentation Licensee indicates its acceptance of these terms and conditions. This license only governs terms and conditions of printing online documentation. Please reference the appropriate license agreement for terms and conditions applicable to any other use, reproduction, modification, distribution or display of Avaya software and documentation.
Educational Services
Avaya University provides excellent training courses on a variety of topics. For the latest course descriptions, schedules, and online registration, you can get in touch with us:
n Through the web at http://www.avaya-learning.com
n Over the telephone at 800-288-5327 (within the U.S.) +001 303-406-6089 (outside of the U.S.) n Through email at [email protected]
11
C
HAPTER
1
C
ORE
S
ERVICES
O
VERVIEW
Avaya Interaction Center (Avaya IC) is advanced contact center management software that integrates computers, telephones, voice, and data.
Avaya IC consists of a collection of specialized client and server objects, and the CORBA (Common Object Request Broker Architecture) platform and development tools necessary to develop custom clients and servers. The servers and clients provided by Avaya encompass the standard functionality required for most computer telephony integration applications.
This manual describes the Avaya IC core services, including generic methods that are available to all clients and servers in the Avaya IC system, core servers, and Telephony Toolkit functions.
Core Services Descriptions
The core services described in this manual are:
ORB Server The ORB (Object Request Broker) Server operates behind the scenes to ensure that Avaya IC services are available to clients in a truly location-independent manner. It is capable of restarting a server that is stopped when its services are needed. It also assists in locating the required services to fulfill a client's requests. One ORB Server will reside on each physical computer that contains one or more Avaya IC servers.
Alarm Server The Alarm Server is called by clients and servers to report an alarm condition.
Directory Server The Directory Server maintains a flat file database that is a central repository for information about the Avaya IC environment. It maintains configuration data for servers, agent information, lookup tables and other system information.
Data Connector Server The Data Connector Server allows developers to create database-independent applications using the Data Server libraries instead of database libraries. This reduces the size of the application and eliminates the need to install database libraries or support files on every machine running the application.
Additional Avaya IC services are described in separate manuals in the Avaya IC documentation set. For more information about Avaya IC components, consult these books on the Documentation CD.
CORBA Implementation
Avaya components communicate with each other through TCP/IP, using a protocol that is based upon an early version of the Common Object Request Broker Architecture (CORBA). The Avaya protocol includes several features that were not part of the CORBA specification. These features provide high performance and reliability for CRM and contact management applications. As CORBA has evolved, Avaya has chosen not to implement all of the features of the latest CORBA specifications, and has not made its CORBA implementation interoperable with other CORBA implementations, because the existing Avaya protocol is highly optimized for its intended use. Those customers desiring inter operability with other CORBA based products will need to implement an interface between the Avaya environment and the other CORBA environment.
Avaya IC Toolkit The Avaya IC Toolkit provides a set of network-based functions for the creation of data structures and application programming interfaces (APIs). The Toolkit functions focus on creating, defining, accessing, and deleting network-based objects.
13
C
HAPTER
2
G
ENERIC
S
ERVER
M
ETHODS
There is always a need for a certain set of basic functionality in a server. The methods described in this chapter can be inherited by all servers to create a baseline of functionality. They are built into the toolkit. To access them, include the file generic.idl in your interface definition:
#include "generic.idl"
When creating a new interface, you may inherit the General interface by including the following in your interface definition:
interface your_server : General
To access the General methods, precede the method name with the name of your server's interface; the term Generic is used as an example in this chapter.
IDL Specification
interface General virtual {
ORBStatus Deassign(); /* all VESP Servers can deassign */ /* Process control, all require proc priv */
ONEWAY Exit( in unsigned long exit_code ); ONEWAY Crash();
ORBStatus Shutdown( in unsigned long time ); /* Reject new request terminated current sessions,
tell ORB Server not to route more requests */ ORBStatus DisableServer(in unsigned long time ); ORBStatus EnableServer( in unsigned long time );
ORBStatus CreateUUID( in Identifier host, in Identifier service, in string version, in string
max_users, out string uuid_str );
ORBStatus DecodeUUID( in string uuid_str, out string host, outstring service, out string
time_high, out string time_low, out string version, out string max_users );
unsigned long GetTracing();
ORBStatus GetStatus( out SeqCouple status ); ORBStatus GetCtime( out string ctime );
ORBStatus GetTimet( out unsigned long timet ); /* Note Subsystem */
ORBStatus CreateNote( in string mode, in string name, in string value );
ORBStatus DeleteNote( in string name ); ORBStatus DeleteAllNotes();
ORBStatus GetNote( in string name, out string value ); ORBStatus GetAllNotes( out SeqCouple note_list ); ORBStatus MonitorNote( in string mode );
ORBStatus GenericUpdate( in string info );
ONEWAY SetTracing( in unsigned long trace_level ); ORBStatus LoadNewImplementation();
ORBStatus Ping();
/* Print internal server info */ ORBStatus PrintSessionInfo(); ORBStatus PrintAll();
ORBStatus PrintAllRequests();
ORBStatus GetToolkitVersion( out string version ); ORBStatus GetServerVersion( out string version ); /* memory control */
ORBStatus GetMemoryCount( out unsigned long memory_count ); ORBStatus LoseHeap();
ORBStatus ShowHeap();
ORBStatus ShowMemoryCache(); ORBStatus ShowNetworkStatus();
ORBStatus GetIntRepository( out sting interface_respostory ); ORBStatus GetImpRepository( out string
implementation_respostory );
ORBStatus GetFile( in string file_name, out string file ); ORBStatus GetEnviron( in string name, out string value ); ORBStatus PutEnviron( in string name_value );
ORBStatus SystemCall( in string name_value ); }
Generic.Crash
Issue 1.0 June 2002 15
Generic.Crash
IDL Syntax ONEWAY Crash( ) ;
Description Makes the server crash. The server executes the function abort().
You must have manager level security to access this method, and the calling session must have process security access.
Returns None
Example status = Vesp_Request( "Generic.Crash", callback, user_data, session);
Generic.CreateNote
IDL Syntax ORBStatus CreateNote( in string mode, in string name, in string value ) ;
Description Create a note. All clients assigned to this server will receive an event with the name Note. Input Parameters
Returns
Example Vesp_Request( "Generic.CreateNote ", callback, user_data, session, "", "mynote", "mynote_value" );
String event syntax:
[Generic.Note.event((1,1,( "mynote", "mynote_value")))]
mode Unused, empty. name Name of note value The text of the note.
Generic.CreateUUID
IDL Syntax ORBStatus CreateUUID( in Identifier host, in Identifier service, in string version, in string max_users,
out string uuid_str ) ;
Description Create a UUID string from its component information. Input Parameters
Output Parameters
Returns
Generic.Deassign
IDL Syntax ORBStatus Deassign( void ) ;
Description Terminates the current session. A special hybrid routine is used for deassigns; see Vesp_Deassign. This method will run with an explicit deassign call from an assigned client, or will run
automatically if a client terminates abnormally. Returns
host The name of the host machine.
service The name of the service (server) whose port will be associated with the UUID.
version Reserved; not currently used. max_users Reserved; not currently used.
uuid_str A completed UUID in string form, based on the input information.
VESP_SUCCESS Method was successful
Generic.DecodeUUID
Issue 1.0 June 2002 17
Generic.DecodeUUID
IDL Syntax ORBStatus DecodeUUID( in string uuid_str, out string host, out string service, out string time_high, out string
time_low, out string version, out string max_users ) ;
Description Decode a UUID string into its pieces. Input Parameters
Output Parameters
Returns
Generic.DeleteAllNotes
IDL Syntax ORBStatus DeleteAllNotes( void ) ;
Description Delete all the notes stored in the server. Returns
Example Vesp_Request("Generic.DeleteAllNotes", NULL, OUL, session );
uuid_str The UUID, in string form, to be decoded.
uuid_str The UUID, in string form, to be decoded. host The name of the host machine.
service The name of the service (server) whose port is associated with the UUID.
time_high The time (from the ANSI C time() function) the UUID was created.
time_low A sequence number used to distinguish between UUIDs created in the same second by the same object.
version Version information from the UUID. max_users Max user information from the UUID.
VESP_SUCCESS Method was successful
Generic.DeleteNote
IDL Syntax ORBStatus DeleteNote( in string name ) ;
Description Delete note named. Input Parameters
Returns
Example Vesp_Request("Generic.DeleteNote", NULL, OUL, session, "my_note" );
Generic.DisableServer
IDL Syntax ORBStatus DisableServer( in unsigned long time ) ;
Description Disable the named server. The server will reject assign requests. Input Parameters
Returns
name Name of note to delete.
VESP_NOT_FOUND Service not found VESP_SUCCESS Method was successful
time Number of seconds until the server is disabled.
Generic.EnableServer
Issue 1.0 June 2002 19
Generic.EnableServer
IDL Syntax ORBStatus EnableServer( in unsigned long time ) ;
Description Enable a server previously disabled with the DisableServer() method. Input Parameters
Returns
Generic.Exit
IDL Syntax ONEWAY Exit( in unsigned long exit_code ) ;
Description: Makes the server exit. The calling session must have process security access. If the server is configured for the ORB Server to autostart, it will not auto start if this method is called. This is the only clean way to exit a server.
Input Parameters
Returns None
Example Vesp_Request( "Generic.Exit", callback, user_data, session);
Generic.FlushLog
IDL Syntax ONEWAY FlushLog( void) ;
Description Make the server flush all buffered log information to the log file.
Returns None
Example Vesp_Request( "Generic.FlushLog ", callback, user_data, session);
time The length of time until the server is enabled.
VESP_SUCCESS Method was successful
Generic.GenericUpdate
IDL Syntax ORBStatus GenericUpdate( in string info ) ;
Description Make the server perform a generic update. The server must register its own version of GenericUpdate for this method to have any effect.
The following Avaya IC servers currently use the GenericUpdate method:
Input Parameters
Returns
Example Vesp_Request( "ORBServer.GenericUpdate", callback, user_data, session, "");
Implementation Example
ORBStatus ORBServer_GenericUpdate( Object obj, Environment *ev, char *info ) { EVCHECK(Vesp_Reload_Imp( object_gbl )); return ( VESP_SUCCESS) }
/* this routine is called before the server is registered with BOA */ ORBStatus Server_user_init(Object object)
{
Environment ev;
/* BOA init sequence */
SCHECK(BOA_set_method(VESP_BOA, ev, object, (char*)”GenericUpdate”, OUL, VESP_SUC_PROCESS_CONTROL, (ULONG)ORBServer_GenericUpdate));
TS Load new user information from the Directory. ORB Server Load all new server configuration from the Directory
and create a new implementation repository.
info Information specific to the update.
Generic.GetAllNotes
Issue 1.0 June 2002 21
Generic.GetAllNotes
IDL Syntax ORBStatus GetAllNotes( out SeqCouple note_list ) ;
Description Get all of the notes stored in the server. Output Parameter1
Returns
Example Vesp_Request( "Generic.GetAllNotes", callback, user_data, session, note_list );
Generic.GetCtime
IDL Syntax ORBStatus GetCtime( out string ctime ) ;
Description Return the time in a string in ANSI C format. Output Parameters
Returns
note_list All the notes in the server.
VESP_SUCCESS Method was successful
ctime The time, in ANSI C format.
VESP_SUCCESS Method was successful
Generic.GetEnviron
IDL Syntax ORBStatus GetEnviron( in string name, out string value ) ;
Description Returns the value of the named environment variable. Input Parameters
Output Parameters
Returns
Generic.GetFile
IDL Syntax ORBStatus GetFile( in string file_name, out string file ) ;
Description Retrieve the specified file. Input Parameters
Output Parameters
Returns
name Name of an environment variable.
value Value of the named environment variable.
VESP_SUCCESS Method was successful VESP_BAD_PARAMETER Invalid input parameter
file_name File to retrieve.
file String to hold file.
Generic.GetImpRepository
Issue 1.0 June 2002 23
Generic.GetImpRepository
IDL Syntax ORBStatus GetImpRepository( out string implementation_repository ) ;
Description Load from the selected server a copy of the implementation repository ( i.e., imp file). Output Parameters
Returns
Generic.GetIntRepository
IDL Syntax ORBStatusGetIntRepository( out string interface_ repository) ;
Description Load from the selected server a copy of the interface repository (i.e., pk file). Output Parameters
Returns
Generic.GetMemoryCount
IDL Syntax ORBStatus GetMemoryCount( out unsigned long memory_count ) ;
Description Find out how much memory the server has allocated using Avaya IC memory calls. Output Parameter
Returns
implementation_repository String containing the repository.
VESP_SUCCESS Method was successful
interface_ repository Name of file to hold the repository.
VESP_SUCCESS Method was successful
memory_count How much memory is in use.
Generic.GetNote
IDL Syntax ORBStatus GetNote( in string name, out string value ) ;
Description Get a specific note from a server. Input Parameters
Output Parameters
Returns
Generic.GetServerVersion
IDL Syntax ORBStatus GetServerVersion( out string version ) ;
Description Get the current version of the server. Output Parameters
Returns
name Note to retrieve.
value Contents of note.
VESP_SUCCESS Method was successful
version Version of the server.
Generic.GetStatus
Issue 1.0 June 2002 25
Generic.GetStatus
IDL Syntax ORBStatus GetStatus( out SeqCouple status ) ;
Description Get generic and custom status information from a server. This has a user definable hook so when you build a server you can add your own status information.
Output Parameters
Returns
Example /* Get Server Status */
seq_couple_out = vesp_couple_seq_create();
SCHECK( Vesp_Request_Sync( “TEST.GetStatus”,&ev, session, &reque seq_couple_out ) );
if ( ev._major != NO_EXCEPTION ) {
exit( 1); }
vesp_print_any( TC_IDL_SEQUENCE_Couple, seq_couple_out ); SCHECK( Vesp_Request_Delete( session, request ));
Generic.GetTimet
IDL Syntax ORBStatus GetTimet( out unsigned long timet ) ;
Description Returns the time in seconds since January 1, 1970 in GMT. Output Parameters
Returns
status Current status information in the server.
VESP_SUCCESS Method was successful
timet The time in seconds.
Generic.GetToolkitVersion
IDL Syntax ORBStatus GetToolkitVersion( out string version ) ;
Description Get the toolkit version of a server. Output Parameters
Returns
Generic.GetTracing
IDL Syntax unsigned long GetTracing( void ) ;
Description Get the trace level of the server. Returns Current server trace level
Example trace_level = Vesp_Request_Sync( "TEST.GetTracing ", &ev, session, &request, 1UL );
SCHECK( Vesp_Request_delete( session, request ));
Generic.LoadNewImplementation
IDL Syntax ORBStatus LoadNewImplementation( void ) ;
Description Make the server load a new set of implementations from the Directory. Returns
version The toolkit version of the server.
VESP_SUCCESS Method was successful
Generic.LoseHeap
Issue 1.0 June 2002 27
Generic.LoseHeap
IDL Syntax ORBStatus LoseHeap( void ) ;
Description Make the server lose track of detailed listing of memory that has already been allocated. This is very useful when trying to isolate memory leak problems.
Returns
Generic.MonitorNote
IDL Syntax ORBStatus MonitorNote( in string mode ) ;
Description Not currently used. Returns
Generic.Ping
IDL Syntax ORBStatus Ping( void ) ;
Description Ping the server to see if it is running. This will NOT start a server. Returns
Generic.PrintAll
IDL Syntax ORBStatus PrintAll( void ) ;
Description Print all the internal information about a server into its logfile. Returns
VESP_SUCCESS Method was successful
VESP_SUCCESS Method was successful
VESP_SUCCESS Method was successful
Generic.PrintAllRequests
IDL Syntax ORBStatus PrintAllRequests( void ) ;
Description Print the information about all the outstanding requests of a server into its log file. Returns
Generic.PrintSessionInfo
IDL Syntax ORBStatus PrintSessionInfo( void ) ;
Description Print all the information of all the sessions the server is currently engaged in to the log file. Returns
Generic.PutEnviron
IDL Syntax ORBStatus PutEnviron( in string name_value ) ;
Description Allows you to set an environment variable. The calling session must have process security access. Input Parameters
Returns
VESP_SUCCESS Method was successful
VESP_SUCCESS Method was successful
name_value Name of the environment variable and the value to which it is to be set. The format should be "name=value".
VESP_SUCCESS Method was successful VESP_BAD_PARAMETER Invalid input parameter
Generic.SetTracing
Issue 1.0 June 2002 29
Generic.SetTracing
IDL Syntax ONEWAY SetTracing ( in unsigned long trace_level ) ;
Description Set the trace level of the server. The calling session must have process security access.
Input Parameters
Returns
Example Vesp_Request( "Generic.SetTracing", callback, user_data, session, VESP_Trace_IDL_CODING|VESP_TRACE_FLUSH_LOG);
Generic.ShowHeap
IDL Syntax ORBStatus ShowHeap( void ) ;
Description Print all known allocated memory into the log file. This is very useful in finding memory leaks. Returns
Generic.ShowMemoryCache
IDL Syntax ORBStatus ShowMemoryCache( void ) ;
Description Print the server’s current memory cache information into its logfile. Returns
trace_level Trace level to be set.
VESP_SUCCESS Method was successful
VESP_SUCCESS Method was successful
Generic.ShowNetworkStatus
IDL Syntax ORBStatus ShowNetworkStatus( void ) ;
Description Print all the server’s network information into its logfile. All current TCP/IP information is printed.
Returns
Generic.Shutdown
IDL Syntax ORBStatus Shutdown( in unsigned long time ) ;
Description This method shuts a server down. A shutdown event is sent to all clients assigned to the server. Input Parameters
Returns
Generic.SystemCall
IDL Syntax ORBStatus SystemCall( in string name_value ) ;
Description Use this method to pass a request straight to the operating system. This method is available only on UNIX systems.
Input Parameters
VESP_SUCCESS Method was successful
time Time, in seconds, until the server is shutdown.
VESP_SUCCESS Method was successful
name_value Quoted string containing the command to be executed.
Generic.SystemCall
Issue 1.0 June 2002 31 Returns
VESP_SUCCESS Method was successful VESP_BAD_PARAMETER Bad input parameter
VESP_FAILURE Command failed or method was invoked on a non-Unix server
33
C
HAPTER
3
T
HE
ORB S
ERVER
Overview
The ORB Server controls and maintains servers. Every machine that runs servers must have an ORB Server running. The ORB Server can start, stop, and monitor the status of any server on its machine.
ORB Servers on different machines communicate with each other to find the correct resource for a client request. If the requested server is not on the ORB Server’s machine, the request is routed to the correct ORB Server to handle the request. If a server is not yet started, the ORB Server will start it.
Automatically Starting and Stopping Servers
The ORB Server can automatically start servers on system startup. If the server's autostart configuration parameter is set to true, the server will be automatically started when the ORB Server starts.
Individual servers can be stopped by invoking the Exit() method. Any other attempt results in the ORB Server starting the server again. If a method is invoked on the server after it has exited, the server starts. Automatic starts can be disabled by invoking the TerminateAutostart() method for the given server.
Note: All servers under the control of an ORB Server, including the ORB Server itself, can be stopped using the IC Manager Server Shutdown option, the TerminateVESP() method or the vespadmin utility. Refer to the IC Installation and Configuration Guide for information on the vespadmin utility.
Timing Server Restart Attempts
When a client sends a message to a server and the server is unable to respond, the client requests that the ORB Server start the server. If the server is still unavailable, the client may repeatedly send the request, causing the ORB Server to repeatedly attempt to start the server.
To prevent runaway conditions from occurring, the ORB Server limits the time between server restart attempts. The default is 15 seconds; this can be changed using the SetBackoffTimer() method or the serverstarttimer configuration parameter.
Updating Server Configuration
Whenever the GenericUpdate method is invoked, the ORB Server reads the new server configuration from the directory and generates a new vesp.imp file in the ORB Server home directory. There are several points to consider when updating servers in a WAN environment. n When adding a server in a WAN environment, allow an adequate lapse of time between adding
the server and updating the ORB Server. When a server is added to the Avaya IC environment using Add Server option in IC Manager, a new server record is written in the directory
maintained by the Directory Server. That change is immediately written to the parent directory, but the speed with which the change is relayed out to child directories is configurable. (Refer to
“Configuration,” on page 57 for information on configuration options for the Directory Server.) Once all child directories have been updated, the ORB Server should be updated.
Using the information in the directory, the ORB Server rebuilds the file vesp.imp in its local directory. If all servers are not run from the same directory, vesp.imp must be copied to all of the directories from which servers are run.
n All client machines must also receive the updated copy of vesp.imp. For clients with the Auto load CORBA implementation file option checked in IC Manager, the vesp.imp is
automatically loaded at login. (It is recommended that you check this option.) For other users, the vesp.imp file must be copied to the client machine.
n When adding a new Directory Server in a WAN environment, a copy of the file ds.ffd must be present in the directory in which the Directory Server has been installed before the server can be started. (The install program automatically creates ds.ffd when the first Directory Server is installed.)
Configuration
Issue 1.0 June 2002 35
Configuration
The ORB Server is configured through the IC Manager. Refer to IC Administration Volume 1: Servers & Domainsfor configuration instructions.The following table describes the label used when configuring the ORB Server with IC Manager. The parameter name that is required internally by the server is provided after the label name in parenthesis.
IDL Specification
The following is the Interface Definition Language (IDL) for the ORB Server.
The method names are provided without their interface qualifier, which is ORB. For example, a call to the Resolve() method in the ORB Server takes the form ORB.Resolve().
interface ORBServer : General {
ORBStatus obj_is_ready( in string object_str ); ORBStatus deactivate_obj( in string object_str );
ORBStatus Resolve( in string uuid, out string resolved_uuid ); ORBStatus SetBackoffTimer( in unsigned long timer );
ORBStatus StartServer( in string uuid );
ORBStatus StartServerByBuild( in string uuid, in string group, out string new_uuid );
ORBStatus StopServer( in Identifier uuid ); ORBStatus TerminateAutostart( in string uuid ); ORBStatus TerminateServer( in string uuid ); ORBStatus TerminateAllServers();
void TerminateVESP();
ORBStatus SetServiceProperty( in string uuid, in string name, in string value );
}
Label Description
Server Start Timer (serverstarttimer)
The minimum number of seconds the ORB Server should wait between attempts to start a server. The default is 15 seconds. Server Shutdown Timer
(servershutdowntimer)
The minimum number of seconds the ORB Server should wait for a server to shut down before giving up on it and moving on tp shut down other servers. The default is 180 seconds.
deactivate_obj
IDL Syntax ORBStatus deactivate_obj( in string object_str ) ;
Description This method is not yet implemented. Input Parameters
Returns
Exceptions
GenericUpdate
IDL Syntax ORBStatus GenericUpdate( in string info ) ;
Description This method is inherited from the general methods. It reloads server information from the Directory Server and copies a new copy of the vesp.imp file into its home directory. Input Parameters
Returns
Exceptions None
object_str String identifying the object to be deactivated.
VESP_SUCCESS Request was successful
VESP_NOT_FOUND Service not found
info Information specific to the update.
VESP_SUCCESS Request was successful VESP_BAD_PARAMETER A parameter was invalid
obj_is_ready
Issue 1.0 June 2002 37
obj_is_ready
IDL Syntax ORBStatus obj_is_ready( in string object_str ) ;
Description This method is for internal use only. It is used inside the Vesp_Server_Login function to inform the ORB Server that the server is now ready to accept requests.
Input Parameters
Returns
Exceptions None
Resolve
IDL Syntax ORBStatus Resolve( in string uuid, out string resolved_uuid ) ;
Description For a given server, check to see if the server has been remapped to a different uuid.
Input Parameters
Output Parameters
Returns
Exceptions
object_str String identifying the object.
VESP_SUCCESS Request was successful
uuid Id of server as found in the directory.
resolved_uuid Id of server that will perform task.
VESP_SUCCESS Request was successful
VESP_SERVER_NOT_AVAILABLE Requested service not available VESP_NOT_FOUND Service not found
SetBackoffTimer
IDL Syntax ORBStatus SetBackoffTimer( in unsigned long timer ) ;
Description To prevent runaway conditions from occurring, the ORB Server limits the time between server restart attempts. The default is 15 seconds. The SetBackoffTimer() method allows you to control the amount of time between server restart attempts.
This method requires process control security level.
The serverstarttimer configuration parameter performs the same function. Input Parameters
Returns
Exceptions
SetServiceProperty
IDL Syntax ORBStatus SetServiceProperty( in string uuid, in string name, in string value ) ;
Description This method can be used to temporarily override a server's autostart setting, delay an autostart attempt, enable or disable a server, and print ORB Server activity to a log file.
Note that when the ORB Server is updated, the server's settings will revert to the default set through the IC Manager.
Input Parameters
timer New value of the timer in seconds.
VESP_SUCCESS Request was successful
VESP_NO_PRIVILEGE Insufficient privilege for operation
StartServer
Issue 1.0 June 2002 39 Returns
Exceptions
StartServer
IDL Syntax ORBStatus StartServer( in string uuid ) ;
Description Start a server. Input Parameters
Returns
Exceptions
StartServerByUuid
IDL Syntax ORBStatus StartServerByUuid( in string uuid, in string group, out string new_uuid ) ;
Description Start a server. If the server is not local, ask another ORB Server to start the server. Input Parameters
VESP_SUCCESS Request was successful
VESP_SERVER_NOT_AVAILABLE Requested service not available VESP_NOT_FOUND Service not found
uuid Id of server as found in the directory.
VESP_SUCCESS Request was successful
VESP_SERVER_NOT_AVAILABLE Requested service not available VESP_NOT_FOUND Service not found
uuid Server to start. group Not used.
Output Parameters
Returns
Exceptions
StopServer
IDL Syntax ORBStatus StopServer( in Identifier uuid ) ;
Description Stops a server. Depending on the server's configuration, the server may be automatically restarted by the ORB Server.
Input Parameters
Returns
Exceptions
new_uuid uuid of service started.
VESP_SUCCESS Request was successful
VESP_SERVER_NOT_AVAILABLE It may not be time to restart server yet, as determined by the serverstarttimer configuration parameter
VESP_EXISTS You tried to start the ORB Server
uuid Id of server as found in the directory.
VESP_SUCCESS Request was successful
VESP_SERVER_NOT_AVAILABLE Requested service not available VESP_NOT_FOUND Service not found
TerminateAllServers
Issue 1.0 June 2002 41
TerminateAllServers
IDL Syntax ORBStatus TerminateAllServers( void ) ;
Description Terminate all servers started by this ORB Server. This does not stop the ORB Server. This method requires process control security level.
Returns
Exceptions
TerminateAutostart
IDL Syntax ORBStatus TerminateAutostart( in string uuid ) ;
Description Stop a server from autostarting. After this method is run the server specified will not autostart until the ORB Server is restarted.
This method requires process control security level. Input Parameters
Returns
Exceptions
VESP_SUCCESS Request was successful
VESP_FAILURE Could not stop all servers VESP_NO_PRIVILEGE Insufficient security level
uuid Server for which to disable autostart.
VESP_SUCCESS Request was successful
VESP_FAILURE Could not stop all servers VESP_NO_PRIVILEGE Insufficient security level
TerminateServer
IDL Syntax ORBStatus TerminateServer( in string uuid ) ;
Description Make a specific server exit. This sends the specified server a SIGTERM signal under UNIX. This method requires process control security level.
Input Parameters
Returns
Exceptions
TerminateVESP
IDL Syntax void TerminateVESP( void ) ;
Description Terminate all servers started by this ORB Server including the ORB Server itself. This performs a complete Avaya IC shutdown. Once terminated, the ORB Server has to be restarted on the server platform.
This method requires process control security level.
Note: The vespadmin utility performs this function. Refer to the IC Installation and Configuration Guide for information on the vespadmin utility.
Returns None
Exceptions
uuid uuid of server to exit.
VESP_SUCCESS Request was successful
VESP_FAILURE Could not stop server VESP_NO_PRIVILEGE Insufficient security level
TerminateVESP
Issue 1.0 June 2002 43
Alarms
The following alarms can be generated by the ORB Server.
Alarm Priority Alarm Text Cause/ Recommended Action ServerAutoRestart High Server is starting
at ORB Server start time
A server is configured to autostart, and it has restarted. No corrective action is needed unless you do not want the server to start. ServerCrash High Server has
crashed
A server has terminated for some reason other than an invocation of its Exit method. The ORB Server is aware of this and will restart the server if needed, but the cause of the termination should be investigated. ServerExit Low Server has exited
normally
A server's Exit method has been invoked and the server has stopped.
ServerNotStart High Could not start a server
The ORB Server was unable to start a server. Examine the alarm message and the server log to determine the cause of the failure.
45
C
HAPTER
4
T
HE
A
LARM
S
ERVER
Overview
The Alarm Server allows an Avaya IC client or server to generate alarms when there are problems with the system or a component. The Alarm Server enables client applications to receive these alarms as events, which allows for intervention by systems personnel or software.
The Alarm Server serves two major purposes:
n It receives alarms generated by server and client applications.
n It sends alarms (received as events) to client applications that are interested in obtaining events from one or more sources.
Each Avaya Telephony Server (Avaya TS) and client application maintains its own set of specific alarm messages. Each application that generates alarms sends the alarm to the Alarm Server through the APIs that are automatically available to all client applications (they are registered as part of the Avaya IC environment). The alarm, as well as the name and address of the software process generating the alarm, can be displayed for the system manager.
There are a variety of conditions that can cause an alarm to be generated. For example, if a server cannot perform a requested operation and the reason is environmental, an alarm can be generated. Alarms can also be generated to signal a request that is severely delayed or lost. Other conditions that may be considered less important can be recorded in the application's log file. Alarms are displayed by the IC Manager Alarm Monitor.
The stream of alarms may be captured for integration with other management environments, such as NetView, by creating an Avaya TS that captures and passes events.
Sharing Alarms Across a WAN
Clients assigned to one Alarm Server will receive alarms generated by any other Alarm Server, assuming the Alarm Servers are aware of each other. To make existing Alarm Servers aware of new Alarm Servers added to the system, use the IC Manager Update option on all existing Alarm servers. Refer toIC Administration Volume 1: Servers & Domainsfor information on the Update option.
Configuring the Alarm Server
The Alarm Server is configured through the IC Manager. Refer to IC Administration Volume 1: Servers & Domainsfor configuration instructions. The following table lists the labels used when configuring with IC Manager, followed in parentheses by the parameter name that is required internally by the server.
Predefined Data Elements
The following table describes the predefined data elements associated with the Alarm Server. The Alarm Server adds default values to any Alarm events that do not contain these data elements.
Label Description
Report Alarms (reportflag)
If checked, alarms received by this Alarm Server are saved to the database. Default is checked.
Suppress Alarms (backoff)
Suppresses alarms. Entered in the format: <alarmname> <minutes> <priority>
Once an alarm with the given <alarmname> is sent, additional
<alarmnames> will be discarded for the time specified in <minutes>. After <minutes> have elapsed, the alarm Alarm.RepeatedAlarm is sent with information about the repeated alarm, and the trap is reset.
For example, backoff DS.BadString 15 low would cause the alarm
DS.BadString to be sent once, discarded for 15 minutes, followed by a RepeatedAlarm alarm message with a low priority.
Propagate (propagate)
If checked, alarms received by this Alarm Server are distributed to other Alarm Servers. Default is checked.
Element Description Default
description Description of the alarm. No default. owner An Object string. The identity of the object
(device, person, process, etc.) raising the Alarm.
Generating Alarms
Issue 1.0 June 2002 47
Generating Alarms
When code generates an alarm, it can add any names and values it likes to the alarm event. If it does this for certain key fields (alias, object, sourcetype, group, owner, priority, time, user) the caller's values are believed. If those fields are not set, the Alarm server will try to fill them in based on what it knows about the caller, as follows:
Note: If you add or remove servers, you should issue an Update against the Alarm Server, so it knows to fetch the new server list (in the past, this was only needed if you added or dropped alarm servers.)
time Timestamp, generated in SQL format (year-mm-dd hh:mm:ss).
Date/time when the Alarm Server received the Alarm.
priority Importance of the alarm. Pre-defined levels: emergency high info low
Emergency events are sent to every Alarm Server client even if the client is not monitoring for them explicitly.
low
group Name of the domain associated with the client who raised the original alarm.
No default.
Element Description Default
owner usually set by the caller's toolkit defaults to the session uuid of the calling application. (If set by the toolkit it may be a server uuid instead.)
object usually set by the caller's toolkit, if caller is a server
defaults to the server uuid of the calling application.
If the caller is an agent, it will set user to the caller's loginid.
If the caller is a server, it will set alias to the server's alias, if any, and sourcetype to the server's type (EDU, DS, etc.)
group is filled in with the source's failover group name.
priority defaults to low, time defaults to the current time (generally alarm server local time).
Alarm Monitoring
The Alarm Server sends events to clients that are assigned to or are monitoring an Alarm Server.
Starting and Stopping Alarm Monitoring
Alarm monitoring is started by invoking the Alarm.Assign() and Alarm.Monitor() methods; it is stopped when the Deassign() method is invoked.
The Assign() and Monitor() methods accept a string as an argument. Strings have one of three forms: empty, all, or criteria.
Event Monitoring Criteria
The general syntax of a monitor criteria is:
(name relationalop value) [booleanop...] where relationalop is one of:
“<”, “<=”, “>” and “>=” are not valid with wildcards. and booleanop is one of:
empty ("") No events are monitored. Servers send certain events anyway, but this string specifies the lowest level of event traffic possible while assigned.
all ("*") All events are monitored. Note that some servers may generate a great deal of event traffic. This string is a special case and cannot contain whitespace. criteria An expression that selects some events and rejects others.
= Found. <> Not Found. < Less than.
<= Less than or equal to. > Greater than.
Selection Criteria Wildcards
Issue 1.0 June 2002 49 A sequence of couples is examined one case at a time. For the Found operator (=), a match means that a couple was found within the sequence that had the given name and value. For the Not Found operator, a match means that no Couple in the sequence had the given name and value. The Sequence might have had an instance of the name with a different value, or instances of the value paired with different names, or might not have contained that name at all. Note that all
comparisons are done as strings, and values to be compared against should be enclosed in double quotes to prevent ambiguities and parsing problems. (Within a quoted string, \" means quote and \\ means backslash.) You should also quote names if they contain characters other than letters and digits and underscores.
Examples:
"priority=emergency" "group=xxx"
Selection Criteria Wildcards
Both names and values can include a trailing *, which indicates a limited form of wildcarding, and ?, which provides single character wildcarding.
Wildcard usage is restricted to the <> and = relational operators. Single character wildcards must have a character to match:
Wildcarded names are less useful:
The criteria
(owner = s??) matches records with a 3 digit owner beginning with “s”.
(ow* = srv) matches records that have a field whose name starts with “ow” that happens to hold “srv”.
IDL Specification
The following is the Interface Definition Language (IDL) description of the Alarm Server.
interface Alarm : General {
const unsigned long NOHISTORY = 0x01; const unsigned long NOPROPOGATE = 0x02; ONEWAY Alarm( in event alarmdata );
ONEWAY AlarmNoHistory( in event alarmdata );
ONEWAY AlarmSpecial( in event alarmdata, in unsigned long flags ); ORBStatus Assign( in string criteria );
ORBStatus Monitor( in string criteria ); }
Alarm
IDL Syntax Oneway void Alarm( in event alarmdata ) ;
Description This function takes an event (a name string and a sequence of couples) and passes it to the Alarm Server. The event name should be a concise description that identifies the nature of the alarm. If the event name is empty, the event is discarded.
In the sequence of couples, any names and values may be specified. Certain names have predefined meanings as noted in “Predefined Data Elements,” on page 46. Predefined data elements will default to the values indicated in that section.
You should always specify the description and priority value. It is generally reasonable to allow the others to default.
The function has no return value; it is a oneway request. Input Parameters
Returns None
AlarmNoHistory
Issue 1.0 June 2002 51
AlarmNoHistory
IDL Syntax Oneway void AlarmNoHistory ( in event alarmdata ) ;
Description This function takes an event (a name string and a sequence of couples) and passes it to the Alarm Server. The event name should be a concise description that identifies the nature of the alarm. If the event name is empty, the event is discarded.
In the sequence of couples, any names and values may be specified. Certain names have predefined meanings as noted in “Predefined Data Elements,” on page 46. Predefined data elements will default to the values indicated in that section.
You should always specify the description and priority value. It is generally reasonable to allow the others to default.
The function has no return value; it is a oneway request. Input Parameters
Returns None
Example Event eve;
_IDL_SEQUENCE_Couple cplist[3]; eve.name = “Pop.Explosion”; cplist[0].name = “description”;
cplist[0].value = “Smoke is rising from unit POP01”; cplist[1].name = “priority”;
cplist[1].value = “high”; eve.data._buffer = cplist; eve.data._length = 2; eve.data._maximum = 0;
status = Vesp_Request( “Alarm.AlarmNoHistory”, callback, user_data, id, &eve );
AlarmSpecial
IDL Syntax Oneway AlarmSpecial( in event alarmdata, in unsigned long flags ) ;
Description This function can only be used by other Alarm Servers. Returns
alarmdata Sequence of values associated with the alarm.
VESP_SUCCESS Request was successful VESP_ERROR Request failed
Assign
IDL Syntax ORBStatus Assign( in string criteria ) ;
Description Creates a session with the Alarm Server. When a session is created, events are sent to the Avaya IC client. This enables the Alarm Server to send events to a process, and enables a process to specify events in which it is interested.
The monitor criteria is a string that determines which alarms the process will receive as events. The simplest case is “*”, which requests all alarms. No matter what criteria is specified, clients calling this function receive all alarms with priority=Emergency. The simplest criteria, to receive only system disasters, is "". In general, you can specify events to be received based on the names and values of the _IDL_SEQUENCE_Couple within each alarm event.
It is an error to attempt to assign twice; you must Deassign() before you can Assign again. Should you want to change the monitor criteria, use Alarm.Monitor() instead of a Deassign(), Assign() sequence.
Clients assigned to one Alarm Server will receive alarms generated by any other Alarm Server, assuming the Alarm Servers are aware of each other. Refer to “Sharing Alarms Across a WAN,” on page 45 for more information.
Input Parameters
Returns
Exceptions
Example Monitor all servers and clients
status = Vesp_Assign_Request( "Alarm.Assign", callback, user_data, event_callback, id, "*");
criteria Expression that selects the alarms to be received. Refer to “Event Monitoring Criteria,” on page 48 for information regarding changing monitor criteria strings.
VESP_SUCCESS Request was successful
Deassign
Issue 1.0 June 2002 53
Deassign
IDL Syntax ORBStatus Deassign( void ) ;
Description Destroys a session with the Alarm Server. When a session is deassigned, the flow of events from the Alarm Server to the client will cease.
This function undoes the effect of an Alarm.Assign(). Other than events that are already en route, the client no longer receives events from the Alarm Server unless it performs another Assign(). It is not an error to send a Deassign() without a previous Assign().
Returns
Monitor
IDL Syntax ORBStatus Monitor( in string criteria ) ;
Description This function can be used after a client has Assigned to the Alarm Server. It allows the client to change the types of alarms it receives, and is more efficient than doing a Deassign(), Assign() sequence of calls. It takes the same syntax as an Alarm.Assign().
Input Parameters
Returns
Example Monitor only important alarms.
status = Vesp_Request( "Alarm.Monitor", callback, user_data, event_callback, id, "priority <> Low");
VESP_SUCCESS Request was successful VESP_ERROR Request failed
criteria Expression that selects the alarms to be received. Refer to “Event Monitoring Criteria,” on page 48 for information on selection criteria.
VESP_SUCCESS Change in Assign criteria succeeded VESP_ERROR Attempt failed; the argument is invalid
Alarms
The following alarm is generated by the Alarm Server.
Alarm Priority Alarm Text Cause/Recommended Action RepeatedAlarm Varies. name <name of
repeated alarm> count <number of repeated alarms, including first> since <time_t of first alarm>
priority the value of <priority> fromthe config variable
owner the string “Alarm”
This alarm is generated when the
backoff configuration
parameter has been set and an alarm is being repeated. Refer to
“Configuring the Alarm Server,” on page 46 for information about the backoff parameter.
