WebSphere Voice Response for AIX with DirectTalk Technology. Custom Servers. Version 6.1 SC

Transcription

1 WebSphere Voice Response for AIX with DirectTalk Technology Custom Servers Version 6.1 SC

2 Note Before using this information and the product it supports, read the general information under Notices on page 329. This edition applies to Version 6, Release 1 of IBM WebSphere Voice Response for AIX with DirectTalk Technology (program number 5724-I07), and to all subsequent releases and modifications until otherwise indicated in new editions. Make sure you are using the correct edition for the level of the product. Copyright International Business Machines Corporation 1991, US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

3 Contents Figures vii Tables ix About this book xi Who should read this book xi How to use this book xi Following the procedures in this book... xi Typographic conventions xii Accessibility xii Notes on terminology xiii Where to find more information..... xiii Useful Web sites xiii Making comments on this book..... xiv Chapter 1. Introduction Components of a custom server The main() function System-generated main() function Coding the main() function main() arguments User functions User function parameters The initialization user function The termination user function The open and close functions Chapter 2. Developing a custom server.. 15 How to create a custom server Creating the main() function Defining the main() function Defining user functions and parameters.. 18 Defining properties Completing the main() function Creating user functions Importing files into the custom server directory Importing custom servers Building a custom server Viewing the generated files Debugging a custom server Tracing custom servers How to interpret a custom server trace Editing a custom server definition Installing and deinstalling a custom server.. 35 Putting a custom server into production.. 35 Completing the state table Initializing a custom server Integrating a custom server with other software Executing a custom server Runtime environment What does pool buffer threshold reached mean? Shutting down custom server processes Using custom servers on a single system image Creating an SSI-compliant custom server 42 Changing the AIX environment of a custom server Connecting to a DB2 database Chapter 3. Using custom server subroutines Initializing and terminating the custom server 45 Keeping custom servers in step with the custom server library Interacting with a channel process Custom servers that wait to be called by state tables Custom servers that are not initiated by state tables Simulating events on the channel process.. 49 Managing other custom servers Accessing the WebSphere Voice Response database Manipulating application profiles Manipulating voice segments Manipulating audio names and user greetings Manipulating voice messages Importing and exporting voice Accessing voice channels directly Using synchronous foreground operations 55 Using asynchronous background operation 56 Connecting channels using the time division multiplex (TDM) bus Making and breaking TDM connections.. 58 Logging errors Copyright IBM Corp. 1991, 2009 iii

4 Logging events Trace points Trace points example Chapter 4. Single-process and multiprocess custom servers Single-process blocking operation Single-process nonblocking operation Multiprocess non-associated operation Multiprocess associated operation Chapter 5. Custom server subroutines.. 75 Summary of subroutines grouped by use.. 75 Control subroutines Application subroutines Voice channel subroutines Other custom server subroutines Profile subroutines Import and export subroutines Voice database subroutines Delete database objects subroutines Trace subroutines Statistics subroutine TDM subroutines CA_Close_Channel() CA_Close_CHP_Link() CA_Close_Music_Channel() CA_Close_Record_Channel() CA_Create_Audio_Name() CA_Create_Greeting() CA_Create_Profile() CA_Create_Segment() CA_Create_Voice_Msg() CA_Create_Voice_Msg_Id() CA_Deinstall_CA() CA_Delete_3270_Server() CA_Delete_Audio_Name() CA_Delete_CA() CA_Delete_Greeting() CA_Delete_Profile() CA_Delete_Prompt_Dir() CA_Delete_Segment() CA_Delete_State_Table() CA_Delete_Subscriber_Class() CA_Delete_Voice_Dir() CA_Delete_Voice_Msg() CA_Delete_Voice_Table() CA_Execute_State_Table() CA_Export_Voice() CA_Get_Audio_Name() CA_Get_Audio_Name_Info() CA_Get_CA_Info() CA_Get_Channel_Info() CA_Get_Channel_Play_Status CA_Get_DT_Info() CA_Get_DT_Parameters() CA_Get_Element_Count CA_Get_Element_Info() CA_Get_Greeting() CA_Get_Greeting_Info() CA_Get_Profile() CA_Get_Profile_Count() CA_Get_Profile_List() CA_Get_Segment() CA_Get_Segment_Info() CA_Get_System_State() CA_Get_Voice_Msg() CA_Get_Voice_Msg_Info() CA_Import_Voice() CA_Init() CA_Install_CA() CA_Log_Error() CA_Log_Event() CA_Open_Channel() CA_Open_CHP_Link() CA_Open_Music_Channel() CA_Open_Record_Channel() CA_Ping_CHP_Link() CA_Play_Voice_Elements() CA_Play_Voice_Stream() CA_Poll() CA_Put_DT_Parameters() CA_Receive_DT_Msg() CA_Record_Voice_Stream() CA_Report_Channel_Event() CA_Save_Voice_Msg() CA_Send_CA_Msg() CA_Send_DT_Error() CA_Send_DT_Msg() CA_Send_Voice_Msg() CA_Set_CA_Ipl_Status() CA_Set_CA_Version() CA_Set_Options() CA_Set_Profile_Defaults() CA_Set_Send_Voice_Msg_Defaults() CA_Set_Voice_Msg_Listened() CA_Simulate_Alphas() CA_Simulate_Hangup() CA_Simulate_Keys() CA_Start_CA() iv Custom Servers

