Avaya Interaction Center Release 6.0 Core Services Programmer s Guide

Avaya Interaction Center Release 6.0 Core Services Programmer s Guide DXX-1024-02 Issue 1.0 June 2002

2002, Avaya Inc. All Rights Reserved Notice 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 telecommunications 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 malicious 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, subcontractor, 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) equipment 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 intrusion should occur, it could result in a variety of losses to your company (including 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 equipment rests with you - an Avaya customer's system administrator, your telecommunications 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 peers should carefully program and configure your: Avaya-provided telecommunications systems and their interfaces Avaya-provided software applications, as well as their underlying hardware/software platforms and interfaces Any other equipment networked to your Avaya products. Avaya National Customer Care Center Avaya provides a telephone number for you to use to report problems or to ask questions about your contact center. The support telephone number is 1-800-242-2121. Ordering Information Avaya Publications Center Voice: +1 800 457 1235 International Voice: 410 568 3680 Fax: +1 800 457 1764 International Fax: 410 891 0207 Email: totalware@gwsmail.com 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 appropriate 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 licensors: 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 developed by Sun Microsystems, Inc. In3D is a trademark of Visual Insights, Inc. InstallShield is a registered trademark and service mark of InstallShield Software Corporation in the United States and/or other countries. ORBacus is a trademark of IONA Technologies PLC. Formula One is a licensed trademark and Tidestone Technologies, Inc. Visual Components, First Impression, and VisualSpeller are registered trademarks of Tidestone Technologies, Inc. JRun is a trademark of Macromedia, Inc. in the United States and/or other countries. Intervoice is a registered trademark of Intervoice-Brite, Inc. UNIX is a registered trademark of The Open Group in the United States and other countries. Acrobat is a registered trademark of Adobe Systems. Other product and brand names are trademarks of their respective owners. Acknowledgment This document was written by the CRM Information Development group of Avaya

CONTENTS BEFORE YOU BEGIN........................................ 7 1 CORE SERVICES OVERVIEW................................. 11 Core Services s................................................. 11 CORBA Implementation................................................... 12 2 GENERIC SERVER METHODS................................. 13 IDL Specification......................................................... 13 3 THE ORB SERVER......................................... 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 THE ALARM SERVER....................................... 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 3

Contents 5 THE DIRECTORY SERVER................................... 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 THE DATA CONNECTOR SERVER........................... 105 Overview.............................................................. 105 Data Server Architecture.............................................. 106 Single Database Login................................................ 106 Client Authentication................................................. 107 Connection Pool Concepts............................................. 107 Shared Server Features................................................ 107 Configuration................................................. 108 Connecting to the Data Server.............................................. 109 Special Considerations for DB2 on Windows NT/2000....................... 109 4 Core Services Programmer s Guide

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 AVAYA IC ORB ROUTINES................................. 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 AVAYA IC TOOLKIT FUNCTIONS............................. 127 Function s.................................................... 127 INDEX................................................. 215 Issue 1.0 June 2002 5

Contents 6 Core Services Programmer s Guide

BEFORE YOU BEGIN Typographical Conventions This guide uses the following font conventions: Font Type code italics Meaning This font signifies commands, information that you enter into the computer, or information contained in a file on your computer. 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. 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. 7

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: M M Logging in to the Avaya Technical Support Web site (http://www.avaya.com/support/qq). 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): M Toll free in the U.S. only: 1-888-TECH-SPT (1-888-832-4778) M Direct line for international and domestic calls: 512-425-2201 M Direct line for faxes: 512-719-8225 M Sending email with your question or problem to crmsupport@avaya.com. 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.com for further information. Product Documentation Readme File 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. 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. Electronic Documentation The electronic documentation (in PDF or HTML format) for each Avaya Interaction Center product is installed automatically with the program. Electronic documentation for the entire Avaya product suite is included on the product CD-ROM and the documentation CD-ROM. You can also view the documentation set online at http://www.avayadocs.com. 8 Core Services Programmer s Guide

Educational Services 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: Through the web at http://www.avaya-learning.com Over the telephone at 800-288-5327 (within the U.S.) +001 303-406-6089 (outside of the U.S.) Through email at Avaya.U.Helpdesk@accenture.com Issue 1.0 June 2002 9

10 Core Services Programmer s Guide

CHAPTER 1 CORE SERVICES OVERVIEW 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 s The core services described in this manual are: ORB Server Alarm Server Directory Server Data Connector Server The ORB (Object Request Broker) Server operates behind the scenes to ensure that Avaya IC services are available to clients in a truly locationindependent 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. The Alarm Server is called by clients and servers to report an alarm condition. 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. The Data Connector Server allows developers to create databaseindependent 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. 11

Chapter 1 Core Services Overview 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. 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. 12 Core Services Programmer s Guide

CHAPTER 2 GENERIC SERVER METHODS 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 ); ONEWAY FlushLog(); 13

Chapter 2 Generic Server Methods 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 ); } 14 Core Services Programmer s Guide

Generic.Crash Generic.Crash IDL Syntax ONEWAY Crash( ) ; Makes the server crash. The server executes the function abort(). Example You must have manager level security to access this method, and the calling session must have process security access. None status = Vesp_Request( "Generic.Crash", callback, user_data, session); Generic.CreateNote IDL Syntax ORBStatus CreateNote( in string mode, in string name, in string value ) ; Create a note. All clients assigned to this server will receive an event with the name Note. Input mode name value Unused, empty. Name of note The text of the note. Method was successful Example Vesp_Request( "Generic.CreateNote ", callback, user_data, session, "", "mynote", "mynote_value" ); String event syntax: [Generic.Note.event((1,1,( "mynote", "mynote_value")))] Issue 1.0 June 2002 15

Chapter 2 Generic Server Methods Generic.CreateUUID IDL Syntax ORBStatus CreateUUID( in Identifier host, in Identifier service, in string version, in string max_users, out string uuid_str ) ; Create a UUID string from its component information. Input host service version max_users The name of the host machine. The name of the service (server) whose port will be associated with the UUID. Reserved; not currently used. Reserved; not currently used. Output uuid_str A completed UUID in string form, based on the input information. Method was successful Generic.Deassign IDL Syntax ORBStatus Deassign( void ) ; 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. VESP_BAD_SESSION VESP_FAILURE Session is invalid Request has failed Example Vesp_Deassign_Request( "Generic.Deassign", &ev, NULL, OUL, session ); 16 Core Services Programmer s Guide

Generic.DecodeUUID 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 ) ; Decode a UUID string into its pieces. Input uuid_str The UUID, in string form, to be decoded. Output uuid_str host service time_high time_low version max_users The UUID, in string form, to be decoded. The name of the host machine. The name of the service (server) whose port is associated with the UUID. The time (from the ANSI C time() function) the UUID was created. A sequence number used to distinguish between UUIDs created in the same second by the same object. Version information from the UUID. Max user information from the UUID. Method was successful Generic.DeleteAllNotes IDL Syntax ORBStatus DeleteAllNotes( void ) ; Delete all the notes stored in the server. Method was successful Example Vesp_Request("Generic.DeleteAllNotes", NULL, OUL, session ); Issue 1.0 June 2002 17

Chapter 2 Generic Server Methods Generic.DeleteNote IDL Syntax ORBStatus DeleteNote( in string name ) ; Delete note named. Input name Name of note to delete. VESP_NOT_FOUND Service not found Method was successful Example Vesp_Request("Generic.DeleteNote", NULL, OUL, session, "my_note" ); Generic.DisableServer IDL Syntax ORBStatus DisableServer( in unsigned long time ) ; Disable the named server. The server will reject assign requests. Input time Number of seconds until the server is disabled. Method was successful 18 Core Services Programmer s Guide

Generic.EnableServer Generic.EnableServer IDL Syntax ORBStatus EnableServer( in unsigned long time ) ; Enable a server previously disabled with the DisableServer() method. Input time The length of time until the server is enabled. Method was successful Generic.Exit IDL Syntax ONEWAY Exit( in unsigned long exit_code ) ; : 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 exit_code The exit code with which the server will terminate. Example None Vesp_Request( "Generic.Exit", callback, user_data, session); Generic.FlushLog IDL Syntax ONEWAY FlushLog( void) ; Make the server flush all buffered log information to the log file. None Example Vesp_Request( "Generic.FlushLog ", callback, user_data, session); Issue 1.0 June 2002 19

Chapter 2 Generic Server Methods Generic.GenericUpdate IDL Syntax ORBStatus GenericUpdate( in string info ) ; 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: TS ORB Server Load new user information from the Directory. Load all new server configuration from the Directory and create a new implementation repository. Input info Information specific to the update. Method was successful Example Implementation Example Vesp_Request( "ORBServer.GenericUpdate", callback, user_data, session, ""); ORBStatus ORBServer_GenericUpdate( Object obj, Environment *ev, char *info ) { } EVCHECK(Vesp_Reload_Imp( object_gbl )); return ( ) /* 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)); 20 Core Services Programmer s Guide

Generic.GetAllNotes Generic.GetAllNotes IDL Syntax ORBStatus GetAllNotes( out SeqCouple note_list ) ; Get all of the notes stored in the server. Output Parameter1 note_list All the notes in the server. Method was successful Example Vesp_Request( "Generic.GetAllNotes", callback, user_data, session, note_list ); Generic.GetCtime IDL Syntax ORBStatus GetCtime( out string ctime ) ; Return the time in a string in ANSI C format. Output ctime The time, in ANSI C format. VESP_BAD_PARAMETER Method was successful ctime not available to this implementation Issue 1.0 June 2002 21

Chapter 2 Generic Server Methods Generic.GetEnviron IDL Syntax ORBStatus GetEnviron( in string name, out string value ) ; the value of the named environment variable. Input name Name of an environment variable. Output value Value of the named environment variable. VESP_BAD_PARAMETER Method was successful Invalid input parameter Generic.GetFile IDL Syntax ORBStatus GetFile( in string file_name, out string file ) ; Retrieve the specified file. Input file_name File to retrieve. Output file String to hold file. Method was successful 22 Core Services Programmer s Guide

Generic.GetImpRepository Generic.GetImpRepository IDL Syntax ORBStatus GetImpRepository( out string implementation_repository ) ; Load from the selected server a copy of the implementation repository ( i.e., imp file). Output implementation_repository String containing the repository. Method was successful Generic.GetIntRepository IDL Syntax ORBStatusGetIntRepository( out string interface_ repository) ; Load from the selected server a copy of the interface repository (i.e., pk file). Output interface_ repository Name of file to hold the repository. Method was successful Generic.GetMemoryCount IDL Syntax ORBStatus GetMemoryCount( out unsigned long memory_count ) ; Find out how much memory the server has allocated using Avaya IC memory calls. Output Parameter memory_count How much memory is in use. Method was successful Issue 1.0 June 2002 23

Chapter 2 Generic Server Methods Generic.GetNote IDL Syntax ORBStatus GetNote( in string name, out string value ) ; Get a specific note from a server. Input name Note to retrieve. Output value Contents of note. Method was successful Generic.GetServerVersion IDL Syntax ORBStatus GetServerVersion( out string version ) ; Get the current version of the server. Output version Version of the server. Method was successful 24 Core Services Programmer s Guide

Generic.GetStatus Generic.GetStatus IDL Syntax ORBStatus GetStatus( out SeqCouple status ) ; 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 status Current status information in the server. Method was successful 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 ) ; the time in seconds since January 1, 1970 in GMT. Output timet The time in seconds. Method was successful Issue 1.0 June 2002 25

Chapter 2 Generic Server Methods Generic.GetToolkitVersion IDL Syntax ORBStatus GetToolkitVersion( out string version ) ; Get the toolkit version of a server. Output version The toolkit version of the server. Method was successful Generic.GetTracing IDL Syntax unsigned long GetTracing( void ) ; Example Get the trace level of the server. Current server trace level trace_level = Vesp_Request_Sync( "TEST.GetTracing ", &ev, session, &request, 1UL ); SCHECK( Vesp_Request_delete( session, request )); Generic.LoadNewImplementation IDL Syntax ORBStatus LoadNewImplementation( void ) ; Make the server load a new set of implementations from the Directory. Method was successful 26 Core Services Programmer s Guide

Generic.LoseHeap Generic.LoseHeap IDL Syntax ORBStatus LoseHeap( void ) ; 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. Method was successful Generic.MonitorNote IDL Syntax ORBStatus MonitorNote( in string mode ) ; Not currently used. Method was successful Generic.Ping IDL Syntax ORBStatus Ping( void ) ; Ping the server to see if it is running. This will NOT start a server. Method was successful Generic.PrintAll IDL Syntax ORBStatus PrintAll( void ) ; Print all the internal information about a server into its logfile. Method was successful Issue 1.0 June 2002 27

Chapter 2 Generic Server Methods Generic.PrintAllRequests IDL Syntax ORBStatus PrintAllRequests( void ) ; Print the information about all the outstanding requests of a server into its log file. Method was successful Generic.PrintSessionInfo IDL Syntax ORBStatus PrintSessionInfo( void ) ; Print all the information of all the sessions the server is currently engaged in to the log file. Method was successful Generic.PutEnviron IDL Syntax ORBStatus PutEnviron( in string name_value ) ; Allows you to set an environment variable. The calling session must have process security access. Input name_value Name of the environment variable and the value to which it is to be set. The format should be "name=value". VESP_BAD_PARAMETER VESP_FAILURE Method was successful Invalid input parameter Environment variable could not be set 28 Core Services Programmer s Guide

Generic.SetTracing Generic.SetTracing IDL Syntax ONEWAY SetTracing ( in unsigned long trace_level ) ; Set the trace level of the server. The calling session must have process security access. Input trace_level Trace level to be set. Method was successful Example Vesp_Request( "Generic.SetTracing", callback, user_data, session, VESP_Trace_IDL_CODING VESP_TRACE_FLUSH_LOG); Generic.ShowHeap IDL Syntax ORBStatus ShowHeap( void ) ; Print all known allocated memory into the log file. This is very useful in finding memory leaks. Method was successful Generic.ShowMemoryCache IDL Syntax ORBStatus ShowMemoryCache( void ) ; Print the server s current memory cache information into its logfile. Method was successful Issue 1.0 June 2002 29

Chapter 2 Generic Server Methods Generic.ShowNetworkStatus IDL Syntax ORBStatus ShowNetworkStatus( void ) ; Print all the server s network information into its logfile. All current TCP/IP information is printed. Method was successful Generic.Shutdown IDL Syntax ORBStatus Shutdown( in unsigned long time ) ; This method shuts a server down. A shutdown event is sent to all clients assigned to the server. Input time Time, in seconds, until the server is shutdown. Method was successful Generic.SystemCall IDL Syntax ORBStatus SystemCall( in string name_value ) ; Use this method to pass a request straight to the operating system. This method is available only on UNIX systems. Input name_value Quoted string containing the command to be executed. 30 Core Services Programmer s Guide

Generic.SystemCall VESP_BAD_PARAMETER VESP_FAILURE Method was successful Bad input parameter Command failed or method was invoked on a non-unix server Issue 1.0 June 2002 31

Chapter 2 Generic Server Methods 32 Core Services Programmer s Guide

CHAPTER 3 THE ORB SERVER 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. 33

Chapter 3 The ORB Server 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. 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. 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. 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.) Directing Requests to a Specific Server When a method is invoked using a server's interface name (interface_name.method_name), the request is serviced by the first server listed with that interface name. To direct the request to a specific server, use the server's UUID or alias name in the method invocation. #UUID.method_name or *alias.method_name 34 Core Services Programmer s Guide

Configuration Configuration The ORB Server is configured through the IC Manager. Refer to IC Administration Volume 1: Servers & Domains for 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. Label Server Start Timer (serverstarttimer) Server Shutdown Timer (servershutdowntimer) The minimum number of seconds the ORB Server should wait between attempts to start a server. The default is 15 seconds. 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. 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 ); } Issue 1.0 June 2002 35

Chapter 3 The ORB Server deactivate_obj IDL Syntax ORBStatus deactivate_obj( in string object_str ) ; This method is not yet implemented. Input object_str String identifying the object to be deactivated. Exceptions VESP_NOT_FOUND Service not found GenericUpdate IDL Syntax ORBStatus GenericUpdate( in string info ) ; 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 info Information specific to the update. VESP_BAD_PARAMETER VESP_FILE_DOES_NOT_EXIST A parameter was invalid Could not open vesp.imp for write Exceptions None 36 Core Services Programmer s Guide

obj_is_ready obj_is_ready IDL Syntax ORBStatus obj_is_ready( in string object_str ) ; 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 object_str String identifying the object. Exceptions None Resolve IDL Syntax ORBStatus Resolve( in string uuid, out string resolved_uuid ) ; For a given server, check to see if the server has been remapped to a different uuid. Input uuid Id of server as found in the directory. Output resolved_uuid Id of server that will perform task. Exceptions VESP_SERVER_NOT_AVAILABLE VESP_NOT_FOUND Requested service not available Service not found Issue 1.0 June 2002 37

Chapter 3 The ORB Server SetBackoffTimer IDL Syntax ORBStatus SetBackoffTimer( in unsigned long timer ) ; 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 timer New value of the timer in seconds. Exceptions VESP_NO_PRIVILEGE Insufficient privilege for operation SetServiceProperty IDL Syntax ORBStatus SetServiceProperty( in string uuid, in string name, in string value ) ; 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 uuid name and value Id of server as found in the directory. and values: Name Value autostart true or false autostartdelay in seconds, default is 5 serverenable true or false print all 38 Core Services Programmer s Guide

StartServer Exceptions VESP_SERVER_NOT_AVAILABLE VESP_NOT_FOUND Requested service not available Service not found StartServer IDL Syntax ORBStatus StartServer( in string uuid ) ; Start a server. Input uuid Id of server as found in the directory. Exceptions VESP_SERVER_NOT_AVAILABLE VESP_NOT_FOUND Requested service not available Service not found StartServerByUuid IDL Syntax ORBStatus StartServerByUuid( in string uuid, in string group, out string new_uuid ) ; Start a server. If the server is not local, ask another ORB Server to start the server. Input uuid group Server to start. Not used. Issue 1.0 June 2002 39

Chapter 3 The ORB Server Output new_uuid uuid of service started. Exceptions VESP_SERVER_NOT_AVAILABLE VESP_EXISTS It may not be time to restart server yet, as determined by the serverstarttimer configuration parameter You tried to start the ORB Server StopServer IDL Syntax ORBStatus StopServer( in Identifier uuid ) ; Stops a server. Depending on the server's configuration, the server may be automatically restarted by the ORB Server. Input uuid Id of server as found in the directory. Exceptions VESP_SERVER_NOT_AVAILABLE VESP_NOT_FOUND Requested service not available Service not found 40 Core Services Programmer s Guide

TerminateAllServers TerminateAllServers IDL Syntax ORBStatus TerminateAllServers( void ) ; Terminate all servers started by this ORB Server. This does not stop the ORB Server. This method requires process control security level. Exceptions VESP_FAILURE VESP_NO_PRIVILEGE Could not stop all servers Insufficient security level TerminateAutostart IDL Syntax ORBStatus TerminateAutostart( in string uuid ) ; 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 uuid Server for which to disable autostart. Exceptions VESP_FAILURE VESP_NO_PRIVILEGE Could not stop all servers Insufficient security level Issue 1.0 June 2002 41

Chapter 3 The ORB Server TerminateServer IDL Syntax ORBStatus TerminateServer( in string uuid ) ; Make a specific server exit. This sends the specified server a SIGTERM signal under UNIX. This method requires process control security level. Input uuid uuid of server to exit. Exceptions VESP_FAILURE VESP_NO_PRIVILEGE Could not stop server Insufficient security level TerminateVESP IDL Syntax void TerminateVESP( void ) ; 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. Exceptions None VESP_FAILURE VESP_NO_PRIVILEGE Could not stop all servers Insufficient security level 42 Core Services Programmer s Guide

TerminateVESP 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 ServerCrash High Server has crashed ServerExit Low Server has exited normally ServerNotStart High Could not start a server A server is configured to autostart, and it has restarted. No corrective action is needed unless you do not want the server to start. 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. A server's Exit method has been invoked and the server has stopped. The ORB Server was unable to start a server. Examine the alarm message and the server log to determine the cause of the failure. Issue 1.0 June 2002 43

Chapter 3 The ORB Server 44 Core Services Programmer s Guide

CHAPTER 4 THE ALARM SERVER 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: It receives alarms generated by server and client applications. 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 to IC Administration Volume 1: Servers & Domains for information on the Update option. 45

Chapter 4 The Alarm Server Configuring the Alarm Server The Alarm Server is configured through the IC Manager. Refer to IC Administration Volume 1: Servers & Domains for 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. Label Report Alarms (reportflag) Suppress Alarms (backoff) If checked, alarms received by this Alarm Server are saved to the database. Default is checked. 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. 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. Element Default description of the alarm. No default. owner An Object string. The identity of the object (device, person, process, etc.) raising the Alarm. Object making the request. 46 Core Services Programmer s Guide

Generating Alarms Element Default time priority group Timestamp, generated in SQL format (yearmm-dd hh:mm:ss). 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. Name of the domain associated with the client who raised the original alarm. Date/time when the Alarm Server received the Alarm. low No default. 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: Element 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 group usually set by the caller's toolkit, if caller is a server is filled in with the source's failover group name. 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.) priority defaults to low, time defaults to the current time (generally alarm server local time). 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.) Issue 1.0 June 2002 47

Chapter 4 The Alarm Server 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. empty ("") all ("*") criteria No events are monitored. Servers send certain events anyway, but this string specifies the lowest level of event traffic possible while assigned. 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. An expression that selects some events and rejects others. Event Monitoring Criteria The general syntax of a monitor criteria is: (name relationalop value) [booleanop...] where relationalop is one of: = Found. <> Not Found. < Less than. <= Less than or equal to. > Greater than. >= Greater than or equal to. <, <=, > and >= are not valid with wildcards. and booleanop is one of: & And. Both relations must be true. Or. True if either relation or both is true. == Equivalent. True if both relations are true or both are false. ^ Exclusive Or. True if and only if one relation is true. 48 Core Services Programmer s Guide

Selection Criteria Wildcards 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: (owner = s??) matches records with a 3 digit owner beginning with s. Wildcarded names are less useful: (ow* = srv) matches records that have a field whose name starts with ow that happens to hold srv. The criteria (*=*) selects everything. "*" has the same effect. Issue 1.0 June 2002 49

Chapter 4 The Alarm Server 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 ) ; 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 alarmdata Sequence of values associated with the alarm. None 50 Core Services Programmer s Guide

AlarmNoHistory AlarmNoHistory IDL Syntax Oneway void AlarmNoHistory ( in event alarmdata ) ; 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 alarmdata Sequence of values associated with the alarm. Example None 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 ) ; This function can only be used by other Alarm Servers. VESP_ERROR Request failed Issue 1.0 June 2002 51

Chapter 4 The Alarm Server Assign IDL Syntax ORBStatus Assign( in string criteria ) ; 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 criteria Expression that selects the alarms to be received. Refer to Event Monitoring Criteria, on page 48 for information regarding changing monitor criteria strings. Exceptions VESP_ERROR Bad assign criteria Example Monitor all servers and clients status = Vesp_Assign_Request( "Alarm.Assign", callback, user_data, event_callback, id, "*"); 52 Core Services Programmer s Guide

Deassign Deassign IDL Syntax ORBStatus Deassign( void ) ; 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(). VESP_ERROR Request failed Monitor IDL Syntax ORBStatus Monitor( in string criteria ) ; 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 criteria Expression that selects the alarms to be received. Refer to Event Monitoring Criteria, on page 48 for information on selection criteria. VESP_ERROR Change in Assign criteria succeeded Attempt failed; the argument is invalid Example Monitor only important alarms. status = Vesp_Request( "Alarm.Monitor", callback, user_data, event_callback, id, "priority <> Low"); Issue 1.0 June 2002 53

Chapter 4 The Alarm Server 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> 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. priority the value of <priority> from the config variable owner the string Alarm 54 Core Services Programmer s Guide

CHAPTER 5 THE DIRECTORY SERVER Overview The Avaya IC Directory Server (DS) provides a common directory of resources that are available under Avaya IC. Directory entries include users, Avaya Computer Telephony Servers, telephony resources, and other logical and physical elements. Each entry in the directory contains information such as the resource s name, phone number, location, and configuration. The DS also stores custom tables created with IC Manager. Refer to IC Administration Volume 1: Servers & Domains for a description of custom tables. Use of the DS by Client Applications The directory maintained by the Directory Server is a network resource shared by all applications. A client or server logs in to the IC system by invoking a DS.Login request. At the time this request is invoked, there is no information available to identify the group of the client or domain of the server making the request, so it is assumed the requester is in the Default group. The implication of this is that failover for all vesp login requests will fail over according to the rules specified for the Default domain, regardless of the actual failover configuration of the requester. Directory information is generally loaded at client startup. The directory is then used by the client to access information about network resources. For example, when a caller using a voice response application dials '0' to transfer to an agent: 1 The application chooses an agent or queue by retrieving the directory entries with skill sets matching the caller's profile. 2 The application requests a coordinated voice/data transfer to the chosen agent or queue by calling the Avaya TS using the directory information. The Directory Server eliminates the need for the application to provide network addresses (TCP/IP addresses, telephone numbers, etc.) for resources. If telephone numbers or network addresses of resources change, no change is required in the application. Directory maintenance is centralized. Avaya IC does not automatically update the client s directory information after client startup. Clients cannot log in if there is not a Directory Server on the system. 55

Chapter 5 The Directory Server Wide Area Network Considerations Multiple Directory Servers installed over a wide area network (WAN) share one common directory, a copy of which exists in each DS. One DS must be in charge of ensuring that all copies of the directory are synchronized. This DS is referred to as the parent. Changes made at any site are automatically made in the parent directory and are reflected throughout the system. (If there is only one Directory Server, it is automatically considered the parent.) The parent Directory Server is specified through the IC Manager. For information on specifying a parent Directory Server, refer to IC Administration Volume 1: Servers & Domains. Note the following: If the parent Directory Server goes down, the directory becomes read-only until a new parent is selected through the IC Manager. When a Directory Server starts up, it copies the most current version of the directory from the parent directory. If there is no parent when a DS starts up, it uses its last copy of the directory file and begins activities in read-only mode until a parent is restarted or reassigned. If a client s DS goes down, the ORB Server automatically provides the client with an alternative DS if the original DS cannot be restarted by the ORB Server. The speed with which changes in the parent directory are relayed out to child directories is configurable. Refer to Configuration, on page 57 for information on the Directory Server's configuration options. When adding a new Directory Server in a WAN (wide area network) environment, do the following: M Using IC Manager, create the new Directory Server. Make sure the new DS s host machine is running an ORB Server. M Backup the original DS. M Copy the backup directory file from the first DS s host machine to the new DS s host machine. M Using IC Manager, start the new DS. Multiple Directory Servers can be run on the same system, however each DS must be given its own directory to run in, where it maintains its own copy of the database (ds.ffd). Fatal errors can result if two DS servers attempt to share a copy of the database. 56 Core Services Programmer s Guide

Overview Configuration The Directory Server is configured through the IC Manager. Refer to IC Administration Volume 1: Servers & Domains for configuration instructions. The following table lists the label used when configuring with IC Manager, followed in parentheses by the parameter name as it is required internally by the server. Label IC Data Source (dbconnection) Is Parent (parent) Backup (backup) Restore (restore) First update lag (bufferupdates) The name of the file, created in IC Designer, that contains connection information between an Avaya Business Application and its database. If checked, assigns parent status to this Directory Server. To make a backup copy of the directory, enter the name of a backup file to be created. An extension of.ffd will automatically be appended. Click the Start button to create the file in the server s home directory. To restore the directory from a previously created backup directory file, enter the name of the backup file and click the Start button. The number of seconds the DS will wait before sending updates to the first of its children. During normal operation, a setting of 0 is recommended. (A small delay occurs automatically.) When performing a Batch User Add, a setting between 10 and 90 seconds is recommended. The default setting is 0; there is no maximum value. If this value is greater than 0, the Advanced tab information will contain a couple with the name "PropagationDelay" and a value equal to the current bufferupdates setting. Succeeding update lag (childlag) The number of seconds the DS will pause before sending an update to the next child. During normal operation, a setting of 0 or 1 is recommended. When performing a Batch User Add, a pause of 5 seconds is recommended. The default setting is 0; there is no maximum value. If this value is greater than 0, the Advanced tab information will contain a couple with the name LagBetweenChildren and a value equal to the current childlag setting. Issue 1.0 June 2002 57

Chapter 5 The Directory Server Usage and Performance The Directory Server is intended to hold a small number of records and is designed for fast response time. The size of the directory is limited to available memory. It is not meant to play the role of a corporate directory (for instance, an X.500 service). When installed over a WAN, a DS should be installed at each physically separate location. A parent directory must be specified through the IC Manager. Generic configurations for the Directory Server can be difficult to determine. Typically there are machine dependencies to be considered. The following environmental factors can impact the performance of the Directory Server and any client application it may service. The overall number of records in the directory. The DS must search through all existing records to locate a specific record. The size of the records in the directory. Record size is determined by the total number of name/value pair characters. The overall number of records in the directory combined with the size of those records determines the amount of memory the DS must use. The process memory limit and amount of physical memory available on the machine on which the DS resides. The size of the directory is limited to the physical memory available on the machine on which the DS resides. Memory limitations will dictate the amount of directory information that is available in actual memory; the remaining information will be paged out into virtual memory. When the directory does not fit in actual memory, it becomes dramatically slower. Should the directory grow to exceed the Directory Server's memory limit, the DS will cease to function. The total character length of name/value pairs contained in records. If you have created tables in the DS, note that the total character length of the names and values contained in a table should not exceed 65,000 characters. (A table is stored as a record in the directory.) The number of Directory Servers in the system. When there are multiple Directory Servers, performance is impacted as follows: M There will be a significant additional memory cost associated with sending update messages between the Directory Servers. Multiple Directory Servers will halve the maximum directory size. M There is an overall slowdown associated with a multiple Directory Server configuration which is caused by the update process. M Although the speed of a specific method will not be affected, when the directory is being updated, network traffic between Directory Servers is increased and may impact the speed of other methods (updates or queries) being invoked at the same time. 58 Core Services Programmer s Guide

Directory Structure Sizing Recommendations For a simple non-wan UNIX system, no more than 6000 records with an average size of less than 400 characters should be maintained. In a WAN, the number of records should not exceed 3000. Maintaining a directory in excess of this size will expose you to the risk of crashing the Directory Server. For performance reasons, please consider the following configuration as a potential maximum size or the Directory Server: A maximum of 5,000 users 500 servers 500 additional records (tables / other additions) Note: Sizing recommendations are based on the behavior of a Directory Server running on a 32- bit system with a 16 meg process memory limit. Directory Structure Database Schema Data Structure The Directory Server uses a sequential ( flat ) file structure. When the server is not running, the data exists as a simple formatted text file. When the server is started, this file is parsed and all of its data is read into the server's memory. When the server is stopped, the data file is rewritten. For every record, the DS creates a key, creation_timestamp, and update_time field. All other fields are defined by client processes. The Directory Server database has no fixed schema. The directory contains information of various kinds, such as: Names of individuals and queues Skill sets Phone numbers Addressing information Password and security information The directory consists of one table containing multiple records; each record can contain one or more fields (name/value pairs), in addition to the three fields created by the DS. There does not need to be a relationship between the fields in one record and the next. Issue 1.0 June 2002 59

Chapter 5 The Directory Server The following illustrates three records. Record 1 Field Name name type Value Nancy Jones per phone 8005551234 Record 2 Field Name name type uuid Value Telephony srv uuid of the Avaya TS Record 3 Field Name name type text Value Script1 rules scripting rules The following restrictions apply to field names: They cannot start with a period They cannot be zero length They can only contain numbers, letters, period, or an underbar (_) Field values can be any string, even one with zero length. Avaya IC Defined Records The following sections describe server records and user records, which are created by the IC Manager. 60 Core Services Programmer s Guide

Directory Structure Server Record Server records identify Avaya Telephony Servers. The server record contains all of the information needed to access the server (such as its TCP/IP address). Note: You can add fields to server records, but you cannot modify or delete the following predefined fields. Field Name type key name UUID executable home group cluster security alias configuration servergroups creation_timestamp update_time site srv Unique record key. Server's name. Server identifier. Location of server executable program (full path name of the actual program). Server log file directory; directory from which server is executed. Server's domain name. Reserved. Security level. Alternate name for server. Sequence of couples containing configuration information encoded into a single string. Sequence of couples containing server group preference information encoded into a single string. Time at creation of record. Time at last update of record. In a WAN environment, identifies the site serviced by this server. User Record User records identify individual Avaya IC users. The following is a sample user record. User records differ somewhat depending on the system. Note that using IC Manager you can add fields to user records, but you cannot modify or delete the following predefined fields. Field Name type fname lname per First name. Last name. Issue 1.0 June 2002 61

Chapter 5 The Directory Server Field Name mname supervisor phone phone_passwd phone_type equipment security loginid group cluster homephone pname skills configuration key creation_timestamp update_time site Middle name. Supervisor's name. Telephone number. Telephone password. Type of telephone. Switch dependent. May be a physical teleset extension or a number used by the switch to identify the equipment. Security level. Unique string (identifier). User's domain name. Reserved. Home telephone number. Personal name (e.g., nickname). Sequence of strings listing agent skills encoded into a single string. Sequence of couples containing configuration information encoded into a single string. Unique record key. Time at creation of record. Time at last update of record. In a WAN environment, identifies the site of this user. 62 Core Services Programmer s Guide

Using the Directory Server Using the Directory Server Creating Records Most Directory Server administration (creating, updating, and deleting records) is performed through the IC Manager. Refer to IC Administration Volume 1: Servers & Domains for information about administering the Directory Server. The information that follows is applicable to developers writing applications that use the Directory Server. It is assumed that such developers are familiar with the use of C and/or Visual Basic and the DDE Server. New records are created with a CreateRecord() method invocation. The value of each field in the record, with the exception of the following, should be specified in the CreateRecord() call. The exceptions are: key, a sequential number, automatically assigned at the creation of the record, which is a unique identifier for each record in the database. creation_timestamp, the date and time at which the record was created, automatically assigned at the creation of the record. update_time, the date and time at which the record was last updated. For the use of CreateRecord(), see the example in CreateRecord, on page 71. Selecting and Releasing Records The SelectRecords() method can be used to select a record or group of records for reading, updating, or deleting. The SelectRecords() method matches the selection criteria against the records in the database and returns a selection key (SELKEY). The selection key can be used in subsequent GetRecords(), UpdateRecords(), and DeleteRecords() method invocations. In addition to the SelectRecords() method, the following methods employ selection criteria to retrieve a group of records: GetFewRecords() SelGetRecords() SelUpdateRecords() SelDeleteRecords() Selects and retrieves records in a single step. Does not return a SELKEY. Selects and retrieves records in a single step. a SELKEY, permitting subsequent GetRecords() calls. Selects and update records in a single step. Does not return a SELKEY. Selects and deletes records in a single step. Does not return a SELKEY. Once records have been selected the selection key must be freed. Selection keys may be freed by the ReleaseRecords() method, by the DeleteRecords() method, or by the UpdateRecords() method. Issue 1.0 June 2002 63

Chapter 5 The Directory Server Reading Records The following notes are specific to selecting records from the Directory Server: The table parameter of the SelectRecords() method is an empty string because the database consists of a single unnamed table. Directory records are selected by specifying a list of fields. Fields that do not exist in the record are not returned. This is not an error condition. The position of the SELKEY may become invalid when large numbers of records are deleted or updated. When invoking the methods GetRecords() andgetcount(), a VESP_NOT_IN_DIRECTORY exception will be generated if the SELKEY position is invalid. Repeat your selection and method invocation. The Directory Server provides the following methods for retrieving information: GetFewRecords() GetOneAttribute() GetRecords() SelGetRecords() Selects and retrieves records in a single step. Does not return a SELKEY, prohibiting subsequent GetRecords() calls. Retrieves a single field from a database entry using the record key. Retrieves a group of previously selected records. Selects and retrieves records in a single step. a SELKEY, permitting subsequent GetRecords() calls. Updating Records Before invoking the GetRecords() method, the records to be retrieved must be selected using the SelectRecords() or SelGetRecords() method. The other methods do not require records to be selected prior to retrieval. GetOneAttribute() returns a single field value from a directory entry. All other retrieval methods return the fields requested for a group of records. The maximum number of records returned is specified in the method invocation. See the example in GetRecords, on page 84. Records' field values can be altered by naming them in an UpdateRecords() or SelUpdateRecords() method invocation. The UpdateRecords() method requires that records to be updated be previously selected; SelUpdateRecords() simultaneously selects and updates records. After the records are updated, the selection key (SELKEY) associated with that group of records is automatically released. The calling client must have sufficient security privilege to modify a record. Security privilege is established through the IC Manager. The key and creation_timestamp fields cannot be modified. 64 Core Services Programmer s Guide

Using the Directory Server Deleting Records Selection Criteria Records are deleted using either the DeleteRecords() or SelDeleteRecords() method. DeleteRecords() requires that records to be deleted be previously selected. SelDeleteRecords() simultaneously selects and deletes records. Deleting records automatically releases the SELKEY associated with that group of records. See the example in DeleteRecords, on page 75. The calling client must have sufficient security privilege to delete a record. Security privilege is established through the IC Manager. Several Directory Server methods accept a selectcriteria string, which has one of three forms: empty ("") all ("*") criteria No records are selected. All records are selected. This string is a special case and cannot contain whitespace. An expression that selects some records. If an expression criteria is provided, the names and values of record fields ( couples ) are tested against the criteria and the result is either True (select the record) or False (do not select the record). Selection Criteria Syntax The general syntax of a criteria is: (name relationalop value) [booleanop...] where relationalop is one of: = Found <> Not Found < Less than <= Less than or equal to > Greater than >= Greater than or equal to <, <=, > and >= are not valid with wildcards. Issue 1.0 June 2002 65

Chapter 5 The Directory Server and booleanop is one of: & And. Both relations must be true. Or. True if either relation or both is true. = Equivalent. True if both relations are true or both are false. ^ Exclusive Or. True if and only if one relation is true. Record fields are examined one at a time. For the Found operator (=), a match means that a field was found within the record that had the given name and value. For the Not Found operator, a match means that no field in the record had the given name and value. The record might have had an instance of the name, with a different value, or instances of the value paired with different names, or not contained that name at all. Note that all comparisons are string comparisons, 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.) Enclose names within quotes if they contain characters other than letters, digits, and underscores. 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: (type = s??) matches records with a 3 digit type beginning with s. Wildcarded names are less useful: (ty* = srv) matches records that have a field whose name starts with ty that happens to hold srv. The criteria (*=*) selects everything. "*" has the same effect. Selection Criteria Examples type = "srv" (type = "per") & (name = "L*") selects all directory records for servers. selects all directory records for persons with names beginning with L. 66 Core Services Programmer s Guide

IDL Specification IDL Specification The following is the Interface Definition Language (IDL) description of the Directory Server database. The method names are shown here without their interface qualifier, which is DS. For example, a call to the SelectRecords() method in the Directory Server takes the form DS.SelectRecords(). The genericds class is a collection of general database methods inherited by the Directory Server. The Directory Server uses only one table; methods that require a table name should be passed an empty string. interface genericds virtual { ORBStatus Assign (); } ORBStatus SelectRecords( in string tablename, in string selectcriteria, in SeqString projection, out SELKEY selkey ); ORBStatus GetCount( in string tablename, in string selectcriteria, out unsigned long count ); ORBStatus ReleaseRecords( SELKEY selkey ); ORBStatus GetRecords( SELKEY selkey, out SeqSeqCouple result ); ORBStatus GetColumn( SELKEY selkey, out SeqString result ); ORBStatus DeleteRecords( SELKEY selkey ); ORBStatus UpdateRecords( SELKEY selkey, SeqCouple list); ORBStatus GetOneAttribute( in string tablename, in string key, in string name, out string value ); ORBStatus GetFewRecords( in string tablename, in string selectcriteria, out SeqSeqCouple result); ORBStatus SelGetRecords( in string tablename, in string selectcriteria, in SeqString projection, out SELKEY selkey, out SeqSeqCouple result ); ORBStatus CreateRecord( in string tablename, in SeqCouple list, out string key ); } interface DS : genericds, General { ORBStatus Backup( in string filename ); ORBStatus Restore( in string filename ); void Login( in string loginid, in string password, out SeqSeqCouple list ); void ChangePassword( in string key, in string oldpass, in string newpass ); void ForceChangePassword( in string key, in string newpass ); void DeleteUser( in string key); ORBStatus ChangeParents() FOR INTERNAL USE ONLY ORBStatus AreYouMyParent() FOR INTERNAL USE ONLY ORBStatus CanIBeYourParent() FOR INTERNAL USE ONLY ORBStatus WhoIsYourParent( out string parent_uuid ); ORBStatus SelDeleteRecords( in string criteria ); ORBStatus SelUpdateRecords( in string criteria, in SeqCouple list ); Issue 1.0 June 2002 67

Chapter 5 The Directory Server Assign IDL Syntax ORBStatus Assign( void ) ; If used, the client will assign to the DS, which may be useful to insure that requests on a long series of transactions go to the same server. If the assigned server goes down during a long sequence of requests, the ORB Server will send a ServerFailed.event even when there is not a request pending. Exceptions VESP_ERROR VESP_ASSIGN_FAILURE Request was NOT successful Assign request denied; you may already be assigned Backup IDL Syntax ORBStatus Backup( in string filename ) ; Backup takes a snapshot of the directory. You provide a filename for the backup file. Note that you can only restore from a backup of the parent directory. Refer to Restore, on page 89 for information about the Restore() method. The calling client must have sufficient security privilege. Security privilege is established through the IC Manager. Input filename Name of the backup file. This file is always written in the DS s working directory. Exceptions VESP_ERROR Request was NOT successful 68 Core Services Programmer s Guide

ChangePassword Example Session session; Environment ev; Request request char *tparent_id, *parent_id, interface[64]; Vesp_Request_Sync("DS.WhoIsYourParent", &ev, session, &request, &tparent_id); if (ev._major!= NO_EXCEPTION) { vesp_log_info(vesp_cat_all, "Error", "Failed Request"); log_unparsable("ds.whoisyourparent failed: %s", ev.vesp_error_description); return (ev._minor); } parent_id = vesp_strdup(tparent_id); Vesp_Request_Delete( session, request ); sprintf(interface, "#$s.backup", parent_id); Vesp_Request_Sync(interrace, &ev, session, &request, "examp_back.ffd"); if (ev._major!= NO_EXCEPTION) { vesp_log_info(vesp_cat_all, "Error", "Failed Request"); log_unparsable("%s", ev.vesp_error_description); return (ev._minor); } Vesp_Request_delete( session, request ); ChangePassword IDL Syntax void ChangePassword( in string key, in string oldpass, in string newpass ) ; Change the password to a new one. The calling client must have sufficient security privilege. Security privilege is established through the IC Manager. Use the hybrid (Toolkit library) routine Vesp_Change_Password() instead of invoking this method directly. This method is used internally by Avaya IC. Input key oldpass newpass Key into database entry representing user. Old encrypted password. New encrypted password. Issue 1.0 June 2002 69

Chapter 5 The Directory Server Output None None Exceptions VESP_ERROR Request was NOT successful CreateDBTableRecord IDL Syntax ORBStatus CreateDBTableRecord(in string tablename, in SeqCouple sc, out string key); Create a record in the db in a particular table. Input tablename sc Name of the db table. SeqCouple containing all the field values to be inserted to create a record. Output key Primary key of the record created. Success Exceptions VESP_FAILURE Error 70 Core Services Programmer s Guide

CreateRecord CreateRecord IDL Syntax ORBStatus CreateRecord( in string tablename, in SeqCouple list, out string key ) ; This method adds a new record to a table in a database. The calling client must have sufficient security privilege. Security privilege is established through the IC Manager. The value of all fields except key, creation_timestamp, and update_time should be specified in the CreateRecord() call. The values of key and creation_timestamp are set by the CreateRecord() method. It is invalid to specify certain values for some fields. While the interface represents all values read from or written to the databases as strings, some of the fields represent integers and date/times. If successful, the method provides the value of the key field it created, which is unique to this record. It is invalid to create a record by specifying no fields (a length of 0 in list), fields that are not client-writable, or invalid values for a field. In these cases, VESP_ERROR is returned and exception information is set. Input tablename list Empty string ("") to default to the DS table. Information to populate the record, where the name in each couple is the field name (e.g., phone ) and the value is the value to set (e.g., 5087872800 ). Output key The key to the newly created record. Exceptions VESP_ERROR Request was NOT successful Issue 1.0 June 2002 71

Chapter 5 The Directory Server Example #include <orb.h> int main (argc, argv) int arg; char *argc; { Object client_object; /* Object Handle */ Session session; /* Session Handle */ Request request; /* Request */ Environment ev; /* Environment */ char *key /* Directory Database Key */ _IDL_SEQUENCE_Couple seqcouples; /* Sequence of Couples */ /* Initialize VESP client and log into VESP */ if ( Vesp_Login( JohnDoe, password, &client_object )! = ) { fprintf(stderr, VESP_LOGIN failed! ); exit (1); } /* Create VESP session */ if ( Vesp_Session_Create( client_object, &session )! = ) { fprintf(stderr, Unable to create session! ); exit (1); } /* Create Personnel Record */ seqcouples = vesp_couple_seq_create(); */ Initialize sequence of couples */ vesp_couple_seq_add_couple( seqcouples, type, per ); */ Personnel Record */ vesp_couple_seq_add_couple( seqcouples, lname, Lutton ); */ Last Name*/ vesp_couple_seq_add_couple( seqcouples, fname, Larry ); */ First Name */ vesp_couple_seq_add_couple( seqcouples, userid, LLutton ); */ User ID */ vesp_couple_seq_add_couple( seqcouples, phone, 5084863244 ); */ Telephone Number */ if ( Vesp_Request_Sync( DS.CreateRecord, &ev, session, &request,, &seqcouples, &key)!= ) { fprintf(stderr, VESP_LOGIN failed! ); } */ Clean UP */ vesp_couple_seq_delete( seqcouples ); Vesp_Request_Delete( session, request ); */ Delete Request Created By*/ */ Vesp_Request_Sync*/ if ( Vesp_Logout(client_object)!= */ log Out from VESP */ { fprintf(stderr, VESP_LOGOUT failed! ); exit (1) } } 72 Core Services Programmer s Guide