5 CA_Start_Record_Channel() CA_Stop_CA() CA_Stop_Record_Channel() CA_TDD_Create_Segment() CA_TDD_Get_String() CA_TDD_Play_String() CA_TDM_Connect() CA_TDM_Disconnect() CA_Terminate() CA_Trace_Data(), CA_TRACE_DATA() 258 CA_Trace_String(), CA_TRACE_STRING() 260 CA_Update_Profile() Chapter 6. Subroutine parameter structures AUDIO_NAME_INFO_ST AUDIO_NAME_PARM_ST CA_INFO_ST CA_OPTIONS_ST CHANNEL_INFO_ST CHANNEL_POLL_ST CREATE_VOICE_MSG_ID_PARM_ST CREATE_VOICE_MSG_PARM_ST DELETE_VOICE_MSG_PARM_ST DT_INFO_ST DT_MSG_INFO_ST ELEMENT_INFO_ST EXECUTE_STATE_TABLE_RETURN_ST EXT_VOICE_ST GET_VOICE_MSG_PARM_ST GET_VOICE_MSG_INFO_PARM_ST GREETING_INFO_ST GREETING_PARM_ST INT_VOICE_ST MAILBOX_INFO_ST MUSIC_CHANNEL_PARM_ST PLAY_VOICE_ELEMENTS_PARM_ST PLAY_VOICE_ELEMENTS_RTN_ST PLAY_VOICE_STREAM_PARM_ST PLAY_VOICE_STREAM_RTN_ST PROFILE_INFO_ST PROFILE_LIST_PARM_ST PROFILE_LIST_ST RECORD_CHANNEL_OPEN_ST RECORD_CHANNEL_START_ST RECORD_CHANNEL_START_RTN_ST RECORD_CHANNEL_STOP_RTN_ST RECORD_VOICE_STREAM_PARM_ST RECORD_VOICE_STREAM_RTN_ST SAVE_VOICE_MSG_PARM_ST SEGMENT_INFO_ST SEGMENT_PARM_ST SEND_VOICE_MSG_PARM_ST SET_VOICE_MSG_LISTENED_PARM_ST 291 TDM_CONNECT_ST TDM_DISCONNECT_ST VOICE_MSG_DATA_ID_ST VOICE_MSG_INFO_ST Chapter 7. Error return codes Chapter 8. Example user function parameters Function Function Function Function Function Function Function Function Function Function Appendix. ID and name limitations Notices Trademarks Glossary List of WebSphere Voice Response and associated documentation WebSphere Voice Response software IBM hardware for use with WebSphere Voice Response WebSphere Voice Response related products 368 WebSphere Voice Server Unified Messaging for WebSphere Voice Response AIX and the IBM pseries computer HACMP SS Integrated Services Digital Network Bellcore Specifications for ADSI Telephones 371 Index Contents v

6 vi Custom Servers

7 Figures 1. Custom server interface Custom Server window Multiple instances of one output parameter Multiple instances of more than one output parameter Custom Server window User Function window Custom Server Properties window Build Report window Generated Header File window Custom Server Debug window Extract from a custom server trace Custom Server development activities Buffer pool usage Copyright IBM Corp. 1991, 2009 vii

8 viii Custom Servers

9 Tables 1. Creating and retrieving audio names Valid combinations of format and sample_width fields Error return codes by error code Error names listed alphabetically 299 Copyright IBM Corp. 1991, 2009 ix

10 x Custom Servers

11 About this book This book describes how to design and create custom servers for IBM WebSphere Voice Response for AIX with DirectTalk Technology. Design your voice application before starting work on your custom server; for information on designing voice applications read the WebSphere Voice Response for AIX: Designing and Managing State Table Applications guide. For information about managing custom servers see the WebSphere Voice Response for AIX: Managing and Monitoring the System guide. Throughout this book, the IBM WebSphere Voice Response for AIX system is referred to as WebSphere Voice Response. Who should read this book This book is for programmers familiar with the C or C++ languages. To use this book you should be familiar with AIX for use on the pseries computer, AIXwindows, and WebSphere Voice Response. How to use this book This book contains background information, procedures, and reference information. The procedures explain how to complete the tasks for which you are responsible. The background information explains when to use the procedures and contains prerequisites for using them successfully. Before you use any procedure for the first time, take a moment to read through all of the background information. Following the procedures in this book The procedures assume that you are already familiar with using a mouse and window environment and that you know how to use the common actions such as Save to work with information. If you are new to WebSphere Voice Response, have a look at the WebSphere Voice Response for AIX: User Interface Guide, which tells you how to log on and log off, and use the WebSphere Voice Response windows efficiently. Copyright IBM Corp. 1991, 2009 xi

12 Typographic conventions This book uses the following typographic conventions: boldface Identifies an item that is in a WebSphere Voice Response window. The item might be a keyword, an action, a field label, or a pushbutton. Whenever one of the steps in a procedure includes a word in boldface, look in the window for an item that is labeled with that word. boldface italics Are used for emphasis. Take extra care wherever you see bold italics. italics Identify one of the following: v New terms that describe WebSphere Voice Response components or concepts. A term that is printed in italics is usually followed by its definition. v Parameters for which you supply the actual names or values. v References to other books. monospace Identifies one of the following: v Text that you type in an AIX window. Because AIX is case sensitive, ensure that you type the uppercase and lowercase characters exactly as shown. v Names of files and directories (path names). Accessibility WebSphere Voice Response for AIX is a voice application enabler. The applications that are developed to run on WebSphere Voice Response provide telephone access to business data and services. In this way, WebSphere Voice Response provides accessibility for people who cannot access the data and services by using regular Web pages or traditional graphic interfaces. These telephone user interfaces are fully accessible to people who are blind or have low vision and, if speech recognition is used, to people with mobility impairments or limited hand use. Speech recognition capability can be provided by products such as IBM WebSphere Voice Server. In addition, support for users of Telephony Devices for the Deaf (TDD) is provided as part of the WebSphere Voice Response product. With WebSphere Voice Response you can perform many application development and system administration tasks with a text editor or line commands these are accessible if you use a screen reader product to interface with them. Also, the default settings of the WebSphere Voice xii Custom Servers

13 Response graphical user interface can be changed to produce large fonts and high contrast colors. Details of how to use these accessibility features can be found in the WebSphere Voice Response for AIX: User Interface Guide. Alternatively, application development can be done with Java or VoiceXML development tools that are supplied by IBM and third parties. You can also use a screen-reader product to access the WebSphere Voice Response publications in HTML format (for details of their availability refer to List of WebSphere Voice Response and associated documentation on page 367 at the back of this book). Notes on terminology v A glossary of commonly-used terms is at the end of this book. v The full product name of WebSphere Voice Response for AIX with DirectTalk Technology is generally abbreviated in this book to WebSphere Voice Response. v The term pseries is generically used in this book to refer both to PCI-based RS/6000 computers and to appropriate models of the System and p5 pseries ranges. (Consult your IBM representative for details of models that are supported for use with WebSphere Voice Response.) RS/6000 computers with an MCA bus are not supported. v The IBM Quad Digital Trunk Telephony PCI Adapter is generally referred to in this book by its abbreviation DTTA. This adapter is a replacement for the IBM ARTIC960RxD Quad Digital Trunk PCI Adapter, which is generally referred to by the abbreviation DTXA. The DTXA is not supported with WebSphere Voice Response Version 6.1. v References made to the VoiceXML 2.1 specification are intended to include VoiceXML 2.0 unless otherwise specified. Where to find more information The information provided in the WebSphere Voice Response library will help you complete WebSphere Voice Response tasks more quickly. A complete list of the available books and where you can obtain them is shown in List of WebSphere Voice Response and associated documentation on page 367. Useful Web sites The following Web sites are useful sources of information about WebSphere Voice Response and related products: WebSphere Voice Response About this book xiii

14 IBM WebSphere developerworks resources (including WebSphere Voice products) VoiceXML Version 2.0 and 2.1 specifications CCXML Version 1.0 specification Genesys For more information on Genesys products go to the Genesys Web site at Making comments on this book If you especially like or dislike anything about this book, feel free to send us your comments. You can comment on what you regard as specific errors or omissions, and on the accuracy, organization, subject matter, or completeness of this book. Please limit your comments to the information that is in this book and to the way in which the information is presented. Speak to your IBM representative if you have suggestions about the product itself. When you send us comments, you grant to IBM a nonexclusive right to use or distribute the information in any way it believes appropriate without incurring any obligation to you. You can get your comments to us quickly by sending an to idrcf@hursley.ibm.com. Alternatively, you can mail your comments to: User Technologies, IBM United Kingdom Laboratories, Mail Point 095, Hursley Park, Winchester, Hampshire, SO21 2JN, United Kingdom Please ensure that you include the book title, order number, and edition date. xiv Custom Servers

15 Chapter 1. Introduction A custom server is a program, using the C or C++ language, that provides an interface between data on host computers and WebSphere Voice Response, or performs other processes, such as speech recognition and speech synthesis, generation of fax output, or coordinated call and data transfer. The data on the host system can include business information held in a database, or digitized voice data. A custom server that uses the signaling interface, a specialized library of C subroutines, is known as a signaling process. This is used to manage an external signaling device that controls or monitors telephony channels. For more information, see the WebSphere Voice Response for AIX: Programming for the Signaling Interface guide. Access to remote data means that your voice applications can use this data to perform a variety of tasks, such as: v Read a file or database to retrieve information that a caller needs. v Maintain or manipulate files based on a caller s request. v Obtain information from a combination of sources and business applications on other host computers. v Call another program to perform any predefined process. v Perform calculations and return the result to the state table. v Generate business statistics based on telephony activity. v Recognize spoken words using an external speech recognition server. v Speak words created by an external text-to-speech server or sent from another WebSphere Voice Response system. v Generate fax output. Custom servers are usually invoked by state tables, but they can also be called by other custom servers. Custom servers can be of two types: v Applications that wait to be called by one or more state tables. This type is the most common custom server, typically used for processing functions requested from incoming calls. v Applications that are initiated by other means under your control, such as another program or a timed event. This type is useful for processes like outbound calling, invoking a state table which might then call other custom servers and state tables. Copyright IBM Corp. 1991,

16 The capabilities of a custom server are limited only by the resources of the pseries computer and the connectivity options at your site. You can communicate with other systems such as the IBM AS/400, or the Apple Macintosh, Hewlett Packard, or DEC personal computers, using any communications protocol supported by the pseries computer (refer to the Communications Programming Concepts manual for information about communications protocols). A sample application, the CustomServerSample, is supplied with WebSphere Voice Response. For information about this sample, see the WebSphere Voice Response for AIX: Designing and Managing State Table Applications guide. Attention: Do not use multiple threads in a custom server program. It will not work correctly if there is more than one thread. This chapter describes the components of a custom server. Components of a custom server A custom server is made up of the following: v A name and a description. v A main() function, which can be either generated by the system using information that you supply, or coded by you. See The main() function on page 3. v User functions, which perform the required processes, such as accessing host data. User functions are optional if you code the main() function yourself. See User functions on page 5. These components provide the custom server interface between a WebSphere Voice Response state table and data on a host computer, as shown in Figure 1 on page 3. 2 Custom Servers

17 RS/6000 DirectTalk State Table : OpenHostServerLink : SendData : ReceiveData : SendData ReceiveData : CloseHostServerLink : User Function Custom Server Main Function User Function Local Host Data User Function Remote Host Remote Host Data Host Application Figure 1. Custom server interface The main() function The main() function of a custom server can perform any of the following activities: v Initialize global variables v Call the user functions v Handle voice application requests and return responses to the state table v Invoke other state tables v Access WebSphere Voice Response data v Control the processing logic flow A custom server main() function can be simple or complex. Depending on your custom server requirements, you can create the main() function yourself or use a system-generated main() function. How to code the main() function is explained in more detail in Creating the main() function on page 16. System-generated main() function You can provide information that WebSphere Voice Response uses to automatically generate the main() function. A system-generated main() Chapter 1. Introduction 3

18 function is a relatively straightforward single-process program that performs the following general steps repeatedly until it is terminated by WebSphere Voice Response: v Receives a request v Extracts input data from the request v Calls a user function to handle the request v Places output data into a response v Sends the response When your custom server requirements can be satisfied by a system-generated main() function, you use only the WebSphere Voice Response windows to specify information about the main() function. WebSphere Voice Response then generates the C language or C++ language code for the main() function, and performs the compile and link processes during the build. Coding the main() function If your custom server requirements do not conform to the general steps provided by a system-generated main() function, you will need to code the main() function yourself using C language or C++ language and custom server subroutines (described in Chapter 5, Custom server subroutines, on page 75). Activities may include invoking state tables, starting or stopping other custom servers, executing multiple custom server processes concurrently, accessing WebSphere Voice Response data in application profiles and mailboxes, and manipulating audio data (voice segments, voice messages, audio names, and user greetings). When you code the main() function yourself, you use the WebSphere Voice Response windows to specify general information about the main() function. WebSphere Voice Response then performs the compile and link processes during the build. How to code the main() function is explained in more detail in Creating the main() function on page 16. main() arguments The main() arguments are the input parameters required by the main() function. The main() arguments that you define are used in the following situations: v The custom server IPL status is set to AUTOEXEC (see the WebSphere Voice Response for AIX: Configuring the System guide). v The custom server is started from the Custom Server Manager window (see the WebSphere Voice Response for AIX: Configuring the System guide). v The custom server is started by another custom server using the CA_Start_CA() subroutine, and the number of arguments (num_args) isset to zero (see CA_Start_CA() on page 236). 4 Custom Servers