CreateViewRecord CreateViewRecord IDL Syntax ORBStatus CreateViewRecord(in string viewname, in SeqSeqCouple ssc, out SeqCouple pkeys); A view is a logical set of tables. Each view has a main table and a number of sub-tables. Each of the sub-tables has a foreign key linking it to the main table or another sub-table. A view is represented by a relationset in the ADL. This API (and all the other DS's view APIs) works only for the following views (relationsets): r_ds_employee r_ds_workgroup r_ds_queue employee table and its sub-tables workgroup, workgroupmember and employee tables queue and its sub-tables This API takes in one main table record and one or more sub-tables record, and insert them into the respective tables. All the table inserts are encompassed in one transaction. Input viewname ssc Name of the relationset (one of the three above) SeqSeqCouple containing all the records (each record is a SeqCouple) Output pkeys Primary keys of the records created. It is a SeqSeqCouple having one SeqCouple. The couples in the SeqCouple have tablename and primary keys. Success Exceptions VESP_FAILURE Error Issue 1.0 June 2002 73

Chapter 5 The Directory Server Deassign IDL Syntax ORBStatus Deassign( void ) ; This method terminates the association created with the Assign() method. Exceptions VESP_ERROR VESP_DEASSIGN_FAILURE Request was NOT successful Request failed; the connection may not exist DeleteDBTableRecord IDL Syntax ORBStatus DeleteDBTableRecord(in string tablename, in SeqCouple seq); Delete a record in a table. Input tablename seq Name of the table SeqCouple containing the search criteria for the records to be deleted. Output None Success Exceptions VESP_FAILURE Error 74 Core Services Programmer s Guide

DeleteRecords DeleteRecords IDL Syntax ORBStatus DeleteRecords( in SELKEY selkey ) ; This method deletes all records represented by a selection key, regardless of whether they have been read. The original selection criteria given to SelectRecords() is recovered and applied to a Delete operation. A sequence of SelectRecords(), GetRecords(),..., DeleteRecords() might delete records that were not seen by GetRecords() if records that match the selection criteria were added after the GetRecords() but before the DeleteRecords(). (If you want to insure that you delete only records you have read, you must delete each record as you read it, usually by projecting out its key and deleting each record based on that.) The calling client must have sufficient security privilege. Security privilege is established through the IC Manager. DeleteRecords() automatically calls ReleaseRecords(), since the SELKEY is not useful after all the records it represents are gone. The method returns VESP_ERROR if it fails and sets the exception information. Input selkey The unique identifier assigned to a group of records. Output None Exceptions VESP_ERROR Request was NOT successful Example This example selects and deletes all personnel records. include <orb.h> ORBStatus event_routine ( char *interface, Object object, Session session, Event *event ); int main (argc, argv) int argc; char *argv[] { Object client_object; /* Object Handle */ Session session; /* Session Handle */ Request request; /* Request */ Environment ev; /* Environment */ Issue 1.0 June 2002 75

Chapter 5 The Directory Server SELKEY key /* Selection Key */ _IDL_SEQUENCE_Couple seqcouples; /* Sequence of Couples */ /* Initialize VESP client and log into VESP */ if ( Vesp_Login( JohnDoe, password, &client_object )! = ) { fprintf(stderr, VESP_LOGIN failed! ); exit (1); } /* Create VESP session */ if ( Vesp_Session_Create( client_object, &session )! = ) { fprintf(stderr, Unable to create session! ); exit (1); } /* Create Session to DS */ if ( Vesp_Assign_Request( DS.Assign, &ev, NULL, OUL, event_routine, session, )! = ) { fprintf(stderr, Unable to Assign to DS! ); exit (1); } /* Select all Personnel Records */ if ( Vesp_Request_Sync( DS.SelectRecords, &ev, session, &request,, type = per,, &key )! = ) { fprintf(stderr, Unable to select personnel records! ); exit (1); } Vesp_Request_Delete( session, request ); */ Delete Request Created By*/ */ Vesp_Request_Sync*/ /* Delete all records previously selected */ if ( Vesp_Request_Sync( DS.DeleteRecords, &ev, session, &request, key )!= { fprintf(stderr, Unable to delete personnel records! ); exit (1); } Vesp_Request_Delete( session, request ); */ Delete Request Created By*/ */ Vesp_Request_Sync*/ /* Clean Up */ if ( Vesp_Logout(client_object)!= 76 Core Services Programmer s Guide

DeleteUser DeleteUser IDL Syntax void DeleteUser(in string key) ; This method deletes a user and releases the user s password information. The calling client must have sufficient security privilege. Security privilege is established through the IC Manager. Input key Key into database entry representing user. Output None None Exceptions VESP_ERROR VESP_NO_PRIVILEGE Request was NOT successful Request denied; did not have sufficient privilege DeleteViewRecord IDL Syntax ORBStatus DeleteViewRecord(in string viewname, in SeqCouple delkey); Delete the view i.e. all the records in the view. The primary key of the main table record needs to be passed as input. The delete is actually a soft delete i.e. the deletedflag field s value is changed from 0 to 1 on deletion. Input viewname delkey Name of the relationset Primary key of the record in the main table Output None Issue 1.0 June 2002 77

Chapter 5 The Directory Server Success Exceptions VESP_FAILURE Error ForceChangePassword IDL Syntax void ForceChangePassword( in string key, in string newpass ) ; This method forces the password to change to a new one. Use the hybrid (Toolkit library) routine Vesp_Force_Password() instead of invoking this method directly. This method is used internally by Avaya IC. The calling client must have sufficient security privilege. Security privilege is established through the IC Manager. Input key newpass Key into database entry representing user. New encrypted password. Output None None Exceptions VESP_ERROR VESP_NO_PRIVILEGE Request was NOT successful Request denied; did not have sufficient privilege 78 Core Services Programmer s Guide

GetCount GetCount IDL Syntax ORBStatus GetCount( in string tablename, in string selectcriteria, out unsigned long count ) ; GetCount returns the number of records that match the selection criteria. Input tablename Empty string ("") to default to the DS table. selectcriteria Selection criteria (see Selection Criteria, on page 65). Output count Number of records matching the selection criteria. Exceptions VESP_ERROR Request was NOT successful Example Session session; Environment ev; Request request; unsigned long count, expected_count; Vesp_Request_Sync( DS.GetCount, &ev, session, &request,, type=per, &count ); if (ev._major!= NO_EXCEPTION) { vesp_log_info(vesp_cat_all, Error, Failed Request ); log_unparsable( %s, ev.vesp_error_description); return (ev._minor); } if (count!= expected_count) { vesp_log_info(vesp_cat_all, Error, Failed Request ); log_unparsable( GetCount for type=per returned wrong number of records. ); log_unparsable( Expecting %ld, received %ld.\n, expected_count, count); return(vesp_error) } Vesp_Request_Delete( session, request ); Issue 1.0 June 2002 79

Chapter 5 The Directory Server GetDBRecordCount IDL Syntax ORBStatus GetDBRecordCount(in string tablename, in SeqCouple seq, out long count); Get the count of the records in a table. Input tablename seq Name of the table SeqCouple having the search criteria. Output count Count of records in a table Success Exceptions VESP_FAILURE Error GetDBRecordsFromATable IDL Syntax ORBStatus GetDBRecordsFromATable(in string tablename, in SeqCouple seq, in string nextpagekey, out SeqSeqCouple result); Get the records from a single db table. Input seq nextpagekey Search criteria Primary Key of the last record in current page in order to fetch the next page. Output Result Fetched records 80 Core Services Programmer s Guide

GetFewRecords Success Exceptions VESP_FAILURE Error GetFewRecords IDL Syntax ORBStatus GetFewRecords( in string tablename, in string selectcriteria, out SeqSeqCouple result ) ; GetFewRecords() combines a SelectRecords(), a single GetRecords(), and a ReleaseRecords() into one call. All fields in the selected records are projected out. If all qualifying records are not returned by this call there is no way to "continue" the read by calling GetRecords(). It is not an error to specify a selection that selects zero records. Input tablename Empty string ("") to default to the DS table. selectcriteria Selection criteria (see Selection Criteria, on page 65). Output result Found records. VESP_PARTIAL_SUCCESS Returned all qualifying records More records were requested than could be returned Exceptions VESP_ERROR Request was NOT successful Issue 1.0 June 2002 81

Chapter 5 The Directory Server Example Session session; Environment ev; Request request; char buf[512], *memyselfi; int num; SeqSeqCouple *outlist; /* Get all the records with a type of MY_TYPE, a qqq of num, * and a longish_field_name of memyselfi. There should be one * and only one such record. */ sprintf(buf, type= MY_TYPE & (qqq < %08ld & qqq > %08ld) & longish_field_name = \ %s\, num+1 num-1 memyselfi); outlist = vesp_couple_seqseq_create(); Vesp_Request_Sync( DS.GetFewRecords, &ev, session, &request,, buf, outlist); if (ev._major!= NO_EXCEPTION) { vesp_log_info(vesp_cat_all, Error, Failed Request ); log_unparsable( %s, ev.vesp_error_description); return (ev._minor); } if (outlist->_length < 1) { vesp_log_info(vesp_cat_all, Error, Failed Request ); log_unparsable( Error: no records returned. ); return (VESP_ERROR); } if (outlist->_length < 1) { vesp_log_info(vesp_cat_all, Error, Failed Request ); log_unparsable( Error: multiple records returned. ); } Vesp_Request_Delete( session, request ); Vesp_couple_seqseq_delete(outlist); 82 Core Services Programmer s Guide

GetOneAttribute GetOneAttribute IDL Syntax ORBStatus GetOneAttribute( in string tablename, in string key, in string name, out string value ) ; GetOneAttribute() retrieves one field's value from a single record. Every record in the DS database contains a field named key which contains a string that uniquely identifies that record. You must know a record's key to retrieve information from the record. (You can use SelectRecords() to obtain key.) The return code is VESP_ERROR if the field does not exist, or and a copy of the value returned in value. Input tablename key name Empty string ("") to default to the DS table. Record key; must not be empty. Name of field to retrieve. Output value Retrieved result. VESP_PARTIAL_SUCCESS More records were requested than could be returned Exceptions VESP_ERROR Request was NOT successful Issue 1.0 June 2002 83

Chapter 5 The Directory Server Example Session session; Environment ev; Request request; SELKEY key; char *p, memyselfi[33]; Vesp_Request_Sync ( DS.GetOneAttribute, &ev, session, &request,, key, longish_field_name, &p); if (ev._major!= NO_EXCEPTION) { vesp_log_info(vesp_cat_all, Error, Failed Request ); log unparsable( %s, ev.vesp_error_description); return (ev._minor); } strcpy(memyselfi, p); Vesp_Request_Delete( session, request ); GetRecords IDL Syntax ORBStatus GetRecords( in SELKEY selkey, out SeqSeqCouple result ) ; This method returns some or all of the records chosen with SelectRecords(). The form is a sequence of sequence of couples; the first-level sequences represent records, and the second-level sequences represent fields. The call either explicitly specifies a maximum number of records to be returned or specifies 0. Specifying 0 is a request for an unlimited number of records. (There is no way to control how many fields are returned.) A series of GetRecords() calls with the same SELKEY picks up batches of unread records until all have been fetched position is remembered and each GetRecords() picks up where the last left off. The returned code is if the number of records specified is the number of records returned, e.g., 8 records were requested and 8 records were returned. A return of does not indicate whether there are more records to be gotten or not. The returned code is VESP_PARTIAL_SUCCESS if more records were specified than exist, e.g., if only 6 records match the SELKEY, but 8 records were requested. A return of VESP_PARTIAL_SUCCESS indicates that there are no more records to be gotten. On a failure, the method returns VESP_ERROR and sets the exception information. Errors occur when you try to GetRecords() on a SELKEY that had no fields listed for projection (such SELKEYs are useful only for deleting, not reading). Input selkey The unique identifier assigned to a group of records. 84 Core Services Programmer s Guide

GetRecords Output result Records found. VESP_PARTIAL_SUCCESS More records were requested than could be returned Exception VESP_ERROR VESP_NOT_IN_DIRECTORY Request was NOT successful Due to the updating or deleting of numerous records, the position of the SELKEY is no longer valid. Example include <orb.h> ORBStatus event_routine ( char *interface, Object object, Session session, Event *event ); int main (argc, argv) int argc; char *argv[] { Object client_object; /* Object Handle */ Session session; /* Session Handle */ Request request; /* Request */ Environment ev; /* Environment */ SELKEY key /* Selection Key */ _IDL_SEQUENCE_Couple seqcouples; /* Sequence of Couples */ SeqSeqCouple ssqoutlist; /* Sequence of Sequences of Couples /* Initialize VESP client and log into VESP */ if ( Vesp_Login( JohnDoe, password, &client_object )! = ) { fprintf(stderr, VESP_LOGIN failed! ); exit (1); } /* Create VESP session */ if ( Vesp_Session_Create( client_object, &session )! = ) { fprintf(stderr, Unable to create session! ); exit (1); } /* Create Session to DS */ if ( Vesp_Assign_Request( DS.Assign, &ev, NULL, OUL, event_routine, session, )! = ) { fprintf(stderr, Unable to Assign to DS! ); exit (1); } /* Select all Personnel Records */ if ( Vesp_Request_Sync( DS.SelectRecords, &ev, session, &request,, type = per,, &skselkey )! = ) Issue 1.0 June 2002 85

Chapter 5 The Directory Server { fprintf(stderr, Unable to select personnel records! ); exit (1); } Vesp_Request_Delete( session, request ); */ Delete Request created */ */ by Vesp_Request_Sync*/ /* Retrieve records previously selected */ in_idl_sequence_sequence_couple (ssqoutlist,1) */ Initialize sequence of sequences */ */ of couples */ if ( Vesp_Request_Sync( DS.GetRecords, &ev, session, &request, &skselkey, ssqoutlist)!= ) { fprintf(stderr, Unable to retrieve personnel records! ); exit (1); } Vesp_Request_Delete( session, request ); */ Delete Request Created */ */ by Vesp_Request_Sync*/ /* Clean Up and do auto assign */ if ( Vesp_Logout(client_object)!= */ Log Out from VESP*/ GetViewRecord IDL Syntax ORBStatus GetViewRecord(in string viewname, in SeqCouple seq, in string nextpagekey, out SeqSeqCouple result); Get the view data i.e. all the records in the relationset. Search criteria could be specified to filter the search. The search should result in only one main table record. The DS picks the first and ignores the rest, if there are more than one. Of course, there can be more than one record from other (sub-tables) tables. The page size (maximum record to be returned in a fetch) can be specified in the _maximum attribute of the result parameter. Input viewname seq nextpagekey Name of the relationset Search criteria in the form of sequence couples Primary Key of the last record in current page in order to fetch the next page. Output result Records found. 86 Core Services Programmer s Guide

GetViewRecordCount Success Exceptions VESP_FAILURE Error GetViewRecordCount IDL Syntax ORBStatus GetViewRecordCount(in string viewname, in SeqCouple seq, out long count); Get the count of the number of records in the view. This returns the number of records of the main table in the view. Input seq Search criteria in the form of sequence couple Output count Number of records in the view Success Exceptions VESP_FAILURE Error Issue 1.0 June 2002 87

Chapter 5 The Directory Server Login IDL Syntax void Login( in string loginid, in string password, out SeqSeqCouple list ) ; This method logs into Avaya IC and gets all the configuration information for a given client. Use the hybrid (Toolkit library) routine Vesp_Login() instead of invoking this method directly. This method is used internally by Avaya IC. Input loginid password The login ID of the client. The encrypted password of the client. Output list All the client configuration information. None Exceptions VESP_ERROR VESP_BAD_LOGIN_ID VESP_MULTI_LOGIN_ID VESP_BAD_PASSWORD Request was NOT successful The request failed; the login ID was wrong The request failed; more than one client record has the same login ID The request failed; the password was wrong ReleaseRecords IDL Syntax ORBStatus ReleaseRecords( in SELKEY selkey ) ; ReleaseRecords() frees a SELKEY. Selection keys consume server resources. They should always be released when you are done with the selected records. This method returns VESP_ERROR if the SELKEY is not valid. 0 is a special case and returns even though it is never a valid selection key value. 88 Core Services Programmer s Guide

Restore Input selkey The unique identifier assigned to a group of records. Output None Exceptions VESP_ERROR Request was NOT successful Example Session session; Environment ev; Request request; SELKEY sk1; /*Clean up the selkey from the last request*/ Vesp_Request_Sync( DS.ReleaseRecords:, &ev, session, &request, sk1 ); if (ev._major!= NO_EXCEPTION) { vesp_log_info( VESP_CAT_ALL, Error, Failed Request ); log unparsable( %s, ev.vesp_error_description ); return( ev._minor ); } Vesp_Request_Delete( session, request ); Restore IDL Syntax ORBStatus Restore( in string filename ) ; This method overlays the parent directory with the information previously saved by the Backup() method. The calling client must have sufficient security privilege. Security privilege is established through the IC Manager. Note that only the parent DS can perform a Restore. Input filename Name of the backup file. Output None Issue 1.0 June 2002 89

Chapter 5 The Directory Server Exceptions VESP_ERROR Request was NOT successful Example Session session Environment ev; Request request; char *tparent_id, *parent_id, interface[64]; Vesp_Request_Sync("DS.WhoIsYourParent", &ev, session, &request, &tparent_id); if (ev._major!= NO _EXCEPTION) { vesp_log_info(vesp_cat_all, "Error", "Failed Request"_); log_unparsable("ds.whoisyourparent failed: %s", return (ev._minor); } parent_id = vesp_strdup(tparent_id); Vesp_Request_Delete( session, request ); Vesp_Request_Sync(interface, &ev, session, &request, "examp_back.ffd") if (ev._major!= NO _EXCEPTION) { vesp_log_info(vesp_cat_all, "Error", "Failed Request"_); log_unparsable("%s", ev.vesp_error_description); return (ev._minor); } Vesp_Request_Delete( session, request ); 90 Core Services Programmer s Guide

SelDeleteRecords SelDeleteRecords IDL Syntax ORBStatus SelDeleteRecords( in string criteria ) ; This method selects and deletes multiple records in a single method call. The calling client must have sufficient security privilege. Security privilege is established through the IC Manager. It is not an error to specify a selection that selects zero records. SelDeleteRecords() automatically calls ReleaseRecords(), since the SELKEY is not useful after all the records it represents are gone. Input criteria Selection criteria (see Selection Criteria, on page 65). Output None Exceptions VESP_ERROR Request was NOT successful Example Session session; Environment ev; Request request; Vesp_Request_Sync( DS.SelDeleteRecords, &ev, session, &request, type = MY_TYPE ); if (ev._major!= NO_EXCEPTION) { vesp_log_info( VESP_CAT_ALL, Error, Failed Request ); log_unparsable( %s, ev.vesp_error_description); return (ev._minor); } Vesp_Request_Delete( session, request ); Issue 1.0 June 2002 91

Chapter 5 The Directory Server SelectRecords IDL Syntax ORBStatus SelectRecords( in string tablename, in string selectcriteria, in SeqString projection, out SELKEY selkey ) ; Before records can be read or deleted, they must be selected. This method allows you to specify which records you want and returns a selection key (SELKEY) to pass to the other database methods. Valid SELKEYs are integral, nonzero values. It is not an error to specify a selection that selects zero records. If you intend to read and modify or delete individual records, you will often want to project out (at least) the key field. When a record is created it is assigned a unique key value, which enables you to quickly select individual records. You should always release a SELKEY (with the ReleaseRecords() method) when you are through with the records. Input tablename Empty string ("") to default to the DS table. selectcriteria Selection criteria (see Selection Criteria, on page 65). projection A list of strings naming the fields you wish to read from the database table. If you are going to delete, not read, you should specify an empty sequence (length = 0). If you want every field returned when you read, specify a length of 1 and a string containing only "*". Output selkey The unique identifier assigned to a group of records. Exceptions VESP_ERROR Request was NOT successful Example Session session Environment ev; Request request; char bif[128], buf2[512]; SeqString *univer; SELKEY sk1; 92 Core Services Programmer s Guide

SelGetRecords sprint(buf2, "type = " MY_TYPE " & qqq = \%s\" & pid = %ld", buf, getpid()); univer = vesp_string_seq_create(); vesp_string_seq_add_value(univer, "*"); Vesp_Request_Sync("DS.SelectRecords", &ev, session, &request, "", buf2, univer, sk1); if (ev._major!= NO _EXCEPTION) { vesp_log_info(vesp_cat_all, "Error", "Failed Request"_); log_unparsable("%s", ev.vesp_error_description); return (ev._minor); } vesp_string_seq_delete(univer); Vesp_Request_Delete( session, request ); SelGetRecords IDL Syntax ORBStatus SelGetRecords( in string tablename, in string selectcriteria, in SeqString projection, out SELKEY selkey, out SeqSeqCouple result ) ; SelGetRecords() selects and retrieves multiple records with a single method call. Before records can be read, they must be selected. This method allows you to specify which records you want and returns a selection key (SELKEY) to pass to the other database methods. If the selection succeeds, the method reads and returns matching records, as GetRecords() would. If SelGetRecords() cannot return all the requested records, the SELKEY returned can be used in subsequent GetRecords() calls to continue reading. Valid SELKEYs are integral, nonzero values. This call differs from GetFewRecords() in that if there is more to read than can be returned, you have the option of reading the remainder with a GetRecords() call; GetFewRecords() releases the selection key it creates and does not provide the option of going on. If SelGetRecords() is able to return all matching records and knows it has returned all such records, SelGetRecords() releases the selection key and sets SELKEY to 0. Note: If there are 6 matching records and 8 were requested, SelGetRecords() knows that it has returned all matching records, returns VESP_PARTIAL_SUCCESS, releases the selection key, and sets SELKEY to 0. If there are 6 matching records and 6 were requested, SelGetRecords() may or may not know that it has returned all matching records. It is not an error to specify a selection that selects zero records. Issue 1.0 June 2002 93

Chapter 5 The Directory Server Input tablename Empty string ("") to default to the DS table. selectcriteria Selection criteria (see Selection Criteria, on page 65). projection A list of strings naming the fields you wish to read from the database table. If you want every field returned when you read, specify a length of 1 and a string containing only "*". Output selkey result The unique identifier assigned to a group of records. Result of selection. VESP_PARTIAL_SUCCESS More records were requested than could be returned Exceptions VESP_ERROR Request was NOT successful Example Session session; Environment ev; Request request; SeqString *projection; char buf[512], *parent_id, *parent_alias; SeqSeqCouple *out_data; SELKEY keyto; sprintf(buf, "UUID=%s", parent_id); projection = vesp_string_seq_create(); out_data = vesp_couple)seqseq_create(); Vesp_Request_Sync("DS.SelGetRecords", &ev, session, &request, "", buf, projection, &keyto, out_data); if (ev._major!= NO_EXCEPTION) { vesp_log_info(vesp_cat_all, "Error", "Failed Request"); log_unparsable("%s", ev.vesp_error_description); return (ev._minor); } if (out_data->_length!= 1) 94 Core Services Programmer s Guide

SelUpdateRecords { vesp_log_info(vesp_cat_all, "Error", "Failed Request"); log_unparsable("%ld parent records returned.\n", out_data->_length); return (VESP_ERROR); } vesp_dup_seq_couple_value(&(out_data->_buffer[0]), "alias", &parent_alias); if (parent_alias == NULL) { vesp_log_info(vesp_cat_all, "Error", "Failed Request"); log_unparsable("parent has no alias.\n"); return (VESP_ERROR); } Vesp_Request_delete( session, request ); SelUpdateRecords IDL Syntax ORBStatus SelUpdateRecords( in string criteria, in SeqCouple list ) ; This method selects and updates all the records matching the selection criteria, altering the fields named in the given sequence to the values specified. The calling client must have sufficient security privilege. Security privilege is established through the IC Manager. SelUpdateRecords() automatically calls ReleaseRecords() to release the SELKEY. It is invalid to attempt to modify the key and creation_timestamp fields. If the attempt fails for any reason, the records may be partially updated, and VESP_ERROR is returned. Input criteria Selection criteria (see Selection Criteria, on page 65). list List to update. Output None Issue 1.0 June 2002 95

Chapter 5 The Directory Server Exceptions VESP_ERROR Request was NOT successful UpdateDBTableRecord IDL Syntax ORBStatus UpdateDBTableRecord(in string tablename in SeqCouple sc); Update a record in a table. Primary Key field must be supplied in the table record for update. Input tablename sc Name of the table The updated table record Output None Success Exceptions VESP_FAILURE Error UpdateRecords IDL Syntax ORBStatus UpdateRecords( in SELKEY selkey, in SeqCouple list ) ; This method updates all the records named by the SELKEY, altering the fields named in the given sequence to the values specified. The calling client must have sufficient security privilege. Security privilege is established through the IC Manager. UpdateRecords() automatically calls ReleaseRecords() to release the SELKEY. It is invalid to attempt to modify the key and creation_timestamp fields. 96 Core Services Programmer s Guide

UpdateRecords If the attempt fails for any reason, the records may be partially updated, and VESP_ERROR is returned. Input selkey list The unique identifier assigned to a group of records. List to update. Output None Exceptions VESP_ERROR Request was NOT successful Example Session session; Environment ev; Request request; SeqCouple *seqcoup; char buf[128], buf2[512], *memyselfi; SeqString *univer; SELKEY sk1; sprintf(buf2, "type = " MY_TYPE " & qqq = \ "%s\" & pid = %id", buf, getpid()); univer = vesp_string_seq_create(); vesp)string_seq_add_value(univer, "*"); Vesp_Request_Sync("DS.SelectRecords", &ev, session, &request, "", buf2, univer, &sk1); if (ev._mauor!= NO_EXCEPTION) { vesp_log_info(vesp_cat_all, "Error", "Failed Request"); log_unparsable("%s", ev.vesp_error_description); return (ev._minor); } vesp_string_seq_delete(univer); Vesp_Request_Delete( session, request ); /* Add the couple {"longish_field_name", memyselfi} to all the * records indicated by sk1. Issue 1.0 June 2002 97

Chapter 5 The Directory Server */ seqcoup = vesp_couple_seq_create(); vesp_couple_seq_add_couple_values(seqcoup, "longish_field_name", memyselfi); Vesp_Request_Sync("DS.UpdateRecords", &ev, session, &request, sk1, &seqcoup); if (ev._major!= NO_EXCEPTION) { vesp_log_info(vesp_cat_all, "Error", "Failed Request"); log_unparseable("%s", ev.vesp_error_description); return (ev._minor); } vesp_couple_seq_delete(seqcoup); Vesp_Request_Delete( session, request ); /* sk1 is now defunct */ UpdateViewRecord IDL Syntax ORBStatus UpdateViewRecord(in string viewname, in SeqSeqCouple sc); Update the records in a view. Input viewname sc Name of the relationset. SeqSeqCouple having the pkey and the modified field values as Couples Output None Success Exceptions VESP_FAILURE Error 98 Core Services Programmer s Guide

WhoIsYourParent WhoIsYourParent IDL Syntax ORBStatus WhoIsYourParent( out string parent_uuid ) ; This method returns the UUID of the parent Directory Server. Input None Output parent_uuid UUID of the parent Directory Server. Exceptions VESP_ERROR Request was NOT successful Example Session session; Environment ev; Request request; char *tparent_id, *parent_id; Vesp_Request_Sync("DS.WhoIsYourParent", &ev, session, &request, &tparent_id); if (ev._major!= NO_EXCEPTION) { vesp_log_info(vesp_cat_all, "Error", "Failed Request" log_unparsable("ds.whoisyourparent failed: %s", ev.vesp_error_description); return (ev._minor); } parent_id = vesp_strdup(tparent_id); Vesp_Request_Delete( session, request ); Issue 1.0 June 2002 99

Chapter 5 The Directory Server Alarms The following alarms are set by the Directory Server. Note: If no Directory Server is listed in the directory, alarms will be raised and the Directory Server will add itself. This may result in an incomplete restoration of the directory. Examine the directory records for missing information. Restore from the file backup.ffd if it exists. If a DS exists in the system but is not listed in the directory, an error has occurred and the directory will become read-only. Stop the DS, add it to the directory (or restore the parent from backup.ffd) and restart the DS. Alarm Priority Alarm Text Cause/Recommended Action Backup Admin Backup initiated by username into filename BackupError Emergency Backup into filename failed, error code n BackupInvalid Admin Can be one of the following: Informational message. No action required. Action to be taken is error code dependent. Correct the filename or stop use of the database. Backup filename is invalid Backup filename is in use as current database BackupOK Admin Backup into filename complete BadEnd Emergency DS shutdown failed to update database Informational message. No action required. While shutting down, the DS was unable to save the directory to disk one last time. Restart the DS and examine any recently changed records (within 5 minutes of the error). Recent updates may be lost when the DS restarts. 100 Core Services Programmer s Guide

Alarms Alarm Priority Alarm Text Cause/Recommended Action BadString High Can be one of the following: nnn byte name exceeds nnn byte max, truncating. nnn byte value exceeds nnn byte max, truncating. Value "<valuename>" not in value list. CloseWrite Emergency Close error to ds.tmp; cannot write changes Database Low Update sent to DS in Read-Only state For alarm text #1 and #2, a record has been assigned a couple with a name or value that exceeds the maximum byte length that the DS can handle. Check the log file for the actual text of the name or value and determine if the data was correct. If so, use abbreviated versions of those strings. For alarm text #3, an internal problem has resulted in names or values being lost or incorrectly assigned. Contact customer support. The DS failed to close the file ds.tmp during a write of the directory. Check the status of ds.tmp and try again. A method that alters the directory was invoked by a client on a Directory Server that is in Read Only mode. The method was not processed. DatabaseNot Mommy Low Restore only allowed for parent DS The named database is not the parent. Empty Emergency Database empty The file ds.ffd in the DS execution directory is empty or missing. Restore it from a backup if possible. Otherwise repeat the Avaya IC installation procedure to recreate an initial directory. Failed_Request High DS.ChangeParents request to child failed (<Avaya IC error code in hexadecimal>) FailedUpdate High Received <event name> event while in Read Only mode NoDSHome High Could not add home to DS record. DS record may be insufficient. An internal attempt by the DS to invoke another server s method has failed. Consult the log files for further information. A child DS was in Read Only mode when it received an update from its parent. It could not process the update in Read Only mode and its directory is now out of sync. Stop and restart that Directory Server to force it to load the current directory and restore it to Read/Write mode. While trying to add itself to the directory, the DS could not determine what its home directory should be. The DS record created probably will not be sufficient to restart the DS. Issue 1.0 June 2002 101

Chapter 5 The Directory Server Alarm Priority Alarm Text Cause/Recommended Action NoDSinDirectory High No DS listing in Directory. DS is adding self as Parent. NoMeInDS Emergency DS #<UUID> not listed in its own Directory! Open High Could not open file for write Orphan Emergency <reason> - Going to Read Only mode. PingFailed High Attempt to Ping child #UUID failed (errorcode). Update may have failed. Rename Emergency Could not rename ds.tmp to target filename Restore Admin Restore initiated by username from filename The DS loaded a directory with no DS records, either at startup or when executing a Restore method. The DS sending this alarm will add itself to the directory, but it would be better to restore the DS from a clean backup file if possible. The DS has loaded a directory file in which it is not listed. If possible, a clean directory file should be restored. The DS cannot make periodic backups of the directory because it cannot open the file ds.tmp. Make sure that the file is not locked and that the DS has write permission to it. A child DS can no longer contact its parent, possibly because the parent went down, the child came up and found no parent record in its ds.ffd, the child sent a message to its parent and got no response, and so on. Ensure that the parent DS is up and use IC Manager to set the parent again. If the DS tries to update all of its children at once and one of those children is unresponsive, this alarm is raised. Ensure that the child is running if it should be. The DS was attempting to create a directory file and had done so in the file ds.tmp, but was unable to rename ds.tmp to the originally intended filename. As the DS removes any old copy of the file before renaming, this may mean that the original copy is gone or locked. Check the status of ds.tmp and the target file (ds.ffd if the DS.Backup method was not running). Informational message. No action required. 102 Core Services Programmer s Guide

Alarms Alarm Priority Alarm Text Cause/Recommended Action RestoreError Emergency Can be one of the following: Restore from filename failed, error code -1, Cannot write snapshot into oldds.ffd Restore from filename failed, error code n, Cannot open file If the error is Cannot open file, you have specified a nonexistent snapshot file to restore from. Check your filename. Other errors indicate that the disk or relevant files are read only or otherwise unwriteable (disk full, etc.). Repair the file protections, free disk space (only a few kilobytes are usually needed), or mount the disk, as needed. Restore from filename failed, error code n, Cannot rewrite current database file Restore from filename failed, error code -3, Write error when transferring database RestoreInvalid Admin Can be one of the following: The restore operation was not started. Correct the filename. Restore from filename failed, error code -4, Invalid filename Restore from filename failed, error code -5, Filename is in use RestoreOK Admin Restore from filename complete UUID Emergency ORB_object_copy_t o_string on DS server object failed Write Emergency Write error to ds.tmp; cannot write changes Informational message. No action required. The DS was started with a bad UUID parameter. Correct the UUID being passed to the DS on the command line (first parameter). While attempting to write the directory to a temporary file, the DS encountered an error during a flush() operation. Check the status of ds.tmp and that it is not locked, and try the write again. Issue 1.0 June 2002 103

Chapter 5 The Directory Server 104 Core Services Programmer s Guide

CHAPTER 6 THE DATA CONNECTOR SERVER Overview The Avaya Connector Data Server (Data Server) is a vesp server that monitors and processes requests between the Avaya Business Application and its database(s). In both UNIX and Windows environments, the Data Server can be configured to run on either the database server or on a stand-alone server. The Data 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. The Data Server provides database independence for the Avaya Business Applications. The connection information that is stored in the IC Data Source determines which database the Business Application connects to and what style of SQL to generate. Compared to direct database connections, the Data Server connection has little state information. Therefore, it is possible for an application to re-establish a connection to a database by simply starting a new instance of the Data Server or, in the case of Automatic Failover, switching to a new server running another instance of the Data Server. The Data Server is configured and started by the IC Manager. For more information on configuring and starting Avaya servers, refer to IC Administration Volume 1: Servers & Domains. 105

Chapter 6 The Data Connector Server Data Server Architecture The following diagram illustrates the four central points that describe the Data Server s architecture: Application Client Network Data Server-- 3 unused database connections in DB Connection Pool Database Connection Pool Application Client Confirm Login Database Login Request Directory Server authentication against agent table Single Database Login The four central points of the Data Server architecture are: Handling request through a set of threads. Logging into the database server using a single login specified in IC Manager. Using a connection pool to allow quicker access to a tunable number of database connections. The Data Server performs the following steps to offer a connection to a database server: 1 Receives requests from already authenticated vesp client or server. 2 Confirms the pool of database connections exists. 3 Waits for the client database access request. 4 Accesses the database connection. 5 Executes the database request. The Data Server then returns to step 3 and waits for additional database requests. The Data Server logs into the database server using one user account with admin privileges. The Data Server enforces workgroup permissions by checking the user s workgroup with the Directory Server. As the administrator, you can establish database access for system users through their roles and corresponding privileges in IC Manager. For more information, see IC Administration Volume 2: Agents, Customers, & Queues. 106 Core Services Programmer s Guide

Overview Client Authentication All the services of the Data Server are VESP services and hence the Data Server accepts requests only from a vesp-authenticated client. The client has to login with a user id that is specified in IC Manager for the agent before it can access the database through the Data Server. For more information on setting client login and password values, see IC Administration Volume 2: Agents, Customers, & Queues. Connection Pool Concepts A connection pool makes a set of database connections available for each database server. A pool offers two advantages over database connections that are allocated directly to each client. Tunable number of database connections efficiently allocated and deallocated. Increased bandwidth for each allocated database connection. Each Data Server thread must get access to an available database connection from the pool before executing a database operation. You can set the connection pool parameter to define the maximum number of database connections per connection pool. You should consider these items in setting this value: 1 Number of licensed client connections. Shared Server Features Log File Naming 2 Number of simultaneous client connections. 3 Database connection timeout value. 4 Average turnover of database connections in a given period. 5 Time-based client connection statistics (for example, duration and idle time). The Data Server shares the same features as the other IC Manager servers employed by Avaya. IC Manager bases the log file name on the Data Server name that you selected when creating the Data Server instance. Issue 1.0 June 2002 107

Chapter 6 The Data Connector Server Configurable Error Logging To detect error conditions, you can set four different levels of error logging. Select the appropriate value in the Log Level field on the DataServer tab at the Data Server configuration window. Logging Level Failover Capability 0 VESP error logging 1 Data Server-specific error logging 2 Client connection error logging 3 Database connection error logging The Data Server shares failover capabilities with other servers. If the Data Server goes down, the ORB Server restarts the Data Server whenever any component makes a request to the Data Server. This is possible because all of the services of the Data Server are VESP services. The Data Server should normally be set to start automatically when configured in IC Manager. Configuration The Data Server configuration window in IC Manager contains the parameters that must be modified when configuring a Data Server. The Data Server is not application specific, but specific to the database vendor. 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. Label Test Database user name (User) Password (Password) DBA Login (DbaUser) DBA Password (DbaPassword) Request Handler Thread Pool Size (ClientThreadPoolSize) DB Connection Pool Size (ConnectionPoolSize) This parameter brings up a dialog that enables you to test the database connection. Database login used by DB connection pool for a particular database instance. Database password used by DB connection pool for a particular database instance. Database login used by the database administrator for a particular database instance. Database password used by the database administrator for a particular database instance. Maximum number of threads that can handle client requests in the Data Server. The threads accept requests from the Data Server clients and queues for database threads to be executed in the database. This number is always less than the total number of clients connected to the database. Default is 10. Maximum number of database connections to open in a connection pool. Minimum is 0. Default is 10. 108 Core Services Programmer s Guide

Connecting to the Data Server Label Database Connection Timeout (min) (DBConnectionTimeout) DB Heart Beat Interval (min) (DBHeartBeatInterval) DB Retry Interval (sec) (DBRetryInterval) Database connection timeout in minutes. Prevents inactive database connection from remaining allocated. Default is 10. The interval at which the system checks to verify the database is still up and running or detects that it is down. Minimum is 1. Default is 1. If the system finds that the database is down, the interval at which the system checks to see if the database is back up and running. Minimum is 1. Default is 5. Server Executables The server executables (present in the <install_dir>\avaya_home\ic60\bin directory) are named according to the installed database: qorasrv.exe Oracle qsqlsrv.exe SQL Server qlegacydbsrv.exe legacy dataserver godbcsrv.exe ODBC The interface names or the type names in IC Manager are different for Data Servers of different database types, For example: DataServerMSSQL for SQL Server DataServerOracle for Oracle DataServerDB2 for DB2 DataServerODBC for ODBC DataServerLegacy for Legacy databases Connecting to the Data Server Special Considerations for DB2 on Windows NT/2000 On DB2, the Data Server must run as the db2admin user (or any user with DB2 administrator privileges) for every data server that needs to create databases on the DB2 server. For information on setting up connections to more than one DB2 database, see IC Database Designer Application Reference. Issue 1.0 June 2002 109

Chapter 6 The Data Connector Server Database Events The Data Server has a separate thread per connection pool to poll the database to detect connectivity problems between the Data Server and the database. The frequency of polling is configured by setting the DB Heart Beat Interval parameter in IC Manager to the desired time in minutes. This thread checks for a database connection each time this interval period elapses or whenever there is a database error. Once the thread detects the database connection is down, it first sends an alarm and then it tries to connect to the database until it reconnects. The period of time between attempts to reconnect to the database is configured in the DB Retry Interval parameter in IC Manager. This interval should be shorter in time than the DB Heart Beat Interval parameter. Once the connection between the Data Server and the database is reconnected, the thread returns to polling the database to detect any further connectivity problems. Running in Different Timezones In many organizations, the primary database is accessed by client machines in many different timezones. This raises the necessity to synchronize the database across timezones. Avaya Interaction Center has created new time definitions to add flexibility to the way database time is displayed on the client. For more information about database time settings, see Mapping ODBC Types to Database Designer Data Types, on page 116. There are two main considerations with time: Timezone adjustments regulate the time display when the database is in a different timezone than the clients. System clock adjustments regulate the time display between the database machine clock and the client machine clock. For example, if the database machine time is 10:27 and the client machine is 2:33, the timezone adjustment is four hours and the system time adjustment is six minutes. The IC Data Source setting to correct this behavior, made using Database Designer, is DISPLAY_TIME which accepts three values: HOSTTIME LOCALTIME DBMSTIME 110 Core Services Programmer s Guide

Running in Different Timezones DISPLAY_TIME= HOSTTIME The DISPLAY_TIME= HOSTTIME setting provides compatibility with CustomerQ. The database machine time is converted to local machine time (and vice versa) by applying the difference between the two system clocks. Effectively, both the timezone and system clock adjustments are applied to all times. The primary advantage to using HOSTTIME instead of the LOCALTIME setting is that the IC Script function Now(), which returns the host s current time, can be used in data arithmetic to set database fields where the result is automatically corrected to the database s current time. The primary disadvantage of this manifests itself when entering absolute times like 10:00, which are also adjusted for the small difference between system clocks. For example, 10:00 could be inserted into the database as 9:57, then displayed on another client as 10:02. DISPLAYTIME= LOCALTIME The DISPLAYTIME= LOCALTIME setting overcomes the disadvantage of DISPLAYTIME= HOSTTIME by making the timezone adjustment only to the times received and sent to the database. This works by comparing the difference between the client host time and database host time at startup, then rounding to the nearest hour. If the database time is 8:07 and the local host time is 9:05, the timezone adjustment is one hour and therefore times from the database are adjusted by one hour. In this case, entering 10:00 on the client results in 9:00 being inserted into the database. Another client in the same timezone as the first client also sees 10:00. The keyword now in datetime fields has a special meaning. The client applies the system clock adjustment to get an absolute value for now. Note that only the system clock adjustment is applied. Thus, if the client were to get the value of now in the previous example, it would return 9:07 which is the database current time adjusted to the local timezone. When this is inserted into the database it is adjusted, as with all times, by the timezone adjustment to become 8:07 in the database. Unfortunately, the IC Script function Now() does not apply the system clock adjustment, allowing small errors in times entered in the database from the IC Scripts using the function. In many cases, the keyword now can be used for setting database fields in IC Scripts. However, if some date arithmetic is required, then a new IC Script method of the class CustomerQ.DBTable has been added to return the database time adjusted to the local timezone. This method is called DBNow() and can be used in place of Now(). For new applications, or applications written without the IC Scripts function Now(), this is the recommended setting. DISPLAYTIME= DBMSTIME The DISPLAYTIME= DBMSTIME setting makes no adjustment to time received or sent by the database. All times are displayed in database time. The time 11:55 in a database field is displayed on all clients as 11:55. In this instance, the keyword now has to make both the timezone adjustment and system clock adjustment to get an absolute value for now. Thus, if the database time is 11:55 and the client host time is 14:57, then the value of now as displayed on the client would be 11:55. Similarly, the new IC Script method DBNow() returns the current database time as it appears on the database host. Issue 1.0 June 2002 111

Chapter 6 The Data Connector Server Timestamps This setting is probably most useful when the database runs in the GMT timezone. In this case, all clients in all timezones view all times in GMT. Header strings that are inserted into long text and history fields contain the display time value of Now() followed by the offset from the database time, if the display time is different from the database time. For example, if the database time is 8:07 and the client hosttime is 9:05, the long text header would be: HOSTTIME: ###### cheris(support) 10 Apr 1998 09:05:21 (+00:58) LOCALTIME: ###### cheris(support) 10 Apr 1998 09:07:24 (+01:00) DBMSTIME: ###### cheris(support) 10 Apr 1998 09:07:24 No offset is displayed when DBMSTIME is used, or when LOCALTIME is used and the client and database are in the same timezone. Datetime fields contained in history entries are always in display time. Note: The Timestamp value is always the application machine time, not necessarily the DBMS time. For example, if the database is in a different time zone than the application machine, the timestamp for a record will use the time of the application machine. ODBC Data Source Interface Notes ODBC Setup The ODBC interface enables access to various data sources through the Windows ODBC interface. Note: Unlike other database interfaces, the ODBC interface is used only for secondary connections. This means that while the client can access data through this interface, Database Designer cannot configure a data source through this interface. The Data Server cannot start with a primary ODBC data source nor with a Data Server that is defined with only an ODBC datasource. Unlike the other database interfaces, some ODBC drivers may not support all of the SQL commands that a Business Application issues. In virtually all cases, you can adjust the ADL data model to avoid generating SQL that is not supported. A list of requirements and workarounds follows. Also, while the DBMS type ODBC does not require driver support for stored procedures, it does not support the Business Application s database locking either. The ODBC interface implemented for the Business Application uses the ODBC Version 3 library, which means that the ODBC installed on the database server must be Version 3. ODBC Version 3 is standard with Windows NT Service Pack 3. ODBC Version 3 is backward compatible with ODBC Version 2 drivers, so you can connect to any data source that has Version 2 or Version 3 drivers. At this time the Business Application does not make use of any Version 3 specific features such as interval types. ODBC must be correctly configured on the Data Server machine. 112 Core Services Programmer s Guide

ODBC Data Source Interface Notes The ODBC Data Source Administrator (Settings ControlPanel ODBC) contains the version numbers for both the ODBC Driver Manager version and the database specific driver. Check the About tab to ensure the Driver Manager is Version 3.0 or greater. Running the Data Server with an ODBC database type requires ODBC drivers version 2 or version 3. ODBC database drivers are typically installed as part of a database client installation. These drivers must then be initialized as System DSN drivers. You can configure two types of data sources for ODBC: Database specific, which points to a named database on a specific database server. General, which points to the database server only. In this instance the database is not named. The Avaya ODBC interface sets the current catalog property to use a specific database. Some database drivers will not work without naming the database. Testing the connection to the database will quickly determine this. Adding an ODBC Data Source To add an ODBC Data Source to your environment, from the Data Server machine: 1 Open ODBC Data Sources from the Control Panel. 2 Select the System DSN tab. 3 Click Add. 4 Select the database driver with which you will set up the data source. 5 Click Finish. 6 In the <driver specific> ODBC Setup screen, add the items specific to your database driver. Each database driver requires different ODBC information. See your database driver documentation for more information. Issue 1.0 June 2002 113

Chapter 6 The Data Connector Server 7 Click OK. The Data Source name is now listed on the System DSN tab. ODBC Driver Requirements The following table lists the functions and ODBC SQL escapes that must be supported by an ODBC driver for it to work with a Business Application. If the driver does not support the ODBC SQL escapes, certain workarounds may be attempted. They are also listed. Requirements Driver supports the LCASE function Driver supports the NOW function in a SELECT list Driver supports the outer join escape syntax Workarounds Define Char/Varchar fields as case sensitive in the Database Designer. Datetimes will not be converted between database time and local time or corrected for small clock differences. Do not define browsers with foreign fields in them (unless the foreign key in the anchor table is a required field). ODBC Limitations Because of the limitations of some drivers that do support outer joins, only one outer join is ever generated in ODBC SQL. Therefore, you should avoid defining browsers that contain more than one foreign field in them. 114 Core Services Programmer s Guide

ODBC Data Source Interface Notes The ODBC interface does not require the use of stored procedures. Key generation is performed by two SQL statements rather than a call to q_next_key and application locking is not supported. As a result the Business Application s ODBC interface only requires that an ODBC driver support core level conformance in the ODBC 3 terminology. If a driver supports level 2 conformance, specifically the ability to call stored procedures that can return results in output arguments, then the ODBC2 interface can be used. This invokes the q_next_key stored procedure and supports application locking. The stored procedures themselves could be based on the current Business Application stored procedures for other RDBMSs or could interface with some other application's procedures. The key generation supported by the ODBC interface requires that the database has a table called qw_keys with fields tablename and value, with an entry for each table to which the Business Application can add records. If the database has some other mechanism for allocating keys then the key field could be defined as Integer rather than Serial and a new table rule IC Script could generate a value for it. The qw_keys table is also used to perform a SELECT to get the current database time and so should contain at least one record to enable this to work. For long text fields, a 1 instead of the column name or length function is placed in the select list as there is no reliable way to determine whether a column contains long text data without actually fetching the whole thing. Although ODBC has some attributes to limit the amount of data returned for a field, these do not have to be enforced. As a result, HasValue returns true for a long text even if it does not have a value (until the request to fetch the data is made). ODBC and Database Name Setting Different ODBC drivers support different configurations. For example, the various ODBC drivers react differently to the attempt of the Business Application ODBC interface to set the current catalog when it logs into a data source. With some drivers, this attempt causes the equivalent of use database to be executed, which means you can configure a single ODBC data source to refer to a database instance and access many databases from that ODBC data source. The DBMS_NAME connection setting then determines which database is used. However, some drivers don't support a configuration that allows access to many databases. Therefore, you must specify the database/schema in the data source configuration In other words, if you have three databases in the same database instance you need to define three separate ODBC data sources. If you are defining several separate ODBC secondary data sources and leave the DBMS_NAME field blank, that DCO will not try to determine the current time on the database host at start up. Issue 1.0 June 2002 115

Chapter 6 The Data Connector Server Mapping ODBC Types to Database Designer Data Types The following table shows the best Database Designer data type to use for a given ODBC type. ODBC Type Database Designer Data type ODBC Type SQL_CHAR Character SQL_BIT Byte SQL_VARCHAR Variable Char (acter) SQL_TINYINT Byte Database Designer Data type SQL_LONGVARCHAR Text SQL_BIGINT not supported SQL_DECIMAL Float SQL_BINARY Binary SQL_NUMERIC Float SQL_VARBINARY Binary SQL_SMALLINT Short Integer SQL_LONGVARBINARY Binary SQL_INTEGER DcoIntegerE SQL_DATE Date SQL_REAL Float SQL_TIME Date Time SQL_FLOAT Float SQL_TIMESTAMP Date Time SQL_DOUBLE DoubleE SQL_INTERVAL_* not supported The DECIMAL/NUMERIC types map to integer or float depending on the scale property of the database column. 116 Core Services Programmer s Guide

CHAPTER 7 AVAYA IC ORB ROUTINES This chapter contains a list of Avaya IC ORB routines, organized in functional groups. Each function is described in detail in Chapter 7. To access these routines, include the file orb.h and link in the toolkit libraries. BOA Routines (Basic Object Adapter) BOA_change_implementation BOA_create BOA_deactivate_impl BOA_deactivate_obj BOA_delete_method BOA_dispose BOA_get_id BOA_get_principle BOA_impl_is_ready BOA_obj_is_ready BOA_set_exception BOA_set_method 117

Chapter 7 Avaya IC ORB Routines Context Routines Context_create_child Context_delete Context_delete_values Context_get_configuration Context_get_one_seq_config_value Context_get_one_seq_value Context_get_one_value Context_get_values Context_print Context_set_values Hybrid API Routines Vesp_Assign_Request Vesp_Deassign_Request Vesp_Request Vesp_Request_Sync Hybrid DDE API Routines Vesp_DDE_get_next_response Vesp_Request_DDE Vesp_Request_DDE_sync Hybrid Common API Routines Vesp_Change_Password Vesp_Force_Password Vesp_Get_Default_Session Vesp_Load_Implementation 118 Core Services Programmer s Guide

Hybrid Client Routines Vesp_Load_Interface Vesp_poll Vesp_Reload_Imp Vesp_Reload_Imp_Local Vesp_Request_Delete Vesp_Send_Alarm Vesp_Send_Alarm_No_History Vesp_Session_Create Vesp_Session_Delete Hybrid Client Routines Vesp_Login Vesp_Logout Vesp_Set_Client_Port Hybrid Server Routines Vesp_Server_Login Vesp_Server_Login_Local Server_set_user_init_routine Server_set_user_poll_routine Server_set_user_exception_routine Server_set_user_exit_routine Server_set_client_terminate_routine Server_set_status_hook_routine Issue 1.0 June 2002 119

Chapter 7 Avaya IC ORB Routines Memory Routines These memory routines must be used with the Avaya IC hybrid functions. vesp_calloc vesp_free vesp_realloc vesp_strdup vesp_dump_heap vesp_lose_heap vesp_heap_check vesp_heap_check_value vesp_get_heap_size free_breakpoint_routine Allocate and clear memory Free memory Reallocate memory with new size Duplicate a string Print all allocated memory information to log file Forget about memory already allocated Force a check for bad allocations Check if value is allocated by vesp routines How much memory is allocated This routine gets called only when a vesp_free fails 120 Core Services Programmer s Guide

Miscellaneous Routines Miscellaneous Routines vesp_get_connect_timer vesp_set_connect_timer vesp_set_local_time vesp_set_gmt_time vesp_get_trace_level vesp_set_tracing vesp_set_exception vesp_get_server_version vesp_get_toolkit_version vesp_set_server_version vesp_time vesp_time2 vesp_format_time vesp_log_info log_unparsable vesp_print_any vesp_print_environment flush_log close_log vesp_set_log_name vesp_find_error the maximum number of seconds that may elapse before a time out when attempting to connect to a server that does not exist. Set the maximum number of seconds that may elapse before a time out when attempting to connect to a server that does not exist. Put Avaya IC in local time mode. Put Avaya IC in GMT time mode Get current trace level Set trace level Format exception information Get string describing server version Get the current trace level Set string describing server version Get time as a string Get time as a string with millisecond information Get specified time as a string Print a new entry into the log file Print more stuff into the log file Print any data type to the log file Print an environment variable to the log file Flush information in buffer to log file Close the log file Switch logging to another file Convert an ORBStatus value to a descriptive string. NVList Routines (Named Value List) NVList_add_item NVList_free NVList_free_memory NVList_get_count NVList_get_values Issue 1.0 June 2002 121

Chapter 7 Avaya IC ORB Routines NVList_print NVList_set_values ORB Routines (Object Request Broker) ORB_create_context ORB_create_list ORB_create_operation_list ORB_get_default_context ORB_get_session_lifetime ORB_object_copy_to_string ORB_object_to_string ORB_print_ev ORB_set_session_lifetime ORB_string_copy_to_object ORB_string_to_object ORB Object Routines (Server Objects) Object_compare Object_create_request Object_decode Object_duplicate Object_is_nil Object_print Object_release 122 Core Services Programmer s Guide

Request Routines Request Routines Request_defer Request_delete Request_get_ev Request_get_group Request_get_response Request_send Request_send_deferred_response Session Routines Session_change_group Session_create_request Session_delete Session_delete_request Session_exist Session_get_context Session_get_message_timeout Session_print Session_send Session_send_event Session_set_context Session_set_message_timeout Issue 1.0 June 2002 123

Chapter 7 Avaya IC ORB Routines Support Routines vesp_couple_create vesp_couple_set_values vesp_couple_delete vesp_couple_seq_create vesp_couple_seq_delete vesp_couple_seq_add_couple vesp_couple_seq_add_couple_values vesp_couple_seq_duplicate vesp_dup_seq_couple_value vesp_couple_seqseq_add_seq vesp_couple_seqseq_create vesp_couple_seqseq_delete vesp_couple_seqseq_duplicate vesp_event_add_couple vesp_event_create vesp_event_delete vesp_event_duplicate vesp_string_seq_add_value vesp_string_seq_create vesp_string_seq_duplicate vesp_string_seq_delete Allocate a Couple Set the name and value of a Couple Deallocate a Couple Allocate a sequence of Couples Deallocate a sequence of Couples Add a Couple to a sequence of Couples Add a Couple to a sequence of Couples by giving name and value Clone a sequence of Couples Get a value from a sequence of Couples by name Add a sequence of Couples to a sequence of sequences of Couples Allocate a sequence of sequences of Couples Deallocate a sequence of sequences of Couples Clone a sequence of sequences of couples Add a couple to an event Allocate an event Deallocate an event Duplicate an event Add a string to a sequence of strings Allocate a sequence of strings Clone a sequence of strings Deallocate a sequence of strings 124 Core Services Programmer s Guide

Internal Network Routines Internal Network Routines vnet_status vnet_destroy vnet_setusersoc_callback Log networking information Release all sockets (for exec) Set callback for socket read activity Timed Routines Vesp_Timed_Function_Delete Vesp_Timed_Function_Poll Vesp_Timed_Function_Register Vesp_Timed_Function_Reset Vesp_Timed_Function_Print Delete a timed function Poll a timed function Register a timed function Reset the time for a timed function Print a timed function Issue 1.0 June 2002 125

Chapter 7 Avaya IC ORB Routines 126 Core Services Programmer s Guide

CHAPTER 8 AVAYA IC TOOLKIT FUNCTIONS This chapter contains an alphabetical listing of the Avaya IC API functions. Function s Each description of a function contains: A description of the function A brief description of each function's arguments What the function returns BOA_change_implementation Syntax void BOA_change_implementation( BOA boa, Environment *ev, Object obj, ImplementationDef impl ); Refer to the OMG CORBA Specification for a complete description. Not currently supported. None BOA_create Syntax Object BOA_create( BOA boa, Environment *ev, ReferenceData ref, InterfaceDef interface, ImplementationDef impl ); Refer to the OMG CORBA Specification for a complete description. Not currently supported. None BOA_deactivate_impl Syntax void BOA_deactivate_impl( BOA boa, Environment *ev, ImplementationDef impl ); Refer to the OMG CORBA Specification for a complete description. Not currently supported. 127

Chapter 8 Avaya IC Toolkit Functions None BOA_deactivate_obj Syntax BOA_deactivate_obj( BOA boa, Environment *ev, Object obj ); Refer to the OMG CORBA Specification for a complete description. Not currently supported. None BOA_delete_method Syntax ORBStatus BOA_delete_method( BOA boa, Environment *ev, Object object ); : Refer to the OMG CORBA Specification for a complete description. Not currently supported. None BOA_dispose Syntax void BOA_dispose( BOA boa, Environment *ev, Object object ); Refer to the OMG CORBA Specification for a complete description. Not currently supported. None BOA_get_id Syntax ReferenceData BOA_get_id( BOA boa, Environment *ev, Object obj ); Refer to the OMG CORBA Specification for a complete description. Not currently supported. None BOA_get_principle Syntax Principal BOA_get_principle( BOA boa, Environment *ev, Object obj, Environment principle_ev); Refer to the OMG CORBA Specification for a complete description. Not currently supported. None 128 Core Services Programmer s Guide

BOA_impl_is_ready BOA_impl_is_ready Syntax void BOA_impl_is_ready( BOA boa, Environment *ev, implementationdef impl ); Refer to the OMG CORBA Specification for a complete description. Not currently supported. None BOA_obj_is_ready Syntax BOA_obj_is_ready( BOA boa, Environment *ev, Object obj, implementationdef impl); This function is used internally by Avaya IC to tell the ORB Server that a server started by the ORB Server has successfully started. Refer to the OMG CORBA Specification for a complete description. None BOA_set_exception Syntax void BOA_set_exception( BOA boa, Environment *ev, exception_type major, char *userid, void *param); Set a user or system level exception in a server method. Refer to the OMG CORBA Specification for a complete description. Not currently supported; please use vesp_set_exception. None BOA_set_method Syntax ORBStatus BOA_set_method( BOA boa, Environment *ev, Object object, Identifier operation, ULONG system_auth, ULONG user_auth. ULONG method ); This function registers a server's method with the ORB Server. This is usually done at server initialization time. A maximum of 128 methods is currently allowed per server. boa ev object Must have the value VESP_BOA. Environment variable. Object handle of this server. Issue 1.0 June 2002 129

Chapter 8 Avaya IC Toolkit Functions operation system_auth user_auth. method Operation of this method. System security bit mask. Refer to Chapter 0 for information on security levels. User security bit mask. Refer to Chapter 0 for information on security levels Address of the method to execute. VESP_BAD_PARAMETER Bad parameter passed to function Example SCHECK (BOA_set_method( VESP_BOA, &ev, object, "Echo", 0, 0 (ULONG)Test_Echo ) ); Context_create_child Syntax ORBStatus Context_create_child( Context ctx, Environment *ev, Identifier ctx_name, Context *child_ctx); Refer to the OMG CORBA Specification for a complete description. Not currently supported. VESP_BAD_PARAMETER Bad parameter passed to function Context_delete Syntax ORBStatus Context_delete( Context ctx, Environment *ev, Flags def_flags ); Delete a context. Used internally by Avaya IC. ctx ev def_flags Context to delete. An environment variable filled when an error is detected. Reserved for internal use. 130 Core Services Programmer s Guide

Context_delete_values VESP_BAD_PARAMETER VESP_NOT_FOUND VESP_BAD_MAGIC_NUMBER Bad parameter passed to function Context was not found Corruption of the NVList has occurred Context_delete_values Syntax ORBStatus Context_delete_values( Context ctx, Environment *ev, char *prop_name ); Refer to the OMG CORBA Specification for a complete description. Not currently supported. VESP_BAD_PARAMETER Bad parameter passed to function Context_get_configuration Syntax ORBStatus Context_get_configuration( Context ctx, Environment *ev, _IDL_SEQUENCE_Couple **cp); Return a copy of the sequence of couples corresponding to information saved in the configuration field in IC Manager for both client and servers. The context that holds the configuration is bound to the default session that is created when the server starts or the client logs into Avaya IC. ctx ev cp Context. An environment variable filled when an error is detected. Copy of sequence of couples matching configuration. VESP_NOT_FOUND Configuration was not found Issue 1.0 June 2002 131

Chapter 8 Avaya IC Toolkit Functions Example /* * Get default session, and config from that. * Print out the Servers or clients configuration information */ */ SCHECK( Vesp_get_default_session(object, &sess)); SCHECK( Session_get_context(sess, &loc_ev, &ctx)); SCHECK( Context_get_configuration(ctx, &loc_ev, &configseq) ); if (configseq!=null) { for (i = 0; i < configseq->_length; ++i) { PRINT( LOGFILE, name=%s, value=%s\n, configseq->_buffer[i].name, configseq->_buffer[i].value; } } Context_get_one_seq_config_value Syntax ORBStatus Context_get_one_seq_config_value( Context ctx, Environment *ev, char *name, char **value); Because Context elements can only be strings, a method of storing more complex data types was needed. Sequence of couples can be converted to strings. This function scans the Context value for the specified configuration couple pair. The configuration values are entered through IC Manager. ctx ev name value Context. An environment variable filled when an error is detected. Name of sequence element in ctx_value_name to look for. String found, this is allocated and must be freed with vesp_free. VESP_BAD_PARAMETER VESP_NOT_FOUND Bad parameter passed to function Context was not found 132 Core Services Programmer s Guide

Context_get_one_seq_value Example SCHECK( Vesp_get_default_session( object, &sess )); SCHECK( Session_get_context( sess, ev, &ctx )); /************************************************************ * Get imp autoload flag * If set to true load new inp file!!! *************************************************************/ Context_get_one_seq_config_value( ctx, ev, autoloadimp, & buf ); if (ev->_major == NO_EXCEPTION ) { if (!strcmp( buf, true ) ) { vesp_free( buf ); /*load new file and load new copy of imp into memory SCHECK( Vesp_Reload_Imp(resource->object ) ); } else vesp_free( buf ); } Context_get_one_seq_value Syntax ORBStatus Context_get_one_seq_value( Context ctx, Environment *ev, char *ctx_value_name, char *name, char *value); Because Context elements can only be strings, a method of storing more complex data types was needed. Sequence of couples can be converted to strings. This function scans the Context value for the specified couple pair. ctx ev ctx_value_name name value Context. An environment variable filled when an error is detected. Name of element in context that contains sequence in string from. Name of sequence element in ctx_value_name to look for. String found; this is allocated and must be freed with vesp_free. VESP_BAD_PARAMETER VESP_NOT_FOUND Bad parameter passed to function Context was not found Example SCHECK( Vesp_get_default_session( object, &sess )); SCHECK( Session_get_context( sess, ev, &ctx )); /************************************************************ * Get trace info *************************************************************/ Issue 1.0 June 2002 133

Chapter 8 Avaya IC Toolkit Functions Context_get_one_seq_value( ctx, ev, configuration, trace, & buf ); if (ev->_major == NO_EXCEPTION ) { if ( strstr( buf, idl )!= NULL { vesp_trace_level = vesp_trace_level VESP_TRACE_IDL_CODING; } if ( strstr) buf, heap )!= NULL { vesp_trace_level = vesp_trace_level VESP_HEAP_CHECK; }.. vesp_free( buf ); } else { vesp_trace_level = OUL; } return ( ); } Context_get_one_value Syntax ORBStatus Context_get_one_value( Context ctx, Environment *ev, char *scope, char *name, char **value ); Get a specific value from the context. ctx ev scope name value Context. An environment variable filled when an error is detected. Scope of search, currently ignored. Name of sequence element in ctx_value_name to look for. String found, this is allocated and must be freed with vesp_free. VESP_BAD_PARAMETER VESP_NOT_FOUND Bad parameter passed to function Context was not found 134 Core Services Programmer s Guide

Context_get_values Example /* get and save the group info of client or server */ SCHECK( Vesp_get_default_session(object, &sess) ); SCHECK( Session_get_context(sess, &loc_ev, &ctx) ); Context_get_one_value( ctx, ev, *, group, &buf ); if (ev->_major = NO_EXCEPTION) { PRINT( LOGFILE, value of group=%s\n, buf ); /* have to free memory only a copy */ vesp_free( buf ); } Context_get_values Syntax ORBStatus Context_get_values( Context ctx, Environment *ev, Identifier start_scope, Flags op_flags, Identifier prop_name, NVList *values); Refer to the OMG CORBA Specification for a complete description. Used internally by Avaya IC. VESP_BAD_PARAMETER VESP_NOT_FOUND VESP_BAD_MAGIC_NUMBER Bad parameter passed to function Context was not found Corruption of the NVList has occurred Context_print Syntax ORBStatus Context_print( Context ctx, Environment *ev ); Print the contents of a context to the logfile. ctx *ev Context. An environment variable filled when an error is detected. VESP_BAD_PARAMETER Bad parameter passed to function Issue 1.0 June 2002 135

Chapter 8 Avaya IC Toolkit Functions Context_set_values Syntax ORBStatus Context_set_values( Context ctx, Environment *ev, NVList values ); Refer to the OMG CORBA Specification for a complete description. Used internally by Avaya IC. VESP_BAD_PARAMETER VESP_NOT_FOUND VESP_BAD_MAGIC_NUMBER VESP_NO_SPACE Bad input parameter Context was not found Corruption of the NVList has occurred No more space to store entry into flush_log Syntax void flush_log( void ); Flush anything that is in the log file buffer. Calls the fflush() function. None Example /*This is the source code for flush_log*/ void flush_log(void) { if (logfile!= NULL) flush(logfile); } free_breakpoint_routine Syntax void free_breakpoint_routine( void); This routine is called when memory, not allocated by Avaya IC, is freed by vesp_free. Use this as a break point; problems involving bad address that are freed are hard to resolve. None log_unparsable Syntax void log_unparsable( char *format,... ); 136 Core Services Programmer s Guide

NVList_add_item Write additional information to the log for an entry started with vesp_log_info. log_unparsable() is for text that is intended to be human-readable, not machine parsable. This function takes printf() type arguments. log_unparsable() should be preceded by a call to vesp_log_info(), which provides a formatted header (including timestamp) for the log entry. None Example vesp_log_info( VESP_CAT_ALL, Put level here, Put description here ); log unparsable( Login object=%s, temp ); NVList_add_item Syntax ORBStatus NVList_add_item( NVList item_handle, Environment *ev, Identifier item_name, TypeCode type, void *value, long value_len, Flags item_flags ); Add an item to an NVList created with a call to ORB_create_list. You cannot add more items than specified in the ORB_create_list function. This is used internally by Avaya IC. Refer to the OMG CORBA Specification for a complete description. item_handle ev item_name type value value_len item_flags A handle that uniquely identifies the NVList. An environment variable that is filled when an error is detected. Name of item to add to NVList. Type of the item to be added to the NVList. Value of the item to be added to the NVList. Length of the item to be added to the NVList. Flags for item includes IN_ARG, OUT_ARG. VESP_NO_SPACE VESP_BAD_PARAMETER VESP_BAD_MAGIC_NUMBER No more space to store entry into Bad input parameter Corruption of the NVList has occurred Issue 1.0 June 2002 137

Chapter 8 Avaya IC Toolkit Functions NVList_free Syntax ORBStatus NVList_free( NVList item_handle, Environment *ev ); Delete all the memory allocated with an NVList. Refer to the OMG CORBA Specification for a complete description. This is used internally by Avaya IC. item_handle ev A handle that uniquely identifies the NVList. An environment variable filled when an error is detected. VESP_BAD_PARAMETER VESP_BAD_MAGIC_NUMBER Bad input parameter Corruption of the NVList has occurred NVList_free_memory Syntax ORBStatus NVList_free_memory( NVList item_handle, Environment *ev ); Free all the NVList items with the OUT_ARG flag set. Refer to the OMG CORBA Specification for a complete description. This is used internally by Avaya IC. item_handle ev A handle that uniquely identifies the NVList. An environment variable filled when an error is detected. VESP_BAD_PARAMETER VESP_BAD_MAGIC_NUMBER Bad input parameter Corruption of the NVList has occurred NVList_get_count Syntax ORBStatus NVList_get_count( NVList item_handle, Environment *ev, long *count ); Get the current count of items in the NVList. Refer to the OMG CORBA Specification for a complete description. 138 Core Services Programmer s Guide

NVList_get_values This is used internally by Avaya IC. item_handle ev count A handle that uniquely identifies the NVList. An environment variable filled when an error is detected. Number of items currently in the NVList. VESP_BAD_PARAMETER VESP_BAD_MAGIC_NUMBER Bad input parameter Corruption of the NVList has occurred NVList_get_values Syntax ORBStatus NVList_get_values( NVList item_handle, Environment *ev, Identifier start_scope, Flags op_flags, Identifier prop_name, NVList *values ); Get one or more values that match the prop_name and scope. Refer to the OMG CORBA Specification for a complete description. This is used internally by Avaya IC. item_handle ev start_scope op_flags A handle that uniquely identifies the NVList. An environment variable filled when an error is detected. Indicates the level at which to initiate the search. Indicator of whether the search should continue beyond the start level. prop_name Name of value to be found, includes wildcard *. values Values found that match the search criteria. Issue 1.0 June 2002 139

Chapter 8 Avaya IC Toolkit Functions VESP_BAD_PARAMETER VESP_BAD_MAGIC_NUMBER VESP_NOT_FOUND Bad input parameter Corruption of the NVList has occurred The item was not found NVList_print Syntax ORBStatus NVList_print( NVList item_handle, Environment *ev ); Print the contents of a NVList to the logfile. item_handle ev A handle that uniquely identifies the NVList. An environment variable filled when an error is detected. VESP_BAD_PARAMETER VESP_BAD_MAGIC_NUMBER Bad input parameter Corruption of the NVList has occurred NVList_set_values Syntax ORBStatus NVList_set_values( NVList item_handle, Environment *ev, NVList set_values); Set one or more values in an NVList. This function copies the information in set_values and then calls NVList_add_item for each item. Refer to the OMG CORBA Specification for a complete description. This is used internally by Avaya IC. item_handle ev set_values A handle that uniquely identifies the NVList. An environment variable filled when an error is detected. Values to be copies and added to the NVList. 140 Core Services Programmer s Guide

Object_compare VESP_BAD_PARAMETER VESP_BAD_MAGIC_NUMBER VESP_NO_SPACE Bad input parameter Corruption of the NVList has occurred No space available to store entry Object_compare Syntax ORBStatus Object_compare( Object object, Environment *ev, Object in_object ); Compare two objects. Refer to the OMG CORBA Specification for a complete description. object ev in_object A handle of type Object. An environment variable filled when an error is detected. Object to compare against. VESP_BAD_PARAMETER VESP_PARTIAL_SUCCESS IP, Port and time information match, exactly One of the Objects is bad Only IP and Port match Example status=object_compare( ev->session, &local_ev, ts_info->session ); if ( (status == VESP_PARTIAL_SUCCESS) (status == ) ); { PRINT( LOGFILE, Assign Duplicate phone number = %lx\n, status ); PRINT( LOGFILE, Had to delete old session\n ); Phone_list_delete( ts_info ); } else { PRINT( LOGFILE, Assign Duplicate phone number = %lx\n, status ); vesp_set_exception( ev, USER_EXCEPTION, VESP_ASSIGN_FAILURE, Only one session allowed per phone number: ); return( VESP_ASSIGN_FAILURE ); } Issue 1.0 June 2002 141

Chapter 8 Avaya IC Toolkit Functions Object_create_request Syntax ORBStatus Object_create_request( Object object, Environment *ev, Context ctx, Identifier operation, NVList arg_list, NamedValue *result, Request *request, Flags req_flags); Create a request to a specific Object. Refer to the OMG CORBA Specification for a complete description. This is used internally by Avaya IC object ev ctx operation arg_list result request req_flags A handle of type Object that uniquely identifies the object. An environment variable filled when an error is detected. Context to send to Object. Operation for Object to perform. Arguments to send to Object. Address of where to put the return result from the Object. Handle of type Object that identifies the newly created request. Flags for request creation. VESP_BAD_PARAMETER Bad parameter passed to function Object_decode Syntax void Object_decode( object, ev, time_high, time_low, reserved, ip, port, family ); Object object; Environment *ev; unsigned long *time_high; unsigned short *time_low; unsigned short *reserved; unsigned long *ip; unsigned short *port; unsigned char *family; Decode an Object reference into its Avaya IC specific pieces. 142 Core Services Programmer s Guide

Object_decode object ev time_high time_low reserved ip port family A handle of type Object that uniquely identifies the object. An environment variable filled when an error is detected. Time of creation in seconds since 1970 (from time()). Unique count to differentiate identical time_highs. Reserved for internal use. IP address of the creator of the object. Port address of the creator of the object. Single character definition of protocol type. Default is 2, which is TCP/IP. VESP_BAD_PARAMETER Bad parameter passed to function Issue 1.0 June 2002 143

Chapter 8 Avaya IC Toolkit Functions Example object_uuid = ORB_string_to_object( VESP_ORB, ev, uuid_str ); SCHECK( Object_decode(object_uuid, ev, &high, &low, &reserved, &zip, &port, &family) ); sprintf( *host, %lx, ip ); sprintf( *service, %x, port ); sprintf( *time_low, %x, low ); sprintf( *time_high, %lx, high ); sprintf( *version, %x, 0x00ff &reserved ); sprintf( *max_users, %x, (0x00ff & (reserved>>8) )); Object_release( object_uuid, &local_ev ); if( ip == 0 ) { vesp_set_exception( ev, USER_EXCEPTION, VESP_FAILURE, Could not decode UUID ); return( VESP_ERROR ); } return( ); Object_Duplicate Syntax Object Object_duplicate( Object object, Environment *ev ); Duplicate an Object. a copy of the Object. Space is allocated for the new Object. The Object must be deleted with the Object_release command. Refer to the OMG CORBA Specification for a complete description. object ev A handle of type Object that uniquely identifies the object. An environment variable filled when an error is detected. Object NULL The object that was duplicated If error Example Objectnew_obj; new_obj = Object_duplicate( old_object, &ev ); Object_release( new_obj, &ev ); Object_is_nil Syntax boolean Object_is_nil( Object obj, Environment *ev); : Check if an Object is empty. Refer to the OMG CORBA Specification for a complete description. 144 Core Services Programmer s Guide

Object_print object ev A handle of type Object that uniquely identifies the object. An environment variable filled when an error is detected. true false Object is nil Object is not nil Object_print Syntax ORBStatus Object_print( Object object, Environment *ev ); Print the Contents of an Object to the log. object ev A handle of type Object that uniquely identifies the object. An environment variable filled when an error is detected. VESP_BAD_PARAMETER object or ev was NULL Object_release Syntax void Object_release( Object object,environment *ev ); Free all storage associated with an Object. Refer to the OMG CORBA Specification for a complete description. object ev A handle of type Object that uniquely identifies the object. An environment variable filled when an error is detected. None Issue 1.0 June 2002 145

Chapter 8 Avaya IC Toolkit Functions Example Objectnew_obj; new_obj = Object_duplicate( old_object, &ev ); Object_release( new_obj, &ev ); ORB_create_context Syntax ORBStatus ORB_create_context( ORB orb_ref, Environment *ev, Identifier ctx_name, ULONG size, Context *ctx ); Create a new context. A context is automatically created when a server starts or a client logs in to Avaya IC. orb_ref ev ctx_name size ctx Pre-defined handle used specifically for Avaya IC's implementation of CORBA. The value is always VESP_ORB. An environment variable filled when an error is detected. Name of new context. Number of entries allowed in context. Context created. VESP_BAD_PARAMETER Bad parameter passed to function ORB_create_list Syntax ORBStatus ORB_create_list( ORB orb_ref, Environment *ev, long count, NVList*new_list); Create a new NVList. Refer to the OMG CORBA Specification for a complete description. orb_ref ev count new_list Pre-defined handle used specifically for Avaya IC's implementation of CORBA. The value is always VESP_ORB. An environment variable filled when an error is detected. Number of items to allocate for list. The created list. 146 Core Services Programmer s Guide

ORB_create_operation_list VESP_BAD_PARAMETER Bad parameter passed to function ORB_create_operation_list Syntax ORBStatus ORB_create_operation_list( ORB orb_ref, Environment *ev, OperationDef oper, NVList *new_list ); Create an NVList that is pre-defined with all the information of a specific operation. Refer to the OMG CORBA Specification for a complete description. Not currently supported. orb_ref ev ctx_name oper new_list Pre-defined handle used specifically for Avaya IC's implementation of CORBA. The value is always VESP_ORB. An environment variable filled when an error is detected. Name of new context. Operation to get the template from. List created with all the default information. VESP_BAD_PARAMETER Bad parameter passed to function ORB_get_default_context Syntax ORBStatus ORB_get_default_context( ORB orb_ref, Environment *ev, Context *ctx ); Get the default context for the ORB implementation. Refer to the OMG CORBA Specification for a complete description. orb_ref ev ctx Pre-defined handle used specifically for Avaya IC's implementation of CORBA. The value is always VESP_ORB. An environment variable filled when an error is detected. The default context. Issue 1.0 June 2002 147

Chapter 8 Avaya IC Toolkit Functions VESP_BAD_PARAMETER Bad parameter passed to function ORB_get_session_lifetime Syntax ORBStatusORB_get_session_lifetime( ORB orb_ref, Environment *ev, ULONG *lifetime ); Get the lifetime for all idle temporary sessions. All sessions that are established when a server receives a request from a client that is not assigned to it are temporary. If they remain idle for more than a certain lifetime, they are deleted. That lifetime is set when the session is created and reset each time the session is used. The breakdown (and possible recreation) of idle sessions is handled transparently by the toolkit, but it can impact performance. This routine is used to learn the idle lifetime that will be assigned to all temporary sessions. orb_ref ev lifetime Pre-defined handle used specifically for Avaya IC's implementation of CORBA. The value is always VESP_ORB. An environment variable filled when an error is detected. The lifetime (in seconds) assigned to all temporary sessions. VESP_BAD_PARAMETER Bad parameter passed to function Example ORBStatus Server_user_init(Object object) { ULONG default_lifetime; Environment ev; ORBStatus rval; /********************************************************************** *This server expects a lot of one-time-only method calls from strangers, *so we don t want temporary sessions around for more than a minute. ***********************************************************************/ rval=orb_get_session_lifetime(vesp_orb_, &ev, &default_lifetime); if(rval!=) return rval; if(default_liftime>60ul) { rval=orb_set_session_lifetime(vesp_orb, &ev, 60UL); 148 Core Services Programmer s Guide

ORB_object_copy_to_string } if(rval!+) return rval; } return ; ORB_object_copy_to_string Syntax ORBStatus ORB_object_copy_to_string( ORB orb_ref, Environment *ev, Object obj, char * buf ); Convert an Object to its string representation. This routine does NOT allocate space for the string. orb_ref ev obj buf Pre-defined handle used specifically for Avaya IC's implementation of CORBA. The value is always VESP_ORB. An environment variable filled when an error is detected. Object to convert to string. The string copied, make sure the string is at least 33 bytes long. VESP_BAD_PARAMETER Bad parameter passed to function ORB_object_to_string Syntax char* ORB_object_to_string( ORB orb_ref, Environment *ev, Object obj ); Convert an Object to its string representation. This routine allocates the space for the string and the string must be freed with the vesp_free function. Refer to the OMG CORBA Specification for a complete description. orb_ref ev obj Pre-defined handle used specifically for Avaya IC's implementation of CORBA. The value is always VESP_ORB. An environment variable filled when an error is detected. Object to convert to a string. The string created Issue 1.0 June 2002 149

Chapter 8 Avaya IC Toolkit Functions Example /******************************************************************* *print Servers uuid and Toolkit version ********************************************************************/ temp = ORB_object_to_string( VESP_ORB, &local_ev, object ); vesp_log_info( VESP_CAT_ALL, Vesp_Login Print login object, ); log_unparsable( Login object=%s, temp ); vesp_free(temp ); ORB_print_ev Syntax void ORB_print_ev( ORB orb_ref, Environment *ev ); Prints contents of ev to the logfile. orb_ref ev Pre-defined handle used specifically for Avaya IC's implementation of CORBA. The value is always VESP_ORB. An environment variable to print to the logfile. None ORB_set_session_lifetime Syntax ORBStatus ORB_set_session_lifetime( ORB orb_ref, Environment *ev, ULONG *lifetime ); Set the lifetime for all idle temporary sessions. All sessions that are established when a server receives a request from a client that is not assigned to it are temporary. If they remain idle for more than a certain lifetime they will be deleted. That lifetime is set when the session is created and reset each time the session is used. The breakdown (and possible recreation) of idle sessions is handled transparently by the toolkit, but it can impact performance. This routine is used to change the idle lifetime that will be assigned to all temporary sessions. orb_ref ev lifetime Pre-defined handle used specifically for Avaya IC's implementation of CORBA. The value is always VESP_ORB. An environment variable filled when an error is detected. The lifetime (in seconds) assigned to all temporary sessions. 150 Core Services Programmer s Guide

ORB_string_copy_to_object VESP_BAD_PARAMETER Bad parameter passed to function Example Refer to ORB_get_session_lifetime for an example of ORB_set_session_lifetime being used. ORB_string_copy_to_object Syntax ORBStatus ORB_string_copy_to_object ( ORB orb_ref, Environment *ev, char *str Object obj); Convert a UUID string to the Object structure it represents. This routine does NOT allocate space for the Object structure. orb_ref ev str obj Pre-defined handle used specifically for Avaya IC's implementation of CORBA. The value is always VESP_ORB. An environment variable filled when an error is detected. String to convert to an Object. The destination for the converted Object data. VESP_BAD_PARAMETER Bad parameter passed to function ORB_string_to_object Syntax Object ORB_string_to_object( ORB orb_ref, Environment *ev, char *str ); Allocate the space for a new object and convert the string representation of an Object into it. The Object must be freed with Object_release. Refer to the OMG CORBA Specification for a complete description. orb_ref ev str Pre-defined handle used specifically for Avaya IC's implementation of CORBA. The value is always VESP_ORB. An environment variable filled when an error is detected. String to convert to an Object. Issue 1.0 June 2002 151

Chapter 8 Avaya IC Toolkit Functions New object -or- NULL is bad parameter. Exceptions VESP_BAD_PARAMETER Bad parameter passed to function Example Object boa_object = NULL; /* * 1st arg in this object s UUID(object_gbl is declared in orb.h) * 2nd arg is BOA object s UUID */ if(argc >=2){ object_gbl=orb_string_to_object(vesp_orb, &local_env, argv[1]); if(argc >=3) object_gbl=orb_string_to_object(vesp_orb, &local_env, argv[2]); } /*if*/ else return VESP_ERROR; Request_defer Syntax ORBStatus Request_defer( Request request, Environment *ev ); Used in a server to defer the response to the client until further processing has been done. Use Request_send_deferred_response to send response back to client at a later time. request ev A handle of type Object which uniquely identifies the request. Created with ORB_create_request or Session_create_request. An environment variable filled when an error is detected. VESP_BAD_PARAMETER Bad parameter passed to function 152 Core Services Programmer s Guide

Request_delete Example ORBStatus TEST_Assign( Object obj, Environment *ev ) { Environment local_ev; Event *event; Request deferred request; PRINT(LOGFILE, Assign Method\n ) event = vesp_event_create( TEST.Vafoo ); vesp_event_add_couple( event, arg1, value1 ); Vesp_Send_Alarm( obj, TEST.TESTAlarm, low, blabla description ); SCHECK( Session_send_event( ev->session, &local_ev, TEST.Vafoo, event )); vesp_event_delete( event ); } /*we have to copy the request so we know that it is a good object and does not get deleted by some act of fate*/ deferred request = Object_duplicate( ev->request, &local_ev ); SCHECK( Vesp_Request( ORBServer.Ping, ping_routine_callback, (ULONG)deferred_request, ev->session )); /*defer response until we ping the Orb Server*/ EVCHECK( Request_defer(ev->request, ev) ); return( ); Request_delete Syntax ORBStatus Request_delete( Request request, Environment *ev ); Delete a Request and all its related resources. Refer to the OMG CORBA Specification for a complete description. request ev A handle of type Object which uniquely identifies the request. Created with ORB_create_request or Session_create_request. An environment variable filled when an error is detected. VESP_BAD_PARAMETER Bad parameter passed to function Request_get_ev Syntax ORBStatus Request_get_ev( Request request, Environment *ev, Environment **msg_ev ); Get a request s environment. Used mostly for setting an exception in a request that has been deferred. Refer to the OMG CORBA Specification for a complete description. Issue 1.0 June 2002 153

Chapter 8 Avaya IC Toolkit Functions request ev msg_ev A handle of type Object which uniquely identifies the request. Created with ORB_create_request or Session_create_request. An environment variable filled when an error is detected. Request's environment VESP_BAD_PARAMETER ev or msg_ev was invalid or (NULL) Example if( Request_get_ev((Request)user_data, &local_ev, &msg_ev) = ) { vesp_set_exception( msg_ev, ev->_minor,ev->vesp_error_description ); } Request_get_group Syntax ORBStatus Request_get_group( Request request, Environment *ev, char *buf ); Given a request object, this returns into buf the string representing the client's group. request ev buf A handle of type Object which uniquely identifies the request. Created with ORB_create_request or Session_create_request. An environment variable filled when an error is detected. A buffer to contain the client's group. VESP_BAD_PARAMETER VESP_NOT_FOUND Request or buf was invalid or NULL The request specified was not found 154 Core Services Programmer s Guide

Request_get_response Request_get_response Syntax ORBStatus Request_get_response( Request request, Environment *ev, unsigned long flags ); Wait for a specific request to be processed. ev contains message status. Refer to the OMG CORBA Specification for a complete description. Used internally by Avaya IC. request ev flags A handle of type Object which uniquely identifies the request. Created with ORB_create_request or Session_create_request. An environment variable filled when an error is detected. RESP_WAIT or RESP_NO_WAIT, indicates whether Request_get_response() should wait until a response is received or simply check for a response and return. VESP_BAD_PARAMETER VESP_WOULD_BLOCK Bad parameter passed to function Request was unsuccessful; requested operation would block Request_send Syntax LONG Request_send( Request request, Environment *ev, unsigned long invoke_flags ); Send a request to the server specified in the Object_create_request. Refer to the OMG CORBA Specification for a complete description. Used internally by Avaya IC. request ev invoke_flags A handle of type Object which uniquely identifies the request. Created with ORB_create_request or Session_create_request. An environment variable filled when an error is detected. Request control information. Issue 1.0 June 2002 155

Chapter 8 Avaya IC Toolkit Functions VESP_MSG_NOT_FOUND VESP_BAD_PARAMETER Message does not exist Bad parameter passed to function Request_send_deferred_response Syntax ORBStatus Request_send_deferred_response( Request request, Environment *ev, any return_result ); Send a response to a previously deferred request indicated by the request parameter. This function is used in tandem with Request_defer to handle those cases when a method request cannot be processed immediately. When a previously deferred request can finally be processed, this function indicates to the toolkit that the response is ready. It is important to note that the Request_send_deferred_response call informs the toolkit of the return value for the original request, but it does not provide any information about any output parameters that the requested method may have. The toolkit maintains the output parameters that were passed by reference to the original method function, and it expects that these parameters are properly filled in. This means that the programmer has to maintain pointers to any output parameters until the deferred response is sent. request ev return_result A handle of type Object which uniquely identifies the request. Created with ORB_create_request or Session_create_request. An environment variable filled when an error is detected. The return result of the original request. This should match the data type of the responding method as declared in its IDL specification. (See the section that describes the IDL declarations.) VESP_BAD_PARAMETER VESP_MSG_NOT_FOUND ev was NULL or return_result was not the correct type Message does not exist Example The following code fragment is extracted from the sample server provided in the IC Client and Server Programmer's Design Guide.... 62 /* This is the declaration for a structure that will be used to hold the 63 information about the request, the session, and a pointer to the output 156 Core Services Programmer s Guide

Request_send_deferred_response 64 data associated with a deferred request in TEST_DeferRequest. 65 */ 66 struct saved_for_callback { 67 Request orequest; 68 Session osession; 69 void *pxuserdata; 70 };... 78 static ORBStatus 79 defer_request_callback (Identifier, ORBStatus, Environment *, long, 80 Session, SeqCouple *);... 685 /*********************************************************************/ 686 /* This method demonstrates deferring the response to a client while the 687 server asynchronously makes a request to another server. 688 The client invoking this request expects output data. We will be making an 689 Alarm.GetStatus request and passing a copy of the returned sequence of 690 couples back to the client. 691 This method returns void instead of ORBStatus. For an example that returns 692 ORBStatus, see TEST_Assign. 693 */ 694 /*********************************************************************/ 695 /*ARGSUSED */ 696 void 697 TEST_DeferRequest (Object tobj, Environment * ptenv, SeqCouple * ptoutputdata) 698 { 699 Environment tmyenv; 700 ORBStatus mmystatus; 701 struct saved_for_callback *ptsaveinfo; 702 /* This has to be static for the callback to work. It will only be 703 filled in and meaningful in the callback to this function, so it 704 doesn't matter that it will be overwritten by subsequent function 705 calls. */ 706 static SeqCouple tseqcouple; 707 /* Initialize the structure to NULL - the information in this struct 708 will be sent to the server that you are making a request of, so 709 you're better off knowing what you are sending */ Issue 1.0 June 2002 157

Chapter 8 Avaya IC Toolkit Functions 710 tseqcouple._length = 0; 711 tseqcouple._maximum = 0; 712 tseqcouple._buffer = NULL; 713 /* Allocate space for saving the request, the session, and the output 714 data to be used by the callback function to send the deferred 715 response. */ 716 ptsaveinfo = vesp_calloc (1, sizeof (struct saved_for_callback)); 717 /* Save the request - we use it in the callback to retrieve the 718 client environment. */ 719 ptsaveinfo->orequest = Object_duplicate (ptenv->request, &tmyenv); 720 if (tmyenv._major!= NO_EXCEPTION) { 721 vesp_log_info (VESP_CAT_ALL, "Problem", "Object_duplicate"); 722 log_unparsable ("Error: %s", tmyenv.vesp_error_description); 723 vesp_set_exception (ptenv, tmyenv._major, tmyenv._minor, 724 tmyenv.vesp_error_description); 725 vesp_free (ptsaveinfo); 726 return; 727 } 728 /* Save the session - we use it in the callback to check that the 729 client still exists. */ 730 ptsaveinfo->osession = Object_duplicate (ptenv->session, &tmyenv); 731 if (tmyenv._major!= NO_EXCEPTION) { 732 vesp_log_info (VESP_CAT_ALL, "Problem", "Object_duplicate"); 733 log_unparsable ("Error: %s", tmyenv.vesp_error_description); 734 vesp_set_exception (ptenv, tmyenv._major, tmyenv._minor, 735 tmyenv.vesp_error_description); 736 Object_release (ptsaveinfo->orequest, &tmyenv); 737 if (tmyenv._major!= NO_EXCEPTION) { 738 vesp_log_info (VESP_CAT_ALL, "Problem", "Object_release"); 739 log_unparsable ("Error: %s", tmyenv.vesp_error_description); 740 } 741 vesp_free (ptsaveinfo); 742 return; 743 } 744 /* Save the output data pointer passed to the function with the 745 duplicated session and request objects. This will be used in the 746 callback. */ 747 ptsaveinfo->pxuserdata = (void *) ptoutputdata; 158 Core Services Programmer s Guide

Request_send_deferred_response 748 mmystatus = Vesp_Request ("Alarm.GetStatus", defer_request_callback, 749 (unsigned long) ptsaveinfo, omysession_gbl, 750 &tseqcouple); 751 if (mmystatus!= ) { 752 /* Return an error to the client immediately if there's a problem 753 with the request. */ 754 vesp_log_info (VESP_CAT_ALL, "Problem", "Vesp_Request"); 755 log_unparsable ("Status: %s", vesp_find_error (mmystatus)); 756 vesp_set_exception (ptenv, SYSTEM_EXCEPTION, VESP_FAILURE, 757 "defer_request method request failed"); 758 vesp_free (ptsaveinfo); 759 return; 760 } 761 /* Now defer the request - after this is successfully called, no 762 response will be sent to the client until we send one. Normally, a 763 response would be sent to the client when this function returns. */ 764 mmystatus = Request_defer (ptenv->request, &tmyenv); 765 if (tmyenv._major!= NO_EXCEPTION mmystatus!= ) { 766 /* We were unable to defer the request for some reason. */ 767 vesp_log_info (VESP_CAT_ALL, "Problem", "Request_defer"); 768 log_unparsable ("Error: %s, Status: %s", tmyenv.vesp_error_description, 769 vesp_find_error (mmystatus)); 770 /* Clean up of our duplicated objects will happen in the callback. We 771 could release them here if we wanted to, then in the callback we'd 772 have to check that the saved objects were non-null. 773 Since the Request_defer failed, the response will be sent to the 774 client when this function returns. However, the callback will still 775 be invoked when the request we made in this function returns a 776 response. 777 We'll end up with a situation where there will be no 778 outstanding request associated with our stored request object. We 779 use Request_get_ev to detect this situation when it retrieves the 780 original request environment. */ 781 vesp_set_exception (ptenv, tmyenv._major, tmyenv._minor, 782 tmyenv.vesp_error_description); 783 } 784 /* If we get to this point, we should be good to go - the session, the 785 request, and the output data pointer are saved, and the original Issue 1.0 June 2002 159

Chapter 8 Avaya IC Toolkit Functions 786 request has been deferred. */ 787 } 788 /*********************************************************************/ 789 /* Send the results of the deferred request to the client. In this case, 790 we pass along the result returned by the toolkit, but that's not 791 necessary - you can send the client any status you want to. 792 */ 793 /*********************************************************************/ 794 /*ARGSUSED */ 795 static ORBStatus 796 defer_request_callback (Identifier tinterface, ORBStatus mstatus, 797 Environment * ptenv, long luserdata, 798 Session osession, SeqCouple * ptoutputdata) 799 { 800 Environment tmyenv; 801 struct saved_for_callback *ptsavedinfo; 802 ORBStatus mmystatus; 803 int i; 804 any treturntoclient; 805 Environment *ptrequestenv; 806 SeqCouple *ptrequestdata; 807 /* Make the user data look like a pointer again. */ 808 ptsavedinfo = (struct saved_for_callback *) luserdata; 809 /* Get the client environment first - this is mostly to check that our 810 request is still valid. If you're working with a toolkit older than 811 3.5.9 you have to add the following line before making the 812 Request_get_ev function call. 813 tmyenv._major = NO_EXCEPTION; 814 This is because of a toolkit bug that was not properly initializing 815 the environment before doing its stuff. */ 816 mmystatus = Request_get_ev (ptsavedinfo->orequest, &tmyenv, 817 &ptrequestenv); 818 if (tmyenv._major!= NO_EXCEPTION mmystatus!= ) { 819 vesp_log_info (VESP_CAT_ALL, "Problem", "Request_get_ev"); 160 Core Services Programmer s Guide

Request_send_deferred_response 820 log_unparsable ("Error: %s, Status: %s", tmyenv.vesp_error_description, 821 vesp_find_error (mmystatus)); 822 Object_release (ptsavedinfo->orequest, &tmyenv); 823 if (tmyenv._major!= NO_EXCEPTION) { 824 vesp_log_info (VESP_CAT_ALL, "Problem", "Object_release"); 825 log_unparsable ("Error: %s", tmyenv.vesp_error_description); 826 } 827 Object_release (ptsavedinfo->osession, &tmyenv); 828 if (tmyenv._major!= NO_EXCEPTION) { 829 vesp_log_info (VESP_CAT_ALL, "Problem", "Object_release"); 830 log_unparsable ("Error: %s", tmyenv.vesp_error_description); 831 } 832 vesp_free (ptsavedinfo); 833 /* No request, can't send anything to client. Any return from inside 834 this function goes to the toolkit, not the client. */ 835 return ; 836 } 837 /* Check that the client session still exists before sending a response. 838 Bad things will happen if you try to send a response using a client 839 session that's already been cleaned up by the toolkit. */ 840 mmystatus = Session_exist (ptsavedinfo->osession, &tmyenv); 841 if (tmyenv._major!= NO_EXCEPTION mmystatus!= ) { 842 vesp_log_info (VESP_CAT_ALL, "Problem", "Session_exist"); 843 log_unparsable ("Error: %s, Status: %s", tmyenv.vesp_error_description, 844 vesp_find_error (mmystatus)); 845 Object_release (ptsavedinfo->orequest, &tmyenv); 846 if (tmyenv._major!= NO_EXCEPTION) { 847 vesp_log_info (VESP_CAT_ALL, "Problem", "Object_release"); 848 log_unparsable ("Error: %s", tmyenv.vesp_error_description); 849 } 850 Object_release (ptsavedinfo->osession, &tmyenv); 851 if (tmyenv._major!= NO_EXCEPTION) { 852 vesp_log_info (VESP_CAT_ALL, "Problem", "Object_release"); 853 log_unparsable ("Error: %s", tmyenv.vesp_error_description); 854 } 855 vesp_free (ptsavedinfo); 856 return ; 857 } 858 /* OK - so we have a valid environment and a valid client session let's 859 send the response. Here's where the result of the request comes into 860 play - if the environment has an exception set, we can't use any of Issue 1.0 June 2002 161

Chapter 8 Avaya IC Toolkit Functions 861 the output values, but our user data is unmodified. 862 Notice that we're sending a response to a method that returns 863 something other than ORBStatus, so the values that we're assigning to 864 treturntoclient._type and treturntoclient._value change accordingly. 865 */ 866 treturntoclient._type = "void"; 867 treturntoclient._value = NULL; 868 /* The important thing is that the toolkit checks the type you are trying 869 to return against the return type that is expected in the original 870 request, so they have to match. */ 871 if (NO_EXCEPTION == ptenv->_major) { 872 /* Fill in the output data using the pointer we saved from earlier. */ 873 ptrequestdata = (SeqCouple *) ptsavedinfo->pxuserdata; 874 for (i = 0; i < ptoutputdata->_length; i++) { 875 char *pcname = ptoutputdata->_buffer[i].name; 876 char *pcvalue = ptoutputdata->_buffer[i].value; 877 vesp_couple_seq_add_couple_values (ptrequestdata, pcname, pcvalue); 878 } 879 } else { 880 vesp_set_exception (ptrequestenv, ptenv->_major, ptenv->_minor, 881 ptenv->vesp_error_description); 882 } 883 mmystatus = Request_send_deferred_response (ptsavedinfo->orequest, 884 &tmyenv, 885 &treturntoclient); 886 /* There's not much we can do if this fails. */ 887 if (tmyenv._major!= NO_EXCEPTION mmystatus!= ) { 888 vesp_log_info (VESP_CAT_ALL, "Problem", 889 "Request_send_deferred_response"); 890 log_unparsable ("Error: %s, Status: %s", tmyenv.vesp_error_description, 891 vesp_find_error (mmystatus)); 892 } 893 /* We're done with these now. */ 894 Object_release (ptsavedinfo->orequest, &tmyenv); 162 Core Services Programmer s Guide

Server_set_client_terminate_routine 895 if (tmyenv._major!= NO_EXCEPTION) { 896 vesp_log_info (VESP_CAT_ALL, "Problem", "Object_release"); 897 log_unparsable ("Error: %s", tmyenv.vesp_error_description); 898 } 899 Object_release (ptsavedinfo->osession, &tmyenv); 900 if (tmyenv._major!= NO_EXCEPTION) { 901 vesp_log_info (VESP_CAT_ALL, "Problem", "Object_release"); 902 log_unparsable ("Error: %s", tmyenv.vesp_error_description); 903 } 904 vesp_free (ptsavedinfo); 905 /* Thank you, drive through. */ 906 return ; 907 } Server_set_client_terminate_routine Syntax void Server_set_client_terminate_routine( routine ) ORBStatus (*routine) ( Object object ); Set the routine to be called when client fails. routine object Routine to be called. Object of client terminating. None Example Server_set_client_terminate_routine( Server_client_terminate ); ORBStatus Server_client_terminate( Object client_object ) { PRINT( LOGFILE, Server_client_terminate\n ); return( ); } Server_set_status_hook_routine Syntax void Server_set_status_hook_routine( routine ) void (*routine)( SeqCouple *seq) ; Set the routine to be called whenever the GetStatus method runs. Issue 1.0 June 2002 163

Chapter 8 Avaya IC Toolkit Functions routine seq Routine to be called. Sequence of couples to which your custom status information will be added. None Example Server_set_status_hook_routine(Server_hook_routine); /* this routine is called any time the method GetStatus is called, you can add your own info on top of the system info */ ORBStatus Server_hook_routine( SeqCouple *seq ) { vesp_couple_seq_add_couple_values( seq, TEST, my_status ); } Server_set_user_exception_routine Syntax void Server_set_user_exception_routine( routine ) ORBStatus (*routine)(); Set the routine to be called when the server fails. routine Routine to be called. None Example Server_set_user_exception_routine(Server_user_exception); /*server user exception routine*/ ORBStatus Server_user_exception() { PRINT(LOGFILE, Server CRASH\n ); } Server_set_user_exit_routine Syntax void Server_set_user_exit_routine( routine ) ORBStatus (*routine)( ) ; 164 Core Services Programmer s Guide

Server_set_user_init_routine Set the routine to be called when the server exits. The routine specified is called when the server exits normally, i.e., when the server's Generic.Exit method is invoked. This routine is not used with atexit() and it will not execute if exit() is invoked directly from inside the server. routine Routine to be called. None Example Server_set_user_exit_routine(Server_user_exit); /*server user exit routine*/ ORBStatus Server_user_exit() { PRINT(LOGFILE, Server Exit\n ); } Server_set_user_init_routine Syntax void Server_set_user_init_routine( routine ) ORBStatus (*routine)( Object object ); Set the routine to be called upon server initialization. routine object Routine to be called. Object of server. None Example /*initialize handler routines*/ Server_set_user_init_routine( Server_user_init ); /*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*) Assign, 0x0, 0x0, (ULONG)TEST_Assign) ); SCHECK( BOA_set_method(VESP_BOA, &ev, object, (char*) Deassign, 0x0, 0x0, (ULONG)TEST_Deassign) ); SCHECK( BOA_set_method(VESP_BOA, &ev, object, (char*) Echo, 0x0, 0x0, (ULONG)TEST_Echo) ); Issue 1.0 June 2002 165

Chapter 8 Avaya IC Toolkit Functions } SCHECK( BOA_set_method(VESP_BOA, &ev, object, (char*) Echo2, 0x0, 0x0, (ULONG)TEST_Echo2) ); SCHECK( BOA_set_method(VESP_BOA, &ev, object, (char*) Echo3, 0x0, 0x0, (ULONG)TEST_Echo3) ); SCHECK( BOA_set_method(VESP_BOA, &ev, object, (char*) Echo4, 0x0, 0x0, (ULONG)TEST_Echo4) ); SCHECK( BOA_set_method(VESP_BOA, &ev, object, (char*) Echo5, 0x0, 0x0, (ULONG)TEST_Echo5) ); SCHECK( BOA_set_method(VESP_BOA, &ev, object, (char*) Exception, 0x0, 0x0, (ULONG)TEST_Exception) ); SCHECK( BOA_set_method(VESP_BOA, &ev, object, (char*) SetRejectFlag, 0x0, 0x0, (ULONG)TEST_SetRejectFlag) ); /*Set server version*/ vesp_set_server_version( TEST Server 1.1.0 ); return( ); Server_set_user_poll_routine Syntax void Server_set_user_poll_routine( routine ) ORBStatus (*routine)() ; Set the routine to be called when the server does polling. routine Routine to be called. None Example /* initialize handler routines */ Server_set_user_poll_routine( Server_user_poll ); /* user poll loop */ ORBStatus Server_user_poll() { return( ); } Session_change_group Syntax ORBStatus Session_change_group( Session session, Environment *ev, char *new_group); Change the group of the session. This will only be set if the user has group security permission. 166 Core Services Programmer s Guide

Session_create_request session ev new_group A handle of type Object that uniquely identifies the session. Created with Vesp_session_create. An environment variable filled when an error is detected. New group for session. VESP_BAD_PARAMETER Bad parameter passed to function Session_create_request Syntax ORBStatus Session_create_request( Session session, Environment *ev, Object object, Context ctx, Identifier operation, NVList arg_list, ORBStatus (* user_routine)(), unsigned long user_data, NamedValue *result, Request *request, unsigned long time_out, Flags req_flags ); Create a request related to a session. Used internally by Avaya IC. session ev object ctx operation arg_list user_routine user_data result request time_out req_flags A handle of type Object that uniquely identifies the session. Created with Vesp_session_create. An environment variable filled when an error is detected. Object to which the request is to be sent. Context to be sent to Object. Operation to be performed by the Object. Argument list. Routine to call when request is called. A longword that is echoed back. Address of where to put the return result from the object. Handle of type Object that identifies the created request. How long the request lives before time-out. Request control information. Issue 1.0 June 2002 167

Chapter 8 Avaya IC Toolkit Functions VESP_BAD_SESSION Session is invalid Session_delete Syntax ORBStatus Session_delete( Session session, Environment *ev ); Delete a Session and all its related resources. Used internally by Avaya IC. session ev A handle of type Object that uniquely identifies the session. Created with Vesp_session_create. An environment variable filled when an error is detected. VESP_BAD_SESSION Session is invalid Session_delete_request Syntax ORBStatus Session_delete_request( Session session, Environment *ev, Request request); Delete a request. This function deletes a request created with the function Session_create_request. This function is used only to get rid of a message that you created but don't want any more. Used internally by Avaya IC. session ev request A handle of type Object that uniquely identifies the session. Created with Vesp_session_create. An environment variable filled when an error is detected. Request to delete. VESP_BAD_SESSION VESP_MSG_NOT_FOUND Session is invalid Request does not exist 168 Core Services Programmer s Guide

Session_exist Session_exist Syntax ORBStatus Session_exist( Session session, Environment *ev ); Check if session is valid. session ev A handle of type Object that uniquely identifies the session. Created with Vesp_session_create. An environment variable filled when an error is detected. VESP_BAD_SESSION Session is invalid Session_get_context Syntax ORBStatus Session_get_context( Session session, Environment *ev, Context *ctx ); Get the context associated with this session. This is NOT a copy of the context information. session ev ctx A handle of type Object that uniquely identifies the session. Created with Vesp_session_create. An environment variable filled when an error is detected. Session context variable. VESP_BAD_PARAMETER Bad parameter passed to function Session_get_message_timeout Syntax ORBStatus Session_get_message_timeout( Session session, Environment *ev, unsigned long *time_out ); Get the current default message timeout. Issue 1.0 June 2002 169

Chapter 8 Avaya IC Toolkit Functions session ev time_out A handle of type Object that uniquely identifies the session. Created with Vesp_session_create. An environment variable filled when an error is detected. Current message time-out value. VESP_BAD_PARAMETER Bad parameter passed to function Session_print Syntax ORBStatus Session_print( Session session, Environment *ev ); Print all current Session information of a session. session ev A handle of type Object that uniquely identifies the session. Created with Vesp_session_create. An environment variable that is cleared (set to NO_EXCEPTION) if Session_print returns successfully. VESP_BAD_SESSION Session is invalid Session_send Syntax ORBStatus Session_send( Request request, Environment *ev, Flags invoke_flags ); Send a request to the server specified in the Session_create_request. request ev invoke_flags A handle of type Object that uniquely identifies the session. Created with Vesp_session_create. An environment variable filled when an error is detected. Request control information. 170 Core Services Programmer s Guide

Session_send_event VESP_MSG_NOT_FOUND Message does not exist Session_send_event Syntax ORBStatus Session_send_event( Session session, Environment *ev, char *operation, Event *event ); Send an event from a server to a client. session ev operation event A handle of type Object that uniquely identifies the session. Created with Vesp_session_create. An environment variable filled when an error is detected. Name of event operation. Event to send to session. VESP_MSG_NOT_FOUND Message does not exist Example event=vesp_event_create( TEST.Vafoo ); vesp_event_add_couple( event, arg1, value1 ); Vesp_Send_Alarm( obj, TEST.TESTAlarm, low, blabla description ); SCHECK( Session_send_events(ev->session, &local_ev, TEST.Vafoo, event) ); vesp_event_delete( event ); Session_set_context Syntax ORBStatus Session_set_context( Request request, Environment *ev, Context ctx ); Set the context associated with this session. session ev ctx A handle of type Object that uniquely identifies the session. Created with Vesp_session_create. An environment variable filled when an error is detected. Session context variable. Issue 1.0 June 2002 171

Chapter 8 Avaya IC Toolkit Functions VESP_BAD_PARAMETER Bad parameter passed to function Session_set_message_timeout Syntax ORBStatus Session_set_message_timeout( Session session, Environment *ev, unsigned long time_out); Set a new default message time-out. If a request takes longer than this value the request returns automatically. All requests sent by this session carry the new time-out value. session ev time_out A handle of type Object that uniquely identifies the session. Created with Vesp_session_create. An environment variable filled when an error is detected. New message time-out value, in seconds. VESP_BAD_PARAMETER Bad parameter passed to function Example /* set message time out to 20 seconds */ Session_set_message_timeout( ev->session, ev, 20UL ); Vesp_Request_Sync( VDU.TerminateMine, &ev, ev->session, &request ); Vesp_Assign_Request Syntax ORBStatus Vesp_Assign_Request( interface, ev, callback, user_data, event_callback, session, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9, arg10, arg11, arg12 ); Identifier Environment ULONG long interface; *ev; (*callback)(); user_data; 172 Core Services Programmer s Guide

Vesp_Assign_Request ULONG Session void (*event_callback)(); session; *arg1... arg12; Call Back Syntax ORBStatus callback( interface, return_result, ev, user_data, session, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9, arg10, arg11, arg12); Identifier ORBStatus Environment long Session void interface; return_result; *ev; user_data; session; *arg1... arg12; Event Syntax ORBStatus event_callback( interface, object, session, event ); Identifier Object Session Event interface; object; session; *event; The Assign function relates a server to a session. Henceforth, any request to this interface goes to the server selected with the assign. This allows for longer term relationships between clients and servers. The Assign also allows a server to send events to a client application until a Deassign request occurs. If the assigned server fails, a ServerFailed event is generated. If the callback is NULL, this is a synchronous request. You must specify an event callback routine. If the event callback is NULL, VESP_BAD_PARAMETER is returned. The data presented in a callback is only good while in the callback. If you want to save the information, you must save the information while in the callback. Issue 1.0 June 2002 173

Chapter 8 Avaya IC Toolkit Functions interface return_result ev event callback user_data event_callback session object arg1 Interface and method to resolve request to. interface is in the form interface.method or?.method when the hybrid interface has to match for the method. If an event, a suffix of.event is added to the interface name. Status code returned by the method that was called. An environment variable filled when an error is detected. The information about the event. Routine to call when a response for the request is received or a time-out has occurred. User longword passed to the callback. Routine to call if events are received from the assigned server. Session to associate the assign with, or session the event is sent to. Object (Server) where the event came from. Arguments as described in the IDL specification. VESP_BAD_PARAMETER VESP_TIMEOUT Bad parameter passed to function Request took too long Example SCHECK( Vesp_Login( Brian, funfun, &client_obj) ); SCHECK( Vesp_Session_Create(client_obj, &session) ); SCHECK( Vesp_Assign_Request( TEST.Assign, &ev, NULL, OUL, event_callback, session, NULL) ); /* do stuff here */ SCHECK( Vesp_Deassign_Request( TEST.Deassign, &ev, NULL, OUL, session) ); SCHECK( Vesp_Session_Delete(session) ); SCHECK( Vesp_Logout(client_obj) ); Vesp_Broadcast_Event Syntax ORBStatus Vesp_Broadcast_Event( Object vobject, Environment *ev, Identifier operation, _ IDL_SEQUENCE_Couple *event_info ); This function allows a server to broadcast an event to all of its assigned clients. 174 Core Services Programmer s Guide

Vesp_Change_Password vobject ev operation event_info Object of the server sending the event. An environment variable filled when an error is detected. Name of event operation. The event data to be broadcast. VESP_BAD_PARAMETER Bad parameter passed to function Vesp_Change_Password Syntax ORBStatus Vesp_Change_Password( Session session, char *loginid, char *oldpass, char *newpass ); Change a password for a loginid. session loginid oldpass newpass Session doing the request. Login of password to change. Old password. New password. VESP_BAD_PARAMETER Bad parameter passed to function Vesp_DDE_get_next_response Syntax ORBStatus Vesp_DDE_get_next_response( char **string_out, Session *session ); Get the next response or event from a server. This function works with Vesp_DDE_Request or Vesp_DDE_Request_Sync. Issue 1.0 June 2002 175

Chapter 8 Avaya IC Toolkit Functions string_out session The response or event in DDE format. This must be freed by the user using vesp_free. The session that this event or response belongs to. VESP_BAD_PARAMETER VESP_NO_MESSAGE Bad parameter passed to function No message Example /* String request */ status = Vesp_Request_DDE( [TEST.Echo2(\ lala,)], session); while(vesp_dde_get_next_response(&string_out, &session) = ) { PRINT(LOGFILE, dde POLL%s, string_out); vesp_free( string_out ); } Vesp_Deassign_Request Syntax Call Back Syntax ORBStatus Vesp_Deassign_Request( Identifier interface, Environment *ev, ULONG (*callback)(), long user_data, Session session ); ORBStatus callback( Identifier interface, ORBStatus return_result, Environment *ev, long user_data, Session session, void *arg1 ); Parameter Break down an Assign that was previously declared with a server specified in interface. The session no longer receives events from this server. Future requests to the interface go through the normal selection process instead of defaulting. If the callback is NULL, this is a synchronous call. interface ev callback Interface and method to resolve request to. An environment variable filled when an error is detected. Routine to call when a response for the request is received or a timeout has occurred. 176 Core Services Programmer s Guide

Vesp_Force_Password user_data session return_result User longword passed to the callback. Session to associate the assign with or session the event is sent to. The return code of the Deassign method. VESP_BAD_PARAMETER VESP_TIMEOUT Bad parameter passed to function Request took too long Example SCHECK( Vesp_Login( Brian, passwd, &client_obj) ); SCHECK(Vesp_Session_Create(client_obj, &session) ); SCHECK(Vesp_Assign_Request( TEST.Assign, &ev, NULL, OUL, event_callback, session, NULL) ); /* do stuff here */ SCHECK( Vesp_Deassign_Request( TEST.Deassign, &ev, NULL, OUL, session ); SCHECK( Vesp_Session_Delete(session) ); SCHECK( Vesp_logout(client_obj) ); Vesp_Force_Password Syntax ORBStatus Vesp_Force_Password( Session session, char *loginid, char *password ); Force a loginid to change its password. This works only if the session has the system security level. session loginid password Session doing the request. Login of password to change. New password. VESP_BAD_PARAMETER Bad parameter passed to function Vesp_get_default_session Syntax ORBStatus Vesp_get_default_session( Object object, Session *session ); Get the default session created with the Vesp_Login or, if a server, created when the server starts. Issue 1.0 June 2002 177

Chapter 8 Avaya IC Toolkit Functions object session Object created by Vesp_Login or passed to usr_server_init. The default session created when Vesp_Login was called. Example /* * Get default session, and config from that. * Print out the Servers or clients configuration information */ */ SCHECK( Vesp_get_default_session(object, &sess) ); SCHECK( Session_get_context(sess, &loc_ev, &ctx) ); Context_get_configuration( ctx, &_loc_ev, &configseq ); if (configseq!=null) { for (i = 0; i < configseq->_length; ++i) { PRINT( LOGFILE, name-%s, value=%s\n, configseq->_buffer[i].name, configseq->_buffer[i].value ); } } Vesp_Load_Implementation Syntax ORBStatus Vesp_Load_Implementation ( Object object, char *service, char *filename ); Reload Implementation repositories. This function is used when some system configuration has changed. A new implementation file is created and its information is loaded into memory. object service filename Object returned from login. Service from which imp is loaded. Local file for new repository. Example Vesp_Load_Implementation( object, DS, vesp.imp ) 178 Core Services Programmer s Guide

Vesp_Load _Interface Vesp_Load _Interface Syntax ORBStatus Vesp_Load_Interface( Object object, char *service, char *filename ); Reload interface repository. Used when some system configuration has changed. object service filename Object returned from login. Service where file will be loaded from. Local file where new repository is put. Example Vesp_Load_Interface( object, "DS", "vespidl.pk" ) Vesp_Login Syntax ORBStatus Vesp_Login( char *name, char *password, Object *object ); Log a client in the Avaya IC ORB environment. name password object User name as defined in the Directory Server. The login can be a maximum of 31 characters. User Password. The password can be a maximum of 16 characters. Object returned by the ORB Server that uniquely defines this client or server. This is used to create sessions and identify the object for alarms. VESP_INIT_FAILURE VESP_BAD_PARAMETER VESP_TIMEOUT No more sockets Bad parameter passed to function Request took too long Issue 1.0 June 2002 179

Chapter 8 Avaya IC Toolkit Functions VESP_BAD_PASSWORD VESP_MULTI_LOGIN_ID VESP_BAD_LOGIN_ID The password used does not match the one in the directory The loginid was found more than once in the directory Bad login id Example SCHECK( Vesp_Login( Brian, funfun, &client_obj) ) SCHECK( Vesp_Session_Create(client_obj, &session) ); SCHECK( Vesp_Assign_Request( TEST.Assign, &ev, NULL, OUL, event_callback, session) ); /* do stuff here */ SCHECK( Vesp_Deassign_Request( TEST.Deassign, &ev, NULL, OUL, session) ); SCHECK( Vesp_Session_Delete(session) ); SCHECK( Vesp_Logout(client_obj) ); Vesp_Logout Syntax ORBStatus Vesp_Logout( Object object ); Break down the instance of an object created with Vesp_Login. object Object returned by the ORB Server that uniquely defines this client or server. This is used to create sessions and identify the object for alarms. VESP_BAD_PARAMETER VESP_BAD_SESSION VESP_TIMEOUT Bad parameter passed to function Session is invalid Request took too long Example SCHECK( Vesp_Login( Brian, funfun, &client_obj) ) SCHECK( Vesp_Session_Create(client_obj, &session) ); SCHECK( Vesp_Assign_Request( TEST.Assign, &ev, NULL, OUL, event_callback, session) ); /* do stuff here */ SCHECK( Vesp_Deassign_Request( TEST.Deassign, &ev, NULL, OUL, session) ); SCHECK( Vesp_Session_Delete(session) ); SCHECK( Vesp_Logout(client_obj) ); Vesp_poll Syntax ORBStatus Vesp_poll( unsigned long time ); 180 Core Services Programmer s Guide

Vesp_Reload_Imp This routine packages and sends messages between servers. It must be called about five times a second to ensure proper operation of a client application. time How long to wait for a message in tens of milliseconds. For example, 20UL is five times per second. VESP_WOULD_BLOCK Request was unsuccessful; the function would block Example for ( ;; ) { } Vesp_poll( 20UL ); Vesp_Reload_Imp Syntax ORBStatus Vesp_Reload_Imp( Object object ); Reload Implementation repositories. Used when some system configuration has changed. object Object returned from login. Vesp_Reload_Imp_Local Syntax ORBStatus Vesp_Reload_Imp_Local( char *file_name ); Reloads a local copy of the implementation file. This replaces all previously loaded implementation information. file_name The name of the file to contain the new copy. The file is assumed to be in the current directory. Issue 1.0 June 2002 181

Chapter 8 Avaya IC Toolkit Functions VESP_BAD_PARAMETER VESP_IMP_NOT_FOUND VESP_FILE_DOES_NOT_EXIST VESP_FAILURE Bad parameter passed to function vesp.imp is not in the current directory Indicated file is not in the current directory Too many attributes Vesp_Request Syntax ORBStatus Vesp_Request( interface, callback, user_data, session, arg1, agr2, agr3, arg4, arg5, arg6, arg7, arg8, arg9, arg10, arg11, arg12 ) Identifier ULONG long Session void interface; (*callback)(); user_data; session; *arg1...; Call Back SyntaxO RBStatus callback( interface, return_result, ev, user_data, session, arg1... ); Identifier ORBStatus Environment long Session interface; return_result; *ev; user_data; session; void *arg1...; Send a method request to a server Object asynchronously. The function returns after the method request is sent, it does not wait for a reply. Vesp_Request converts the method request to an ORB Dynamic Binding method request and passes the converted request to an object of the appropriate type. If no such object is running, one will be started if possible. (Exceptions: see Generic.Exit and Generic.Ping) 182 Core Services Programmer s Guide

Vesp_Request The first four parameters are fixed and are explained below. After the first four parameters, additional parameters corresponding to the parameters of the method as declared in its IDL specification are passed. None of these additional parameters should be set to NULL. Any output parameters should be passed as pointers to valid memory locations of the appropriate size to hold the output type. The pointers passed in will be the memory locations where the toolkit puts the results when the callback function is invoked. If an output parameter is a sequence, the _length should always be 0 and the _buffer should always be NULL. The _maximum may be set to some positive number to indicate to the method that no more than that many should be returned. It is recommended that all other output parameters be set to zeros. Output parameters are filled in (and any additional memory needed for sub-structures, such as the _buffer portion of a sequence, is allocated) immediately before the callback function is invoked, and cleared (including release of the memory allocated by the toolkit) immediately after the callback returns. The callback field specifies the callback function to be invoked when the method has completed. The callback function's sixth and later parameters must correspond to the fifth and later parameters of the Vesp_Request call (i.e., those parameters defined in the method s IDL specification). Any value passed into the user_data field when the request is made is passed on to the callback function unaltered. If no callback function is specified, the method response will be discarded (quietly cleaned up by the toolkit). interface return_result ev callback user_data session arg1 Name of method and interface to invoke. Of format Interface.Method. Status code returned by the method that was called. An environment variable filled when an error is detected. Routine to call when response is returned. When invoking methods of type Oneway, the callback will be null, thus the response will be discarded. Value passed to call back routine. Session created with Vesp_Session_Create or the default session. Arguments as described in the IDL specification for the method being invoked. VESP_BAD_PARAMETER VESP_BAD_SESSION Bad parameter passed to function Session is invalid Example SCHECK( Vesp_Request( TEST.Echo2, echo_routine2, 1233UL, session, abcd, &output2) ); Issue 1.0 June 2002 183

Chapter 8 Avaya IC Toolkit Functions Vesp_Request_DDE Syntax ORBStatus Vesp_Request_DDE( char *param_string_in, Session session ); Send a DDE style request to an object. param_string_in session DDE style string of operation and parameters to perform. Session created with Vesp_Session_Create or the default session. VESP_BAD_PARAMETER VESP_BAD_SESSION Bad parameter passed to function Session is invalid Example SCHECK( Vesp_Request_DDE( [TEST.Echo3({0,1,{ fie\,\ fum\ }},{0,0,}), session) ); while ( Vesp_DDE_get_next_response(&string_out, &session) == ) { } PRINT( LOGFILE, dde POLL %s, string_out ); vesp_free( string_out ); Vesp_Request_DDE_Sync Syntax char * Vesp_Request_DDE_Sync( char *param_string_in, Session session ); Send a DDE style request to an object synchronously. param_string_in session DDE style string of operation and parameters to perform. This operation is performed synchronously. Session created with Vesp_Session_Create or the default session. The DDE style string that was returned by the server. A NULL is returned for an error or a one way request. This parameter must be freed when it is no longer in use. Example string_out = Vesp_Request_DDE_Sync( [TEST.Deassign()], session, ); PRINT( LOGFILE, dde call %s, string_out ); vesp_free( string_out ); 184 Core Services Programmer s Guide

Vesp_Request_Delete Vesp_Request_Delete Syntax ORBStatus Vesp_Request_Delete( Session session, Request request ); Delete a request created with Vesp_Request_Sync. session request Session to which this request belongs, created with Vesp_Session_Create or the default session. Request to delete. Example SCHECK( Vesp_Request_Sync( TEST.Echo, &ev, session, &request, 0x232UL, &output) ); PRINT( LOGFILE, Sync output arg2=%1x, (ULONG)output ); SCHECK( Vesp_Request_Delete(session, request) ); Vesp_Request_Sync Syntax ORBStatus Vesp_Request_Sync( inter_opt, ev, session, request, arg1, agr2, agr3, arg4, arg5, arg6, arg7, arg8, arg9, arg10, arg11, arg12); Identifier Environment Session Request void inter_opt; *ev; session; *request; *arg1... arg12; Send a synchronous request to an Object. This routine allocates memory, including but not limited to any output parameters from the method being called. It is important that Vesp_Request_Delete() be called when you are done with that output, to free the allocated memory. Forgetting to do this is a common source of memory leaks. This function clears the environment structure.you have to create a new environment variable. Issue 1.0 June 2002 185

Chapter 8 Avaya IC Toolkit Functions inter_opt ev session request arg1 Name of interface method. Environment. Session created with Vesp_ Session_Create or the default session. Request handle created if request is good. Arguments as described in the IDL specification. VESP_BAD_PARAMETER VESP_BAD_SESSION Bad parameter passed to function Session is invalid Example SCHECK( Vesp_Request_Sync( TEST.Echo, &ev, session, &request, 0x232UL, &output) ); PRINT( LOGFILE, Sync output arg2=%1x, (ULONG) output ); SCHECK( Vesp_Request_Delete( session, request) ); Vesp_Send_Alarm Syntax ORBStatus Vesp_Send_Alarm( Object object, Identifier name, char *priority, char *description ); Send an alarm to the Alarm Server. object name priority description Server sending the alarm. This is created with the Vesp_Login function or, if a server, passed as the first parameter into the method. Name of alarm. Priority of the alarm as defined by the Alarm Server, high, low, info, or Emergency. of alarm. Example Vesp_Send_Alarm( client_obj, AlarmName, high, This is a Test Event ); 186 Core Services Programmer s Guide

Vesp_Send_Alarm_No_History Vesp_Send_Alarm_No_History Syntax ORBStatus Vesp_Send_Alarm_No_History ( Object object, Identifier name, char *priority, char *description ); Send an alarm to the Alarm Server without logging the alarm to the History Server, if one is being used. object name priority description Server sending the alarm. This is created with the Vesp_Login function or, if a server, passed as the first parameter into the method. Name of alarm. Priority of the alarm as defined by the Alarm Server. of alarm. Example Vesp_Send_Alarm_No_History( client_obj, AlarmName, high, This is a Test Event ); Vesp_Server_Login Syntax ORBStatus Vesp_ Server _Login( Object object, Object boa_object ); Log a server in the Avaya IC ORB environment. When the ORB Server starts a server, the object and boa_object are passed as strings into the server. object boa_object Object that uniquely defines this server. Object that defines the ORB Server related to this server. VESP_BAD_PARAMETER VESP_INIT_FAILURE VESP_TIMEOUT Bad parameter passed to function No more sockets Request took too long Issue 1.0 June 2002 187

Chapter 8 Avaya IC Toolkit Functions Example /* 1st arg in this objects object */ /**************************************************************** * 1st arg in this objects uuid * 2nd arg is BOA object uuid *****************************************************************/ object = ORB_string_to_object( VESP_ORB, &local_ev, arg[1] ); if ( arg >= 3 ) { boa_object = ORB_string_to_object( VESP_ORB, &local_ev, arg[2] ); } /**************************************************************** * remap server if necessary * if it fails runs out of ports or could not bind * Login after Server inits so it can talk to itself at login * Specifically for the Directory Server * Object is not set here only used to create default session *****************************************************************/ /* if not successful server exits!! */ SCHECK( Vesp_Server_Login( object, boa_object ) ); /* loop here and process incoming requests */ while(1) { Vesp_poll( 20UL ); } Vesp_Session_Create Syntax ORBStatus Vesp_Session_Create( Object object, Session *session ); Create a session associated with the instance of an object created with Vesp_Login. Parameter object session Object to associate session with. Session created with Vesp_ Session_Create or the default session. Example SCHECK( Vesp_Session_Create( client_obj, &session ) ); SCHECK( Vesp_Assign_Request( TEST.Assign, &ev, NULL, OUL, event_callback, session, NULL )); Vesp_Session_Delete Syntax ORBStatus Vesp_Session_Delete( Session session ); Delete a session created with Vesp_ Session_Create. 188 Core Services Programmer s Guide

Vesp_Set_Client_Port session Session created with Vesp_ Session_Create. VESP_BAD_PARAMETER VESP_BAD_SESSION Bad parameter passed to function Session is invalid Example SCHECK( Vesp_Deassign_Request( TEST.Deassign,&ev, NULL, OUL, session )); SCHECK( Vesp_Session_Delete( session ) ); Vesp_Set_Client_Port Syntax void Vesp_Set_Client_Port( unsigned short port ); Set the port where the client starts to scan for a starting port. If this is not used, 7000 is the default start point. Avaya IC searches up 255 ports to find a good one. port Port to start search for free IP-type port. None Example /* 7000 is the default client port number */ Vesp_Set-Client_Port( 7000); Vesp_Timed_Function_Delete Syntax ORBStatus Vesp_Timed_Function_Delete( ULONG handle ); Deletes a timed function from the timed function list. handle The handle of the function to be deleted. Issue 1.0 June 2002 189

Chapter 8 Avaya IC Toolkit Functions Vesp_Timed_Function_Poll Syntax ORBStatus Vesp_Timed_Function_Poll ( void ); Search the timed function list for any functions that are due to be executed and execute them. To prevent severe delays, no more than five timed functions will be executed by a single call to this function, regardless of how many are ready. Vesp_Timed_function_poll is called by Vesp_poll. VESP_WOULD_BLOCK This function is being called from within another call to Vesp_Timed_Function_Poll, which is illegal. Vesp_Timed_Function_Print Syntax void Vesp_Timed_Function_Print( ULONG handle ); Put a formatted entry in the log file describing one or all timed functions. handle Handle to the function to be printed. A value of 1 causes all timed functions to be entered into the log. None Vesp_Timed_Function_Register Syntax ORBStatus Vesp_Timed_Function_Register( Timed_Function timed_func, time_t time_to_wait, ULONG flags, void *arg1, void *arg2, void *arg3, void *arg4, char *info, ULONG *handle ) ; 190 Core Services Programmer s Guide

Vesp_Timed_Function_Register Timed_Function Syntax typedef Vesp_Timed_Function_Register void (*timed_func) ( ULONG handle, time_t local_time, void *arg1, void *arg2, void *arg3, void *arg4 ) ; Register a function to be executed after a specified amount of time (in seconds). The function will be added to an internal timed function list and executed when Vesp_Timed_Function_Poll is called after the indicated time has passed. timed_func time_to_wait flags The function to be executed. The number of seconds to wait before executing the function. Flags controlling certain aspects of the timed function: VESP_TIMED_FUNCTION_NONE No special characteristics VESP_TIMED_FUNCTION_NOBLOCK Do not execute this function from within a sync method call VESP_TIMED_FUNCTION_NOVNET_GO Do not call if running vnet_go in Vesp_poll VESP_TIMED_FUNCTION_NOVESP_POLL Do not execute this function from within Vesp_Poll VESP_TIMED_FUNCTION_REARM After timed_func is called, re-register it to run again after the same time interval arg1 - arg4 info handle local_time Function specific arguments to be passed to timed_func when it is executed. A short (63 characters or less) information string to be logged when the function is executed. The handle for the timed function which is created. This handle is passed to the timed function when it is called. The current time when timed_function is called. Refer to the ANSI C function time () for details. VESP_BAD_PARAMETER Bad parameter passed to function Issue 1.0 June 2002 191

Chapter 8 Avaya IC Toolkit Functions Vesp_Timed_Function_Reset Syntax ORBStatus Vesp_Timed_Function_Reset( ULONG handle, time_t new_time ); Resets the execution time for a timed function. handle new_time Handle to the timed function. Minimum number of seconds from now until function is called. vesp_calloc Syntax void *vesp_calloc( unsigned long count, unsigned long size ); This allocates memory for use by other Avaya IC routines. It roughly emulates the standard C routine "calloc()". vesp_free() MUST be used to free memory allocated with this routine. Do not use free(). This also allows additional debugging information to be used to find problems with code using the heap. count size The number of objects for which space must be allocated. The size of (one of) those objects. Memory allocated vesp_close_log Syntax void vesp_close_log( void ); Close the log. Used after fork() and before exec() so the parent's log file is not used. None Example /* stop all sockets so orb server can restart if needed */ vnet_destroy(); PRINT( LOGFILE, ORB Server Starting child ); vesp_close_log(); 192 Core Services Programmer s Guide

vesp_couple_create if ( chdir( home_dir )!= 0 ) { PRINT( LOGFILE, Could not change to new home dir ); } if (( status = excel( value, value, uuid, object_str_gbl, NULL ) ) == -1 ) { PRINT( LOGFILE, ORB Server after Exec failed for child ); PRINT( LOGFILE, ORB Server child exec failed existing ); exit (20); } /* should never get here */ PRINT( LOGFILE, ORB Server after Exec for child ); vesp_couple_create Syntax Example Couple *vesp_couple_create( void); Allocates a Couple structure with name and value equal to NULL. vesp_couple_delete() MUST be used to free Couples allocated with this routine. Couple created Couple *foo; ORBStatus status; foo = vesp_couple_create status = vesp_couple_set_values( foo, foo_name, foo_value ); vesp_couple_delete( foo ); vesp_couple_delete Syntax ORBStatus vesp_couple_delete( Couple *couple ); Delete a couple created with vesp _couple_create(). This frees the name and value strings (if any) and the original structure. couple Couple to be deleted. VESP_BAD_PARAMETER A value passed in was NULL or invalid Example Couple *foo; ORBStatus status; foo = vesp_couple_create status = vesp_couple_set_values( foo, foo_name, foo_value ); vesp_couple_delete( foo ); Issue 1.0 June 2002 193

Chapter 8 Avaya IC Toolkit Functions vesp_couple_seq_add_couple Syntax ORBStatus vesp_couple_seq_add_couple( _IDL_SEQUENCE_Couple *seq, Couple *couple ); Add a couple that was created to a sequence of couples. If the maximum for this sequence is set (_maximum > 0) and it has been reached (_length >= _maximum), this routine does nothing. Otherwise, it allocates space for the new Couple, copies the data from *couple into the allocated space, and increments seq->_length. Calling vesp_couple_seq_delete() will free the Couples allocated in this manner. The original Couple will be unaffected. seq couple The sequence of couples to which new data is added. The data being added. VESP_BAD_PARAMETER A value passed in was NULL Example seq_couple_in = vesp_couple_seq_create(); couple_in = vesp_couple_create(); vesp_couple_set_values( couple_in, name, value ); /* add a bunch more to the echo5 method */ vesp_couple_seq_add_couple( seq_couple_in, couple_in ); vesp_couple_seq_add_couple_values Syntax ORBStatus vesp_couple_seq_add_couple_values ( _IDL_SEQUENCE_Couple *seq, char *name, char *value); Add a name value pair as a couple in a sequence of couples. If the maximum for this sequence is set (_maximum > 0) and it has been reached (_length >= _maximum), this routine does nothing. Otherwise, it allocates space for a new couple, copies the data from *name and *value into the name and value strings of the new couple, and increments seq->_length. Calling vesp_couple_seq_delete() will free the couples allocated in this manner. The original couple will be unaffected. 194 Core Services Programmer s Guide

vesp_couple_seq_create seq name value The sequence of couples to which new data is added. The name for the couple being added. The value of the couple being added. VESP_BAD_PARAMETER A value passed in was NULL Example aspect_info = vesp_couple_seq_create( ); vesp_couple_seq_add_couple_values( aspect_info, resp, resp ); vesp_couple_seq_add_couple_values( aspect_info, cct, 000 ); vesp_couple_seq_add_couple_values( aspect_info, data_a, data_a ); vesp_couple_seq_add_couple_values( aspect_info, data_b, data_b ); vesp_couple_seq_add_couple_values( aspect_info, data_c, data_c ); vesp_couple_seq_add_couple_values( aspect_info, data_d, data_e ); vesp_couple_seq_add_couple_values( aspect_info, data_e, data_e ); Vesp_Request( TS.ReceiveData, ts_receivedata_routine, (ULONG) scripter_data, scripter_data->session, aspect_info ); vsep_couple_seq_delete( aspect_info ); vesp_couple_seq_create Syntax _IDL_SEQUENCE_Couple *vesp_couple_seq_create( void ); Allocates an _IDL_SEQUENCE_Couple structure with _length and _maximum equal to 0 and _buffer equal to NULL. vesp_couple_seq_delete() MUST be used to free structures allocated with this routine. Empty sequence of couples Example aspect_info = vesp_couple_seq_create( ); vesp_couple_seq_add_couple_values( aspect_info, resp, resp ); vesp_couple_seq_add_couple_values( aspect_info, cct, 000 ); vesp_couple_seq_add_couple_values( aspect_info, data_a, data_a ); vesp_couple_seq_add_couple_values( aspect_info, data_b, data_b ); vesp_couple_seq_add_couple_values( aspect_info, data_c, data_c ); vesp_couple_seq_add_couple_values( aspect_info, data_d, data_e ); vesp_couple_seq_add_couple_values( aspect_info, data_e, data_e ); Vesp_Request( TS.ReceiveData, ts_receivedata_routine, (ULONG) scripter_data, scripter_data->session, aspect_info ); vsep_couple_seq_delete( aspect_info ); Issue 1.0 June 2002 195

Chapter 8 Avaya IC Toolkit Functions vesp_couple_seq_delete Syntax ORBStatus vesp_couple_seq_delete( _IDL_SEQUENCE_Couple *seq ); Delete a sequence of couples created with vesp_couple_seq_create. This frees the structure and any Couples it contains. seq Sequence of couples to delete. VESP_BAD_PARAMETER A value passed in was NULL Example aspect_info = vesp_couple_seq_create( ); vesp_couple_seq_add_couple_values( aspect_info, resp, resp ); vesp_couple_seq_add_couple_values( aspect_info, cct, 000 ); vesp_couple_seq_add_couple_values( aspect_info, data_a, data_a ); vesp_couple_seq_add_couple_values( aspect_info, data_b, data_b ); vesp_couple_seq_add_couple_values( aspect_info, data_c, data_c ); vesp_couple_seq_add_couple_values( aspect_info, data_d, data_e ); vesp_couple_seq_add_couple_values( aspect_info, data_e, data_e ); Vesp_Request( TS.ReceiveData, ts_receivedata_routine, (ULONG) scripter_data, scripter_data->session, aspect_info ); vsep_couple_seq_delete( aspect_info ); vesp_couple_seq_duplicate Syntax _IDL_SEQUENCE_Couple *vesp_couple_seq_duplicate( _IDL_SEQUENCE_Couple *in_seq ); Duplicate a sequence of couples. This routine creates a complete copy of the original sequence, which must be freed in the same manner as the original. in_seq Sequence of couples to be duplicated Example Sequence of couples duplicated or NULL if bad parameter. _IDL_SEQUENCE_Couple *seq1, *seq2; /* initialize the first sequence */ seql = vesp_couple_seq_create(); vesp_couple_seq_add_couple_values(seql, name1, value1 ); vesp_couple_seq_add_couple_values(seql, name2, value2 ); 196 Core Services Programmer s Guide

vesp_couple_seqseq_add_seq /* create a second identical sequence */ seq2 = vesp_couple_seq_duplicate(seq1); /* add additional data */ vesp_couple_seq_add_couple_values(seq2, name3, value3 ); /* At this point we have two separate sequences, each of which * contains a copy of the couples { name1, value1 } and { name2, * value2 }, but only the second sequence, seq2, contains the * couple { name3, value3 }. We now have five separate couples in * memory. */ vesp_couple_seqseq_add_seq Syntax ORBStatus vesp_couple_seqseq_add_seq( _IDL_SEQUENCE_sequence_Couple *seqseq, _IDL_SEQUENCE_Couple *seq ); Add a sequence of couples to a sequence of sequence of couples. If the maximum for this sequence is set (_maximum > 0) and it has been reached (_length >= _maximum), this routine does nothing. Otherwise, this makes a complete copy of the original sequence of couples; each can be manipulated separately. In other words, deleting the sequence of sequences (with vesp_couple_seqseq_delete) does not free all or part of the original sequence of couples. seqseq seq The sequence of sequences of couples to which new data is added. The data being added, a sequence of couples. VESP_BAD_PARAMETER A value passed in was NULL Example Couple *couple_in = vesp_couple_create(); Couple *couple_in2 = vesp_couple_create(); _IDL_SEQUENCE_Couple *seq_couple_in = vesp_couple_seq_create(); _IDL_SEQUENCE_Couple *seq_couple_in2 = vesp_couple_seq_create(); _IDL_SEQUENCE_sequence_Couple *seqseq_couple; /* fill some couples with data */ vesp_couple_set_values( couple_in, name, value ); vesp_couple_set_values( couple_in2, name2, value2 ); /* add a copy of couple_in to seq_couple_in */ vesp_couple_seq_add_couple( seq_couple_in, couple_in ); Issue 1.0 June 2002 197

Chapter 8 Avaya IC Toolkit Functions /* add a bunch more to seq_couple_in2 */ vesp_couple_seq_add_couple( seq_couple_in2, couple_in ); vesp_couple_seq_add_couple( seq_couple_in2, couple_in2 ); vesp_couple_seq_add_couple( seq_couple_in2, couple_in ); vesp_couple_seq_add_couple( seq_couple_in2, couple_in2 ); /**************************************************************/ /* create seqseq_couple, a sequence of 3 sequences of couples */ /**************************************************************/ seqseq_couple = vesp_couple_seqseq_create(); vesp_couple_seqseq_add_seq( seqseq_couple, seq_couple_in ); vesp_couple_seqseq_add_seq( seqseq_couple, seq_couple_in2 ); vesp_couple_seqseq_add_seq( seqseq_couple, seq_couple_in ); /* cleanup the input data, we inly need seqseq_couple, which */ /* has copies of everything else */ vesp_couple_delete( couple_in ); vesp_couple_delete( couple_in2 ); vesp_couple_seq_delete( seq_couple_in ); vesp_couple_seq_delete( seq_couple_in2 ); vesp_couple_seqseq_create Syntax _IDL_SEQUENCE_sequence_Couple *vesp_couple_seqseq_create( void ); Create a sequence of sequence of couples, i.e., allocate an _IDL_SEQUENCE_sequence_Couple structure with _length and _maximum equal to 0 and _buffer equal to NULL. vesp_couple_seqseq_delete() MUST be used to free structures allocated with this routine. VESP_BAD_PARAMETER A value passed in was NULL Example _IDL_SEQUENCE_sequence_Couple *seqseq_couple_in; seqseq_couple_in = vesp_couple_seqseq_create( ); vesp_couple_seqseq_delete Syntax vesp_couple_seqseq_delete( _IDL_SEQUENCE_sequence_Couple *seqseq ); Delete a sequence of sequence of couples created with vesp_couple_seqseq_create. This frees the structure and any sequences of couples it contains. seqseq Sequence of sequences of couples to delete (free). 198 Core Services Programmer s Guide

vesp_couple_seqseq_duplicate VESP_BAD_PARAMETER A value passed in was NULL Example vesp_couple_seqseq_delete( seqseq_couple_in ); vesp_couple_seqseq_duplicate Syntax _IDL_SEQUENCE_sequence Couple *vesp_couple_seqseq_duplicate( _IDL_SEQUENCE_sequence_Couple *in_seqseq ); Duplicate a sequence of sequences of couples. This routine creates a complete copy of the original sequence, which must be freed in the same manner as the original. in_seqseq Sequence of sequences of couples to be duplicated. Duplicated sequence of couples or a NULL vesp_couple_set_values Syntax ORBStatus vesp_couple_set_values( Couple *couple, char *name, char *value ); Set the parameters in a couple. New memory is allocated for couple->name and couple->value and the name and value strings are copied into the newly allocated memory. This routine should not be used on a Couple whose name or value is already set (non-null). Calling vesp_couple_delete() will free the strings allocated in this manner. couple name value Couple to set. Parameter name in couple. Parameter value to be set. VESP_BAD_PARAMETER A value passed in was NULL Example Couple *foo ORBStatus status; Issue 1.0 June 2002 199

Chapter 8 Avaya IC Toolkit Functions foo = vesp_couple_create( ); status = vesp_couple_set_values( foo, foo name, foo_value ); vesp_couple_delete( foo ); vesp_dump_heap Syntax void vesp_dump_heap( void ) This prints the filename and line number of the caller of vesp_calloc for every block that has been allocated. This works only if the heap testing flag is set. Blocks with filename cleared are not reported. None vesp_dup_seq_couple_value Syntax ORBStatus vesp_dup_seq_couple_value ( _IDL_SEQUENCE_Couple *in_seq, char *name, char **value); Find a couple in a sequence of couples by name and return a copy of the value string from this couple. vesp_free() MUST be used to free strings created in this manner. in_seq name value Sequence of couples to be searched. Name to search for. Pointer to value string found. VESP_BAD_PARAMETER VESP_NOT_FOUND A value passed in was NULL in_seq contained no couples with that name Example if (vesp_dup_seq_couple_value(personseq, Fname, &fname) == ) printf( The person s first name is \ %s\.\n, fname); else printf( ERROR: No first name.\n ); vesp_event_add_couple Syntax ORBStatus vesp_event_add_couple( Event *event, char *name, char *value ); Add one couple to an event. 200 Core Services Programmer s Guide

vesp_event_create If the maximum for the event sequence is set (_maximum > 0) and it has been reached (_length >= _maximum), this routine does nothing. Otherwise, it allocates space for the new couple, copies the data from *name and *value into the name and value strings of the new couple, and increments seq->_length. Calling vesp_event_delete() will free the couples allocated in this manner. The original input values will be unaffected. event name value Event created with the vesp_event_create function. Name of couple. Value of couple. VESP_BAD_PARAMETER A value passed in was NULL Example event = vesp_event_create( Test.SpecificEventName ); vesp_event_add_couple( event, arg1, value1 ); vesp_event_add_couple( event, arg2, value2 ); vesp_event_add_couple( event, arg3, value3 ); vesp_event_add_couple( event, arg4, value4 ); SCHECK( Session_send_event(session, &local_ev, Test.SpecificEventName, event) ); vesp_event_delete( event ); vesp_event_create Syntax Event *vesp _event_create ( char *event_name ); Allocates an Event structure with Event->name initialized to a copy of event_name, Event->value, Event->data._length and Event->data._maximum equal to 0 and Event->data._buffer equal to NULL. vesp_event_delete() MUST be used to free structures allocated with this routine. event_name Name string to assign to the new event. The created event Example event = vesp_event_create( Test.SpecificEventName ); vesp_event_add_couple( event, arg1, value1 ); vesp_event_add_couple( event, arg2, value2 ); vesp_event_add_couple( event, arg3, value3 ); vesp_event_add_couple( event, arg4, value4 ); SCHECK( Session_send_event(ev->session, &local_ev, Test.SpecificEventName, event) ); vesp_event_delete( event ); Issue 1.0 June 2002 201

Chapter 8 Avaya IC Toolkit Functions vesp_event_delete Syntax ORBStatus vesp_event_delete( Event *event ); Delete an event created with the function vesp_event_create. This frees the Event structure, the underlying sequence of couples and any couples contained in the underlying sequence. event Event to delete. VESP_BAD_PARAMETER A value passed in was NULL Example event = vesp_event_create( Test.SpecificEventName ); vesp_event_add_couple( event, arg1, value1 ); vesp_event_add_couple( event, arg2, value2 ); vesp_event_add_couple( event, arg3, value3 ); vesp_event_add_couple( event, arg4, value4 ); SCHECK( Session_send_event(session, &local_ev, Test.SpecificEventName, event) ); vesp_event_delete( event ); vesp_event_duplicate Syntax ORBStatus vesp_event_duplicate( Event *in_event ); Duplicate an event. This routine creates a complete copy of the original event. in_event Event to be duplicated. Duplicated event or a NULL vesp_find_error Syntax char *vesp_find_error( ORBStatus status ); Convert an error code of type ORBStatus to a descriptive text string. status Avaya IC error code to be described. 202 Core Services Programmer s Guide

vesp_format_time Text string describing the error indicated by the value of status. Example status = Vesp_Request_DDE( param_string_in, session ); if (status!=) { printf(vesp_find_error(status)); return(vesp_hybrid_add_error_to_request(param_string_in, vesp_find_error(status)); } vesp_format_time Syntax char *vesp_format_time( time_t atime ); Return a pointer to a string containing the specified date and time in the form yyyy-mo-dd hh:mm:ss\0. If it fails, Avaya IC returns a single "?" character. If successful, the resulting string is 19 characters wide, plus a null. The result is volatile (overwritten with each call.) time_t atime Time to be converted. Pointer to a string containing the time string. string with time or "?" vesp_free Syntax void vesp_free( void *ptr ); Frees a block of memory that was allocated with either vesp_calloc, vesp_malloc, vesp_strdup or vesp_realloc. This supports some extra debugging information that is used to find problems with code using the heap. ptr Memory to be freed. If there was an allocation error or memory overwrite error, it is logged to the log file. Avaya IC memory allocation includes a sentinel byte at the end of all allocated memory to detect overwrites. None vesp_get_connect_timer Syntax time_t vesp_get_connect_timer( void ); Issue 1.0 June 2002 203

Chapter 8 Avaya IC Toolkit Functions the maximum number of seconds that may elapse before a time out when attempting to connect to a server that does not exist. The maximum is set with the vesp_set_connect_timer function. The maximum number of seconds before time out. vesp_get_heap_size Syntax long vesp_get_heap_size( void ); Find out how much memory is used by Avaya IC routines. Heap size is returned as part of the Generic.GetStatus method. Count of memory allocated. vesp_get_server_version Syntax char *vesp_get_server_version( void ); Return a string that describes the server version, created with vesp_set_server_version. This information is returned as part of the Generic.GetStatus method. String created with vesp_set_server_version. vesp_get_toolkit_version Syntax char *vesp_get_toolkit_version( void ); Return a string that describes the Avaya Computer Telephony Toolkit version.this information is returned as part of the Generic.GetStatus method. Avaya Computer Telephony Toolkit version vesp_get_trace_level Syntax long vesp_get_trace_level ( void ); Get current Avaya IC trace level. Current trace level; the possible values are listed in the Trace Level section of this manual. This information is returned as part of the Generic.GetStatus method. Example trace_level = vesp_get_trace_level ( ); 204 Core Services Programmer s Guide

vesp_heap_check vesp_heap_check Syntax void vesp_heap_check(void ); Run through the blocks allocated from the heap and check that the sentinel value is not overwritten. Errors are printed into the log file. None vesp_heap_check_value Syntax int vesp_heap_check_value( char *ptr ); Check if memory allocated is valid. ptr Pointer to allocated memory. TRUE or FALSE vesp_log_info Syntax void vesp_log_info( LOGCAT cat, char *subtype, char *name ); Put a machine parsable header for a log entry into the log file. The information entered into the log file is of the form (<date & time stamp>) Info /<subtype> <name> <entry_source>. The <date & time stamp> is a string similar to the one produced by vesp_time2(). <subtype> and <name> are the values passed to vesp_log_info. <entry_source> is information about the port and source code that this entry originated from. cat subtype name Must always be constant VESP_CAT_ALL. A single-word classification of the type of information being logged. A word or short phrase describing the information being logged. None Example vesp_log_info( VESP_CAT_ALL, VESP_TRACE_IDL_CODING In Event ); ORB_object_copy_to_string( VESP_ORB, &local_ev, msg_ptr->channel, temp1 ); ORB_object_copy_to_string( VESP_ORB, &local_ev, msg_ptr->msg_num, temp2 ); log_unparsable( Session=%s, temp1 ); log_unparsable( Request=%s, temp2 ); This example would produce a logfile entry like this: Issue 1.0 June 2002 205

Chapter 8 Avaya IC Toolkit Functions (2001-06-21 11:56:08 520 ) Info /VESP_TRACE_IDL_CODING In Event ice:8007 [generic.c.496] //Session=2f3bc5f600000000780000261f580002 //Request=2e29b29a00000000780000261f410002 vesp_lose_heap Syntax void vesp_lose_heap( void ); Forget current information in the heap. This is used for debugging purposes; you know where you are in the heap and can start from a clean slate. None vesp_malloc Syntax void *vesp_malloc ( unsigned long size ); This allocates memory for use by other Avaya IC routines. It roughly emulates the standard C routine "malloc()". vesp_free() MUST be used to free memory allocated with this routine.this allows some extra debugging information to be used to find problems with code using the heap. size Size (in bytes) of the memory to be allocated. Example Pointer to newly allocated memory or the process aborts. list._buffer = vesp_malloc(numele *sizeof (*list._buffer) vesp_mkdir Syntax ORBStatus vesp_mkdir(char *dirname); This performs a mkdir function. Under UNIX, it provides a protection mode of 0700. Under Windows NT / Windows 2000, it follows NT's defaults. Under NT, the system takes either \ or / as a path delimiter, so it does no checking. Under UNIX, / is the only path delimiter, so it converts \ into /. *dirname Directory name. 206 Core Services Programmer s Guide

vesp_print_any VESP_BAD_PARAMETER VESP_ERROR Request contained an empty or NULL parameter Request failed Example vesp_mkdir(userlist); vesp_print_any Syntax ORBStatus vesp_print_any( TypeCode type, void *value ); Print the contents of any type into the log. type value Data type from IDL compiler or TC_ declaration. Value to be printed. vesp_print_environment Syntax ORBStatus vesp_print_environment( Environment *ev ); Print the contents of an environment into the log. *ev The environment to be printed. vesp_realloc Syntax void *vesp_realloc ( void *ptr, unsigned long new_size); Reallocate memory that was already allocated with an Avaya IC memory allocation routine. vesp_free() MUST be used to free memory allocated with this routine. Issue 1.0 June 2002 207

Chapter 8 Avaya IC Toolkit Functions This roughly emulates the standard C routine "realloc()". However, in this version, additional memory that has been added, if any, is zeroed out. This is a concession for compatibility with old code and should NOT be relied on. Someday vesp_realloc() will stop zeroing out added memory. This allows some extra debugging information to be used to find problems with code using the heap. ptr new_size Pointer to the original memory. Size of the new memory block. Pointer to reallocated memory, or process abort if error. vesp_set_connect_timer Syntax ORBStatus vesp_set_connect_timer( time_1 new_time ); Set the maximum number of seconds that may elapse before a time out when attempting to connect to a server that does not exist. Legal values are between one and 120 seconds. new_time The maximum number of seconds before a time out. vesp_set_exception Syntax void vesp_set_exception( Environment *ev, ULONG major, ULONG minor, char *description); Set the type codes and description string to indicate an exception in an environment variable. This is a convenience routine that fills in all the relevant fields in an environment variable to indicate an exception has been raised. The major and minor type codes are set appropriately and the vesp_error_description string in the environment variable is formatted based on the major code and the description string provided. If major is NO_EXCEPTION, ev->vesp_error_description is not changed. Otherwise, up to the first 80 characters of description become a substring of ev- >vesp_error_description. 208 Core Services Programmer s Guide

vesp_set_gmt_time ev major minor description Pointer to the Environment structure to be set. Major exception code - should be one of NO_EXCEPTION, SYSTEM_EXCEPTION, USER_EXCEPTION or USER_REJECT_EXCEPTION. Minor exception code description text string to incorporate into the formatted vesp_error_description string. String for the vesp_error_description string. None Example ORBStatus backuprec( Environment *env_p, REC *rec_p ) { if ((fp = (fopen( backup.dat, w )) == NULL) { perror(temp_str); set_exception(env_p, SYSTEM_EXCEPTION, VESP_FAILURE, temp_str); return VESP_FAILURE; }... vesp_set_gmt_time Syntax void vesp_set_gmt_time( void ); Put Avaya IC in GMT time mode. None vesp_set_local_time Syntax void vesp_set_local_time( void ); Put Avaya IC in local time mode. None vesp_set_log_name Syntax void vesp_set_log_name(char *fname); Issue 1.0 June 2002 209

Chapter 8 Avaya IC Toolkit Functions Switch to a different logfile by name. The logfile currently in use is closed and the file named by fname is opened and henceforth used for all logging. If fname is NULL, the default logfile, vesp.log is used. fname Relative pathname of the new logfile. None Example vesp_set_log_name {"test_client.log"} ; vesp_set_server_version Syntax ORBStatus vesp_set_server_version( char *version_number ); Set version information about the server. Use the function vesp_get_server_version to retrieve the version at a later time. This information is returned as part of the Generic.GetStatus method. version_number String containing version information. vesp_set_tracing Syntax void vesp_set_tracing(unsigned long trace_level ); Set Avaya IC trace level. The trace level is represented by a collection of bit flags describing various aspects of tracing. These flags can be found in the file generic.idl and are listed in Chapter 8. The most commonly used trace flags are: VESP_TRACE_FLUSH_LOG VESP_TRACE_IDL_CODING VESP_TRACE_HEAP_CHECK Flush every logfile message to disk Trace IDL messages Monitor dynamic memory state during deallocations trace_level New trace level. None 210 Core Services Programmer s Guide

vesp_strdup Example vesp_set_tracing(vesp_idl_coding VESP_TRACE_HEAP_CHECK _TRACE_FLUSH_LOG); vesp_strdup Syntax char *vesp_strdup ( char *buf ); Parameter Allocates a block of memory large enough for the passed string, copies the string into the new block and returns a pointer to the block. Memory is allocated with vesp_malloc. vesp_free() MUST be used to free memory allocated with this routine. buf Buffer to be copied. Newly allocated copied string vesp_string_seq_add_value Syntax ORBStatus vesp_string_seq_add_value( _IDL_SEQUENCE_string *seq, char *value ); Add a new string to a sequence of strings. If the maximum for this sequence is set (_maximum > 0) and it has been reached (_length >= _maximum), this routine does nothing. Otherwise, it allocates space for the new string, copies the data from *value into the allocated space, and increments seq->_length. Calling vesp_string_seq_delete() will free the strings allocated in this manner. The original string will be unaffected. seq value The sequence of strings to which new data is added. The string data being added. VESP_BAD_PARAMETER A value passed in was NULL Example projection = vesp_string_seq_create( ); vesp_string_seq_add_value( projection, per ); vesp_string_seq_delete( projection ); Issue 1.0 June 2002 211

Chapter 8 Avaya IC Toolkit Functions vesp_string_seq_create Syntax _IDL_SEQUENCE_string *vesp_string_seq_create( void ); Allocates an _IDL_SEQUENCE_string structure with _length and _maximum equal to 0 and _buffer equal to NULL. vesp_string_seq_delete() MUST be used to free structures allocated with this routine. New sequence of strings Example projection = vesp_string_seq_create( ); vesp_string_seq_add_value( projection, per ); vesp_string_seq_delete( projection ); vesp_string_seq_delete Syntax ORBStatus vesp_string_seq_delete( _IDL_SEQUENCE_string *seq ); Delete a sequence of strings created with vesp_string_seq_create. This frees the structure and any strings it contains. seq Sequence of strings to delete (free). VESP_BAD_PARAMETER A value passed in was NULL Example projection = vesp_string_seq_create( ); vesp_string_seq_add_value( projection, per ); vesp_string_seq_delete( projection ); vesp_string_seq_duplicate Syntax _IDL_SEQUENCE_string *vesp_string_seq_duplicate( _IDL_SEQUENCE_string *in_seq ); Duplicates a sequence of strings.this routine creates a complete copy of the original sequence, which must be freed in the same manner as the original. in_seq Sequence of strings to be duplicated. Duplicate sequence of strings or NULL if error 212 Core Services Programmer s Guide

vesp_time vesp_time Syntax char *vesp_time( void ); Return a pointer to a static buffer containing the current date and time string. If it fails, Avaya IC returns a single "?" character. If successful, the resulting string is 19 characters wide, plus a null. The result is volatile (overwritten with each call.) string with time or "?" vesp_time2 Syntax char *vesp_time2( void ); Return a pointer to a static buffer containing the current date and time string. If it fails, we return a single "?" character. The result is volatile (overwritten with each call). If the operating system supports millisecond access, millisecond information is included. string with time or "?" vnet_destroy Syntax void vnet_destroy( void ); This is used after a process forks and before it execs and wants to release sockets. We don't free memory. We expect an exec() to destroy the world anyway. This call is also an appropriate way to close connections in a process crash. None Example /* stop all sockets so orb server can restart if needed */ vnet_destroy(); PRINT( LOGFILE, ORB Server Starting child ); vesp_close_log(); if ( chdir( home_dir )!= 0 ) { PRINT( LOGFILE, Could not change to new home dir ); } if (( status = excel( value, value, uuid, object_str_gbl, NULL ) ) == -1 ) { PRINT( LOGFILE, ORB Server after Exec failed for child ); PRINT( LOGFILE, ORB Server child exec failed existing ); exit (20); } /* should never get here */ PRINT( LOGFILE, ORB Server after Exec for child ); Issue 1.0 June 2002 213

Chapter 8 Avaya IC Toolkit Functions vnet_setusersoc_callback Syntax void vnet_setusersoc_callback( int maxdfn, void *bits, void (*uc)(void *) ); Specify a max fd number, a select()-style fd_set mask in bits, and a callback to invoke when any of those sockets have read activity. The Callback is given a copy of the fd_set with interesting bits set. maxdfn bits uc The highest socket number in use by the application. Pointer to a fd_set mask. as defined for select(). The callback to invoke on a read. Example None /* Call here to add (in T) or drop (in F) a socket. * We have to tell vnet portion of the toolkit to keep track of the socket. */ static void fixup_mask(init soc, int in) { if (soc < 0) return; if (in) /* Add it */ { FD_SET(soc, &oursockets); if (soc > maxoursock) maxsock = soc; } else /* remove it */ FD_CLR(soc, &oursockets); /* Tell vnet about the new socket */ vnet_setusersoc_callback(maxoursock, &oursockets, vru_input); } vnet_status Syntax void vnet_status( void ) Print internal networking information to the log file. None 214 Core Services Programmer s Guide

INDEX A adding ODBC data source 113 Alarm 50 Alarm 50 alarm description 51 alarm priority 50 51 AlarmNoHistory 51 AlarmSpecial 51 Assign 52 configuration 46 Data Elements 46 Deassign 53 event monitoring criteria 48 Interface Specification 50 Monitor 53 Monitoring Events 48 Alarm Monitoring 48 Alarm Server Overview 45 AlarmNoHistory 51 Alarms 54, 100 Alarm Server 54 Directory Server 100 ORB Server 43 Alarms, in a WAN environment 45 AlarmSpecial 51 Assign 52, 68 B Backup 68, 89 backup.ffd file 100 BOA_change_implementation 127 BOA_create 127 BOA_deactivate_impl 127 BOA_deactivate_obj 128 BOA_delete_method 128 BOA_dispose 128 BOA_get_id 128 BOA_get_principle 128 BOA_impl_is_ready 129 BOA_obj_is_ready 129 BOA_set_exception 129 BOA_set_method 129 C ChangePassword 69 close_log 192 Configuration Alarm Server 46 Directory Server 57 ORB Server 35 Configuring the Alarm Server 46 Context_create_child 130 Context_delete 130 Context_delete_values 131 Context_get_configuration 131 Context_get_one_seq_config_value 132 Context_get_one_seq_value 133 Context_get_one_value 134 Context_get_values 135 Context_print 135 Context_set_values 136 Crashes, responding to 34 CreateDBTableRecord 70 CreateRecord 71 CreateViewRecord 73 Creating records 63 creation_timestamp 63 D Data Connector Server Overview 105 Data Elements Alarm Server 46 Data Service architecture 106 configuration parameters 108 connecting to 109 deactivate_obj 36 Deassign 53, 74 DeleteDBTableRecord 74 DeleteRecords 65, 75 DeleteUser 77 DeleteViewRecord 77 Deleting records 65 Directory Server Alarms 100 Configuration 57 IDL 67 215

Index Overview 55 Performance 58 Sizing recommendations 59 Directory structure 59 DISPLAY_TIME= HOSTTIME 111 DISPLAYTIME= DBMSTIME 111 DISPLAYTIME= LOCALTIME 111 DS Assign 68 Backup 68, 89 ChangePassword 69 CreateRecord 71 Deassign 74 DeleteRecords 75 DeleteUser 77 ForceChangePassword 78 GetCount 79 GetFewRecords 81 GetOneAttribute 83 GetRecords 84 Login 88 ReleaseRecords 88 Restore 89 SelDeleteRecords 91 SelectRecords 92 SelGetRecords 93 UpdateRecords 95 96 WhoIsYourParent 99 E educational services 9 Event Monitoring Criteria 48 F File structure Directory Server 59 flush_log 136 ForceChangePassword 78 free_breakpoint_routine 136 G Generating Alarms 47 Generic server methods 13 Generic.Crash 15 Generic.CreateNote 15 Generic.CreateUUID 16 Generic.Deassign 16 Generic.DecodeUUID 17 Generic.DeleteAllNotes 17 Generic.DeleteNote 18 Generic.DisableServer 18 Generic.EnableServer 19 Generic.Exit 19 Generic.FlushLog 19 Generic.GenericUpdate 20 Generic.GetAllNotes 21 Generic.GetCtime 21 Generic.GetEnviron 22 Generic.GetFile 22 Generic.GetImpRepository 23 Generic.GetIntRepository 23 Generic.GetMemoryCount 23 Generic.GetNote 24 Generic.GetServerVersion 24 Generic.GetStatus 25 Generic.GetTimet 25 Generic.GetToolkitVersion 26 Generic.GetTracing 26 Generic.LoadNewImplementation 26 Generic.LoseHeap 27 Generic.MonitorNote 27 Generic.Ping 27 Generic.PrintAll 27 Generic.PrintAllRequests 28 Generic.PrintSessionInfo 28 Generic.PutEnviron 28 Generic.SetTracing 29 Generic.ShowHeap 29 Generic.ShowMemoryCache 29 Generic.ShowNetworkStatus 30 Generic.Shutdown 30 Generic.SystemCall 30 GenericUpdate 36 GetCount 79 GetDBRecordCount 80 GetDBRecordsFromATable 80 GetFewRecords 64, 81 GetOneAttribute 64, 83 GetRecords 64, 84 GetViewRecord 86 GetViewRecordCount 87 I IDL Alarm Server 50 Directory Server 67 Generic 13 ORB Server 35 IDL Specification 50 K key 63 216 Core Services Programmer s Guide

Index L limitations for ODBC 114 log_unparsable 136 Login 88 M Methods, generic 13 Monitor 53 N Names, restrictions in the DS 60 NVList_add_item 137 NVList_free 138 NVList_free_memory 138 NVList_get_count 138 NVList_get_values 139 NVList_print 140 NVList_set_values 140 O obj_is_ready 37 Object_compare 141 Object_create_request 142 Object_decode 142 Object_Duplicate 144 Object_duplicate 144 Object_is_nil 144 Object_print 145 Object_release 145 ODBC adding data source 113 data source 112 database name setting 115 driver requirements 114 interface 112 limitations 114 mapping to data types 116 setup 112 ORB Server 33 Alarms 43 Configuration 35 deactivate_obj 36 GenericUpdate 36 IDL 35 obj_is_ready 37 Overview 33 Resolve 37 SetBackoffTimer 38 SetServiceProperty 38 StartServer 39 StartServerByUuid 39 StopServer 40 TerminateAllServers 41 TerminateAutostart 41 TerminateServer 42 TerminateVESP 42 ORB_create_context 146 ORB_create_list 146 ORB_create_operation_list 147 ORB_get_default_context 147 ORB_get_session_lifetime 148 ORB_object_copy_to_string 149 ORB_object_to_string 149 ORB_print_ev 150 ORB_set_session_lifetime 150 ORB_string_copy_to_object 151 ORB_string_to_object 151 Overview 45 Alarm Server 45 Directory Server 55 ORB Server 33 P Parent directory, defined 56 Performance, Directory Server 58 Predefined Data Elements 46 R Reading records 64 Record fields Directory Server 59 Records Creating 63 Deleting 65 Reading 64 Selecting 63 ReleaseRecords 88 Releasing records 63 Request_defer 152 Request_delete 153 Request_get_ev 153 Request_get_group 154 Request_get_response 155 Request_send 155 Request_send_deferred_response 156 Requests, directed to a specific server 34 Resolve 37 Restore 89 Restoring the directory 100 running in different timezones 110 Issue 1.0 June 2002 217

Index S SelDeleteRecords 91 selectcriteria 65 Selecting records 63 Selection criteria 65 Selection Criteria Wildcards 49 selection key 63 SelectRecords 63, 92 SelGetRecords 64, 93 SELKEY 63 64 SelUpdateRecords 95 Server record, defined 61 Server_set_client_terminate_routine 163 Server_set_status_hook_routine 163 Server_set_user_exception_routine 164 Server_set_user_exit_routine 164 Server_set_user_init_routine 165 Server_set_user_poll_routine 166 Servers Adding 34 Directing requests to a specific 34 Responding to crashes 34 Timing restarts of 34 Updating configuration of 34 Session_change_group 166 Session_create_request 167 Session_delete 168 Session_delete_request 168 Session_exist 169 Session_get_context 169 Session_get_message_timeout 169 Session_print 170 Session_send 170 Session_send_event 171 Session_set_context 171 Session_set_message_timeout 172 SetBackoffTimer 38 SetServiceProperty 38 Sharing Alarms Across a WAN 45 Starting and Stopping Alarm Monitoring 48 Starting and stopping servers 33 StartServer 39 StartServerByUuid 39 StopServer 40 T TerminateAllServers 41 TerminateAutostart 41 TerminateServer 42 TerminateVESP 42 The 55 timezones running in 110 values 110 Timing server restarts 34 U update_time 63 UpdateDBTableRecord 96 UpdateRecords 95 96 UpdateViewRecord 98 Updating records 64 Updating server configuration 34 User record, defined 61 V vesp.imp, updating 34 vesp_assign_request 172 vesp_broadcast_event 174 vesp_calloc 192 vesp_change_password 175 vesp_close_log 192 vesp_couple_create 193 vesp_couple_delete 193 vesp_couple_seq_add_couple 194 vesp_couple_seq_add_couple_values 194 vesp_couple_seq_create 195 vesp_couple_seq_delete 196 vesp_couple_seq_duplicate 196 vesp_couple_seqseq_add_seq 197 vesp_couple_seqseq_create 198 vesp_couple_seqseq_delete 198 vesp_couple_seqseq_duplicate 199 vesp_couple_set_values 199 vesp_dde_get_next_response 175 vesp_deassign_request 176 vesp_dump_heap 200 vesp_dup_seq_couple_value 200 vesp_event_add_couple 200 vesp_event_create 201 vesp_event_delete 202 vesp_event_duplicate 202 vesp_find_error 202 vesp_force_password 177 vesp_format_time 203 vesp_free 203 vesp_get_connect_timer 203 vesp_get_default_session 177 vesp_get_heap_size 204 vesp_get_server_version 204 vesp_get_toolkit_version 204 vesp_get_trace_level 204 vesp_heap_check 205 vesp_heap_check_value 205 vesp_load _Interface 179 218 Core Services Programmer s Guide

Index vesp_load_implementation 178 vesp_log_info 205 vesp_login 179 vesp_logout 180 vesp_lose_heap 206 vesp_malloc 206 vesp_mkdir 206 vesp_poll 180 vesp_print_any 207 vesp_print_environment 207 vesp_realloc 207 vesp_reload_imp 181 vesp_reload_imp_local 181 vesp_request 182 vesp_request_dde 184 vesp_request_dde_sync 184 vesp_request_delete 185 vesp_request_sync 185 vesp_send_alarm 186 vesp_send_alarm_no_history 187 vesp_server_login 187 vesp_session_create 188 vesp_session_delete 188 vesp_set_client_port 189 vesp_set_connect_timer 208 vesp_set_exception 208 vesp_set_gmt_time 209 vesp_set_local_time 209 vesp_set_log_name 209 vesp_set_server_version 210 vesp_set_tracing 210 vesp_strdup 211 vesp_string_seq_add_value 211 vesp_string_seq_create 212 vesp_string_seq_delete 212 vesp_string_seq_duplicate 212 vesp_time 213 vesp_time2 213 vesp_timed_function_delete 189 vesp_timed_function_poll 190 vesp_timed_function_print 190 vesp_timed_function_register 190 vesp_timed_function_reset 192 vnet_destroy 213 vnet_setusersoc_callback 214 vnet_status 214 W WAN considerations, DS 56 WhoIsYourParent 99 Issue 1.0 June 2002 219

Index 220 Core Services Programmer s Guide