19 The main() arguments that you define are not used when: v The custom server is started by the custom server debug process (see Debugging a custom server on page 29). v The custom server is started by another custom server, and the number of arguments (num_args) is greater than zero. v The custom server is started from the command line or a shell script. The main() arguments can be updated and saved without having to rebuild and install the custom server. Modified main() arguments are used the next time the custom server is started. Syntax The names of the main() arguments are character strings or numbers. For example: input1.data /tmp/phonefile User functions User functions are one or more functions that you provide written in C or C++. They are linked to, and called by, the main() function. They can establish the necessary links to host computers, provide the application logic to access the required data, or perform other general processes. User functions are not mandatory if you code the main() function yourself. A state table interacts with a custom server by invoking user functions, and passing them parameters. The user functions perform the requested processes and pass information back to the calling voice application state table. Refer to User function parameters on page 6 for rules governing valid user function input and output parameters. A single main() function generally calls several user functions. You can code user functions on the pseries computer, or copy them to the pseries computer using the custom server import facility (see Importing files into the custom server directory on page 25). User functions can use custom server subroutines. Four special user functions can be defined on the Custom Server window, see Figure 2 on page 6. These special user functions are: v The initialization user function on page 10 v The termination user function on page 11 Chapter 1. Introduction 5

20 v The open and close functions on page 12 Figure 2. Custom Server window User function parameters User function input and output parameters are processed by the SendData, GetFindData, and ReceiveData state table actions. To define user function parameters, see Defining user functions and parameters on page 18. Even if a system-generated main is not going to be used, it is useful to produce one and examine the user function parameters in the files customservername_main.c and customservername_hdr.c. If system variables are passed, make sure that the appropriate Data Type is used, as defined in the table System variables listed numerically in the system variables appendix in the WebSphere Voice Response for AIX: Application Development using State Tables reference manual. For examples showing the formats in which various parameter combinations are expected by WebSphere Voice Response, see Chapter 8, Example user function parameters, on page Custom Servers

21 Input parameters The calling state table passes input parameters to a user function. Input parameters are restricted to the following data types: char A single character or a character string. Character strings are denoted by type char followed by length X, where X is the maximum length of the string including the NULL terminator. When character strings are returned, the string must be truncated to the length of the data including the NULL character. For examples of how to code this type of parameter, see Functions 1, 2, 3, and 4 in Chapter 8, Example user function parameters, on page 311. uchar An unformatted binary string. short long Note: A uchar of length 1 is implemented as a uchar[1], whereas a char of length 1 is implemented as a single character. A short integer (2 bytes). For examples of how to code this type of parameter, see Function 1 on page 312, and Function 2 on page 313. A long integer (4 bytes). For examples of how to code this type of parameter, see Functions 3, 5, 6, 7, 8, 9, and 10 in Chapter 8, Example user function parameters, on page 311. struct The beginning of the definition of variables within a structure. Structures can be nested. For examples of how to code this type of parameter, see Function 9 on page 323, and Function 10 on page 325. endstruct The end of the data variables within the structure. output pointer A pointer to a buffer for output parameters. For examples of how to code this type of parameter, see Functions 4, 5, 6, and 7 in Chapter 8, Example user function parameters, on page 311. Output parameters A user function passes output parameters back to the calling state table. Output parameters are restricted to the following data types: char A single character or a character string. For examples of how to code this type of parameter, see Functions 3, 6, 7, and 10 in Chapter 8, Example user function parameters, on page 311. Character strings are denoted by type char followed by length X, where X is the maximum length of the string including the NULL Chapter 1. Introduction 7

22 short long terminator. When character strings are returned, the string must be truncated to the length of the data including the NULL character. A short integer (2 bytes). For examples of how to code this type of parameter, see Functions 4, 7, and 8 in Chapter 8, Example user function parameters, on page 311. A long integer (4 bytes). For examples of how to code this type of parameter, see Functions 2, 3, 5, 7, and 10 in Chapter 8, Example user function parameters, on page 311. struct The beginning of the definition of variables within a structure. For an example of how to code this type of parameter, see Function 9 on page 323. endstruct The end of the data variables within the structure. You can define one or more output parameters for a user function in the User Function window. If there is only one output parameter the user function can use the C return statement, to reply to the calling state table. For examples, see Function 1 on page 312 and Function 2 on page 313. If there is more than one output parameter you have two options: 1. Define an OUTPTR in the Input Parameters pane of the User Function window. For examples, see Functions 4, 5, 6, and 7 in Chapter 8, Example user function parameters, on page If an OUTPTR is not defined as above a system generated main expects the user function to return a pointer to a buffer containing the data. For examples, see Functions 3, 8, 9, and 10 in Chapter 8, Example user function parameters, on page 311. Note that example Function 8 on page 321 has only one output parameter, but it has a Return Type Multiple and therefore must return the address of a buffer containing successive values of the single output parameter. This is discussed below in Multiple instances of output parameters on page 9. Passing output parameters using the output pointer Output parameters can be returned indirectly from the user function by reserving one of the input parameters to contain the address of the output parameter. In this case, the user functions must be defined as int and return an int return code to indicate whether or not the execution was successful. 8 Custom Servers

23 For example, in the following function call, the return_code indicates whether execution of the function was successful or not, and the value of the output parameter is stored in output: return_code = function_name(input1,input2,&output) A system-generated main() function expects the value of return_code to be 0 if execution is successful, or -1 if it failed. The output pointer variable can be the address of single parameters, multiple output parameters, or groups of single or multiple output parameters. For code examples see Functions 4, 5, 6, and 7 in Chapter 8, Example user function parameters, on page 311. Multiple instances of output parameters A user function can return multiple instances (an array) of the output parameters. In this case, you must allocate a buffer of contiguous memory. The buffer must be declared so that the data is persistent in the main function until the call to the CA_Put_DT_Parameters() subroutine. For example, you might return a list of names that match a search string: this would be multiple instances of one char parameter (for a code example see also Function 8 on page 321). To indicate the number of instances, the first four bytes of the buffer must be a long integer (for a code examples see Functions 9 and 10 in Chapter 8, Example user function parameters, on page 311) containing the number of instances being returned (the name count shown in Figure 3 and the order count shown in Figure 4 on page 10). To indicate that the user function can return multiple instances select the Return Type Multiple on the User Function window. The state table can issue ReceiveData once per instance of the output parameters, stopping at count times Name Count SMITH\0 JOHNSON\0 Figure 3. Multiple instances of one output parameter Chapter 1. Introduction 9

24 Order Count Long Integer Short Integer Long Integer Short Integer Order #1 Order #2 Figure 4. Multiple instances of more than one output parameter Passing output parameters back to the state table When you define a user function you can identify those output parameters that are to be ignored by the calling state table (see 11 on page 19). This does not affect the way the user function is written, but will determine which parameters are passed to the calling state table. In the state table, the ReceiveData action simply makes no mention of the ignored parameter. The initialization user function You may need a user function to perform program initialization tasks, for example when you need to initialize a link to a host computer. When defining a custom server, you can specify the name of an initialization user function only for system-generated main() functions. This function is linked with your other user functions and the main() function in the build process. 10 Custom Servers The custom server main() arguments argc (parameter count) and argv (a pointer to a list of parameters) are passed to the initialization user function. The initialization function accepts only these parameters and must return void as in the example below. The initialization user function is called automatically when the custom server is started, immediately following the CA_Init() subroutine. If you code the main() function yourself, code it in this way. The following shows an example of an initialization user function: extern FILE *file1_fp; extern FILE *file2_fp; void open_files(int argc, char *argv[]) { char fname1[100]; char fname2[100]; if (argc == 3) { strcpy(fname1,argv[1]); strcpy(fname2,argv[2]); } else { strcpy(fname1,"default1.dat"); strcpy(fname2,"default2.dat"); }

25 } if ((file1_fp = fopen(fname1,"w+")) == NULL) { CA_Terminate(0); } if ((file2_fp = fopen(fname2,"w+")) == NULL) { CA_Terminate(0); } When attaching to shared memory (for example, by using the AIX system call shmat()), you should never specify a specific address for the attach; always allow the system to select the address. Failure to do so may cause calls to the custom server API to fail. To define an initialization user function, see Defining the main() function on page 16. The termination user function You can define your own termination function to perform program termination tasks such as closing databases and disconnecting communication links in case of terminal processing errors. When you define a custom server, you can specify the name of a termination user function. This function is linked with your other user functions and the main() function in the build process. You can use a termination user function with a main() function you have written, or a system-generated one. The termination user function is called automatically when the system is shut down by the system administrator. The SIGINT signal is used to request a custom server to terminate gracefully. When a custom server calls the CA_Init() subroutine, a signal handler for the SIGINT signal is provided that calls the specified termination user function. When you terminate a custom server, a SIGINT signal is sent to the custom server, which, in turn, sets a terminate flag. Every time the custom server invokes one of the custom server subroutines, this flag is examined and, if it has been set, the termination user function is invoked and the custom server exits. If a user function includes a program loop that does not have any exit criteria, the loop must contain at least one custom server subroutine, otherwise the custom server will not terminate successfully. Note: 1. If you provide another signal handler for the SIGINT signal and activate it, it will override the one provided by WebSphere Voice Response, and graceful termination is your responsibility. Chapter 1. Introduction 11

26 2. You cannot use CA calls in a signal handler as they are not reentrant with respect to signals. For more information on which functions can be used in a signal handler, see the description of the sigaction() function in the AIX Base Operating System and Extensions Technical Reference book. An example of a termination user function: extern FILE *file1_fp; extern FILE *file2_fp; void close_files(void) { fclose(file1_fp); fclose(file2_fp); return; } Notes: 1. The termination function must return to the main() function which ends the custom server process after it has done its own clean up. Do not invoke the exit() subroutine from the termination function. 2. Also, don t call a custom server subroutine from the custom server termination function. If you do, you will get error code 161, CA_TERMINATING. 3. The termination function must return void, and have void parameters. To define a termination user function, see Defining the main() function on page 16. The open and close functions You can define open and close functions, which are special user functions, so that your custom server is notified when a state table performs an OpenHostServerLink action or a CloseHostServerLink action associated with that custom server. Define the names of your open and close functions on the custom server window. How to do this is included in the procedure in Defining the main() function on page 16. Your open and close functions must conform to the prototypes: void OpenFuncName (short link_id) void CloseFuncName (short link_id) These functions are allocated func_ids in the system-generated header file, customservername_hdr.h. As with initialization and termination functions, don t 12 Custom Servers

27 define open and close functions as user functions because they cannot be used for SendData actions in the state table. You can, however, call custom server routines from them. Messages specifying either of the func_ids appear on the message queue just like messages from a channel process or another custom server. Use CA_Receive_DT_Msg() and CA_Get_DT_Parameters() to handle these messages. There is no equivalent CA_Send_DT_Msg() or CA_Put_DT_Parameters(), because the functions return void. A system-generated main() includes code to handle these two functions, just like normal custom server user functions. If you don t define the name of the open function or the close function on the custom server window, your custom server will not receive notification of OpenHostServerLink or CloseHostServerLink actions. No error is logged. Custom servers built on releases of DirectTalk for AIX before Release 2 won t be notified. Note that the close event is received whether the link is closed explicitly using a CloseHostServerLink action, or implicitly by termination of the state table by CloseEverything. When an open or a close event is received, WebSphere Voice Response cleans up any pending requests that have been processed by CA_Get_DT_Parameters(). This ensures that internal buffers are freed, and that data pertaining to a previous call is not mistakenly delivered to a subsequent user of the same channel process. However, requests which have already been received but have not been processed by CA_Get_DT_Parameters() are not flushed. This is because the request may contain vital record data (for example, billing information) which must persist until the custom server has read it, regardless of whether the link has been closed subsequently. If the caller attempts to reply to such messages, their CA_Put_DT_Parameters() will fail with a CA_NO_MSG_RECV. If such messages are present when a subsequent open event specifying the same link_id is received, then an error (20018) is logged to warn of this situation. Chapter 1. Introduction 13

28 14 Custom Servers

29 Chapter 2. Developing a custom server This chapter describes the tasks you need to perform to create, build, debug, and install your custom server. It describes everything from writing the main() and user functions to putting your custom server into production on your WebSphere Voice Response system. The tasks are: v How to create a custom server (see page 15). v How to create the main() function by writing it yourself, or by having WebSphere Voice Response generate it (see page 16). v How to create user functions (see page 24). v How to use the supplied custom server subroutines (see page 25). v How to import files into your custom server directory (see page 25). v How to build your custom server (see page 26). v How to view the files generated by the build process (see page 28). v How to use the custom server debug utility to debug your custom server (see page 29). v How to trace your custom server (see page 30), and how to interpret the trace (see page 32). v How to edit a custom server definition (see page 34). v How to install a custom server, and how to deinstall it (see page 35). v How to put your custom server into production (see page 35). v How to shut down custom server processes (see page 41). v How to use custom servers on a single system image (see page 42). v How to change the AIX environment in which your custom server runs (see page 43). How to create a custom server To create a custom server you can either copy an existing custom server and modify it, or create a new one. To copy an existing custom server, you can either: v From the Welcome window, select Applications > Custom Servers v Click Server > Copy. You can also select multiple user functions to copy at the same time from one custom server to another. Copyright IBM Corp. 1991,

30 v Or, Open an existing custom server or user function and click Save As to copy the existing object under a new name. Note: When you copy a custom server, definitions and configuration information are copied, but the contents of the custom server s subdirectory are not copied. If your new custom server needs files that are in the existing server s directory, use the procedures described in Importing files into the custom server directory on page 25 to copy the files. To create a new custom server (or to modify existing custom servers), you need to be familiar with programming logic and C language or C++ language programming. You should also understand how a custom server interacts with host applications and voice applications. For general information about custom servers and custom server operation see the WebSphere Voice Response for AIX: Designing and Managing State Table Applications guide. Creating the main() function When you have defined your custom server requirements and developed your user functions (not mandatory if you plan to code the main() function yourself), you are ready to create the main() function. As discussed in The main() function on page 3, the main() function will be linked with your user functions to build the custom server. Whether you code the main() function yourself or use WebSphere Voice Response to generate it for you, you must first use the WebSphere Voice Response windows to specify the following information: v A name and description for the custom server (see Defining the main() function ) v Names, descriptions, and parameters of the user functions that interface directly with WebSphere Voice Response (see Defining user functions and parameters on page 18) v Required main() function properties (see Defining properties on page 19) If you are coding the main() function yourself, Completing the main() function on page 24 discusses the additional information that you need to provide. Defining the main() function Use the following procedure to specify a name and description for the main() function, and to provide the names of any initialization, termination, open, or close user functions: 1. From the Welcome window, select Applications >Custom Servers 16 Custom Servers

31 2. Create a new custom server: To create a new custom server click Server > New. The system displays the Custom Server window. Figure 5. Custom Server window. 3. Type a brief description of the custom server in the Server Description field. 4. Specify the custom server type. Next to main(), select System Generated if your custom server requirements can be satisfied by a WebSphere Voice Response-generated main() function, or select User Generated if you are going to code the main() function yourself. 5. Select main() language: Select the programming language used for the main() function. 6. Defining user functions: If you are providing a termination user function, select the Termination Function field and type the name of your termination user function. 7. If you are providing an initialization user function (applicable only to system-generated main() functions), select the Initialization Function field, and type the name of your initialization user function. 8. If you are providing an open function, select the Open Function field and type the name of your open function. Chapter 2. Developing a custom server 17

32 9. If you are providing a close function, select the Close Function field and type the name of your close function. 10. Save the definition, specifying a name for the custom server. 11. Close the Custom Server window. Defining user functions and parameters Use this procedure to specify the names and parameters of the user functions that interface directly with WebSphere Voice Response. Parameters must be specified in the order in which they appear in the parameter list of your user function. If you plan to code the main() function yourself, you may not have any user functions. If this is the case, skip the following procedure: 1. From the Welcome window, select Applications >Custom Servers 2. Select custom server: Select the custom server that requires the user function. 3. Click Function > New. You can also select and Copy existing functions, then Open the copied function. The system displays the User Function window with the custom server name in the Server Name field. Figure 6. User Function window. 18 Custom Servers

33 4. Type a description of the user function in the Function Description field. 5. If this function is compatible with the GetFindData state table action (a single character string for both input and output parameters), then click Yes under Compatible with GetFindData action? 6. Specify parameters: Click the button next to Single or Multiple to specify the output parameter type (see Output parameters on page 7). 7. Use the Definition windows to assist you in defining the parameters, click Options > Parameters. The system displays the Parameter Selection window with existing parameters listed under Parameters. 8. In the Parameter Selection window, click the button next to Input Parameters. To define new input parameters, select Add. The system displays the Input Parameters Definition window. 9. In the Input Parameters Definition window, select the required Data Type, then type required information in the Name and Length (if required) fields. Click OK. The Parameter Selection window displays the defined parameters. 10. In the Parameter Selection window, click the button next to Output Parameters. To define new output parameters, click Add at the bottom of the window. The system displays the Output Parameters Definition window. 11. In the Output Parameters Definition window, indicate whether the parameter is to be used by the calling state table by clicking Use or Ignore next to Use or Ignore Parameter. Click the required Data Type, then type required information in the Name and Length (if required) fields. Click OK. The Parameter Selection window displays the defined parameters. Output parameters that are defined to be ignored by the calling state table are preceded by a dash ( ). 12. Click OK. The User Function window displays the defined parameters. 13. Click the File menu to Validate the user function. If the user function definition is valid, the Validated field displays Yes. A custom server that includes this user function will not execute unless this field displays Yes. 14. Save the definition, specifying a name for the user function. 15. Close the User Function window. 16. More?: Repeat this procedure, starting with Step 3 on page 18, for all user functions to be defined. Defining properties Use this procedure to define the properties for a custom server. Depending on whether the main() function will be system-generated or coded by you, you use the WebSphere Voice Response windows to specify one of the following sets of properties: Chapter 2. Developing a custom server 19

34 System-generated main() main() arguments Compile flags Object files Link flags User-generated main() main() arguments Compile flags Object files Link flags Global declarations Include files 1. From the Welcome window, select Applications > Custom Servers 2. Open the custom server: Open the custom server for which you want to define main() function properties. The system displays the Custom Server window for the selected custom server. 3. Display Properties window: Click File > Properties. The system displays the Properties window (see Figure 7 on page 21). If you are creating a system-generated main() function, the window displays six panes; if you are coding the main() function yourself, the window displays four panes. 20 Custom Servers

35 Figure 7. Custom Server Properties window 4. In each pane of this window, type the appropriate information, as follows: main() args The main() arguments are the input parameters required by the main() function. The arguments you type in this window are passed to the custom server when it is started from the Custom Server Manager window. Chapter 2. Developing a custom server 21

36 When you specify arguments, do not insert a blank character between the flag and the data. For example, to use the -f flag with the data filename, specify it like this: -ffilename Compile Flags The compile flags provide the options for compiling the custom server during the build process. Syntax The compile flags are specified as described in the AIX Commands Reference. For example: -g (compiles with the debug option) -O (compiles with optimization) If you want WebSphere Voice Response to generate ANSI function prototypes for your user functions, set the flag -D DT_PROTO. This option, together with other appropriate options, is set automatically if you are using C++. To set the multiple process flag when your custom server has a system-generated main(), add the flag -DMULTI to the existing set of compile flags. Object Files The names of the object files are added to the Makefile during the build process. Object files need only be identified if they do not exist in a specified object library. If you code your own main() function, the name of the object file that contains the main() function must be included in the list. Syntax The object files are specified by their AIX path name. The.o file extension is required. For example: phonefunc.o set_path.o Note: The system-generated file customservername_ext.o is automatically included in this list. Do not use this name for an object file, as it will be overwritten by the system-generated file during the custom server build. Link Flags The link flags provide the options for linking the custom server during the build process, including the names of any required object libraries. 22 Custom Servers

37 Syntax The link flags are specified as described in the AIX Commands Reference (the cc command). For example: -lm -L/home/accounts/vae/mylib Global Declarations The global declarations are the global variables used by the main() function. In system-generated main() functions, specified global declarations are copied into the customservername_main.c above the Main() statement during the build process. Syntax The global declarations are specified using normal C language conventions. For example: #define MAXLEN 80 char filename[256]; Include Files Include files generally contain additional data pertinent to the application, such as information about constants and data structures. In system-generated main() functions, the names of specified include files are inserted in customservername_main.c above the Main() statement during the build process. Syntax Include files are specified by name, using normal C language conventions. For example: #include "myfile.h" #include <stdio.h> If you are using a combination of C and C++ language files, put the C language files in a subdirectory of the custom server directory to keep them separate from the C++ language files. If you export or import your custom server directories, any subdirectories will also be exported and imported. 1. Validate include statements: If you specify include files, click Validate to verify the syntax of include statements. The system displays an error message if the syntax is invalid. Refer to Include Files for syntax rules. 2. When you have finished entering values for all properties, click OK. The system checks for syntax and notifies you of any errors. If all property specifications are valid, the Properties window closes. 3. Save changes: Save the custom server. 4. Close the Custom Server window. Chapter 2. Developing a custom server 23

38 Completing the main() function If you are creating a system-generated main() function, you have defined all the required information at this point and you can proceed to Building a custom server on page 26. If you are coding the main() function yourself, the next step is to develop the main() function in C or C++ language. v You may need to include some or all of the following header files in your code: CA_header.h: a standard WebSphere Voice Response header file used during the build process by all main() functions that use any of the custom server subroutines. CA_access_db.h: a standard WebSphere Voice Response header file that contains constant and structure definitions for the custom server subroutines that use WebSphere Voice Response data. CA_errstring.h: a file containing text descriptions of the CA_errno values. CA_limits.h: a standard WebSphere Voice Response header file containing definitions of symbolic constants. This file is included by CA_header.h. actionedges.h: a list of possible return codes for each state table action. customservername_hdr.h: a header file generated by the system during the build process. The header files include the external declarations for the custom server subroutines, user functions, define statements, and other global declarations needed to build the custom server. v For descriptions of the WebSphere Voice Response custom server subroutines that you can use in your main() function see Chapter 5, Custom server subroutines, on page 75. Once your main() function is complete, use the instructions in Importing files into the custom server directory on page 25 to import any custom server data from tape, diskette, or a file in the AIX file system to WebSphere Voice Response before you build the custom server. Creating user functions If you have existing C or C++ language applications that perform the processes required by a custom server, you can use these as your user functions instead of writing new ones. If you need to create new user functions to satisfy your custom server requirements, code them as you would any C or C++ language program. 24 Custom Servers

39 Whether you use existing user functions or write new ones, they are linked with the custom server main() function during the build process. See Importing files into the custom server directory for information about transferring your C or C++ language user functions from the AIX file system on the pseries computer to WebSphere Voice Response. Importing files into the custom server directory All data that comprises a custom server (the main() and user functions and declarations) must reside in the WebSphere Voice Response custom server directory before you can build the custom server. The custom server directory is established by an environment variable set when the WebSphere Voice Response environment is defined. The directory is automatically created when you use the custom server Import facility described in Step 3 of the following procedure. Note: Take care not to import a file whose filename exceeds 100 characters, or a file whose path name would result in a directory with a complete path name exceeding 155 characters, because you will be unable to export such files or migrate them to a new release. Use the following procedure to import custom server data from tape, diskette, or a file in the AIX file system into the custom server directory: 1. From the Welcome window, select Applications > Custom Servers 2. Open custom server: Open the custom server that defines the data you want to import into the custom server directory. The system displays the Custom Server window. 3. Open custom server import window: Click Utilities > Import. The system displays the Custom Server Import window. The window displays the name of the custom server directory and prompts you to import the data using the appropriate AIX command. 4. Import from tape or diskette: To import from tape or diskette, insert the tape or diskette containing the files into the pseries computer diskette or tape drive. Then, in the Custom Server Import window, type the appropriate AIX command to copy the data. For example: tar -xvf /dev/fd0 and press Enter. The system copies the contents of the tape or diskette into the custom server directory. 5. Import from another directory: To import from another directory, type the appropriate copy command. For example: cp ~/csmain csmain Chapter 2. Developing a custom server 25

40 and press Enter. The system copies the specified files into the custom server directory. 6. To close the Custom Server Import window, type exit, then press Enter. 7. Close the Custom Server window. Importing custom servers When you import a custom server that was exported in the INSTALLED or AUTOEXEC state, it is restored in the same state on the target system. A custom server executable in the import file is installed without being rebuilt; if it doesn t install, it is rebuilt and installed. You must have the C or C++ compiler installed on the target system to rebuild the executable. The system-generated main() file (if any), the custom server header file and the custom server Makefile are regenerated. Note: You cannot import or uninstall a custom server if it is running; you must first stop the custom server. If the custom server is installed on a single system image, it must not be running on any node of the image. Building a custom server When all required custom server data resides in the custom server directory, you can initiate the build. The files generated during the build are based on information you type in the Figure 7 on page 21. The build process performs the following activities: v Generates the header file, customservername_hdr.h, which contains information needed to enable communication between a custom server and a state table. v Generates the file customservername_ext.c which is used to initialize required external variables. For C++ files, the name of the generated file is customservername_ext.c. v Generates the makefile, Makefile.customservername. v If specified, generates the main() function, which has a file name of customservername_main.c. v Compiles all necessary source (.c or.c) files. v Links all object files and object libraries to create the custom server executable module. v Produces a build report, customservername.rpt, that identifies related errors and activities. 26 Custom Servers

41 If the build was successful, you can optionally follow the steps in Viewing the generated files on page 28 to view the results of the build. Then, install the custom server as described in Installing and deinstalling a custom server on page 35. If the results of the build are not as expected, you can search the Build Report for errors (see Viewing the generated files on page 28). Make appropriate changes and rebuild the custom server. Note that you cannot debug a custom server if the build failed, because the executable module is not generated. By default, WebSphere Voice Response uses the C compiler to build the custom server. If you want WebSphere Voice Response to use the C++ compiler, select it on the radio button on the menu. You can mix.c and.c source files in the same custom server, but if you want to use a.c source file, make sure there is no corresponding.c source file, as this will be used in preference. Compile options for C language source files in the custom server properties window (see Figure 7 on page 21) are assigned to the CFLAGS macro, and the.c.o inference rule used to compile objects. For C++ language source files, the CCFLAGS macro and the.c.o inference rule are used. The custom server build process sets the -M compiler flag to produce dependency files. These.u files are used when generating the Makefile, and should be exported with the rest of the custom server files. If you have modified the default rules for your system, for example, by setting the MAKERULES environment variable, the results may be unpredictable. You can specify additional Makefile rules to be used when building the custom server. Put them in a file named makerules.name, where name is the name of your custom server, in the corresponding custom server subdirectory. When you build the custom server, these rules are automatically included in the Makefile. Use the following procedure to initiate the build process: 1. From the Welcome window, select Applications > Custom Servers 2. Open the custom server: Open the custom server that you want to build. The system displays the Custom Server window. 3. Start building it: To start the build click Utilities > Build. Inthe Confirm Request window, click OK. Chapter 2. Developing a custom server 27

42 When the build completes, the system displays an Information window to notify you whether or not the custom server was compiled and linked successfully. If the build completed successfully, the message verifies a successful build. If the build was not successful, the message refers you to the build report for the error listing. Figure 8. Build Report window 4. The build report : Click OK to close the status window. If the build was successful, the Status field on the Custom Server window displays Built. 5. Close the Custom Server window. Viewing the generated files When you have completed the build process, you might want to view each component that is generated for information or to check for errors. You can view the following output from the build process: v Build report v Makefile v System-generated header file v System-generated main() function 1. From the Welcome window, select Applications > Custom Servers 2. Open the custom server: Open the custom server for which you want to access the build output. The system displays the Custom Server window. 28 Custom Servers

43 3. Click Build Output, then the component that you want to view. The system displays a scrollable window, showing the selected component. Figure 9. Generated Header File window 4. Click Close to close the window when you have finished viewing the contents. Debugging a custom server If your custom server does not operate as expected, you can use the debug facility to identify the point of error. Using the AIX dbx debugger, you can step through each statement and observe the results of the execution of that line of code. You can also use custom server trace for debugging custom servers; this may be more suitable for debugging custom servers that are in production. See Tracing custom servers on page 30. To use the dbx debugger, you must specify -g as a compile (C flags) option when you define the main() function properties, as described in Defining properties on page 19. If you want to use another debugging tool, instead of dbx, edit the custom server debug script, CA_DEBUG which is located in $VAETOOLS. Change the line that initiates dbx to initiate your debugging tool. The printf C-library function can be useful for debugging. To avoid a delay caused by buffering, follow each printf with an fflush function. The output Chapter 2. Developing a custom server 29

44 of the printf function is sent to the DTstatus.out file. However, the results of the printf function can become merged with other data sent to DTstatus.out; to prevent this happening, use the setlinebuf function before your printf function to ensure that your data always starts printing on a new line. Note: You cannot run more than one custom server of the same name at a time. Therefore, if you have an earlier version of this custom server running in production status, you must stop it before you can debug your new version. Refer to the WebSphere Voice Response for AIX: Configuring the System guide for information about stopping the execution of a custom server. Use the following procedure to initiate the debug facility: 1. From the Welcome window, select Applications > Custom Servers 2. Open the custom server: Open the custom server that you want to debug. The system displays the Custom Server window. 3. Start debugging: To start the debug facility click Utilities > Debug. The system displays the Custom Server Debug window, running dbx. Figure 10. Custom Server Debug window 4. Step through your program: Step through each statement in the program, or run the program. You can do this by typing standard dbx commands (for example: stop in main, run, next) in the Custom Server Debug window (refer to the Commands Reference for information about dbx). The program executes and displays the activities and results as programmed. 5. Note any errors or unexpected results so that you can make required modifications. 6. When you have finished debugging the custom server, type quit at the (dbx) prompt. Tracing custom servers You can use custom server trace to debug problems, even when the custom server is in production. When AIX system tracing is turned on, WebSphere Voice Response traces entry and exit from all custom server library subroutine calls. You can use this 30 Custom Servers