WebSphere Voice Response for AIX with DirectTalk Technology. Fax using Brooktrout. Version 6.1 GC

Transcription

1 WebSphere Voice Response for AIX with DirectTalk Technology Fax using Brooktrout Version 6.1 GC

2

3 WebSphere Voice Response for AIX with DirectTalk Technology Fax using Brooktrout Version 6.1 GC

4 Note Before using this information and the product it supports, read the general information under Notices on page 73. 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 IBM Corporation 1996, US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

5 Contents Figures v Tables vii About this information ix Who should use this information..... ix Typographic conventions ix Accessibility x Notes on terminology xi Where to find more information..... xi Useful Web sites xi Making comments on this book..... xii Chapter 1. Introducing Brooktrout Fax... 1 What is fax? Planning for fax applications on WebSphere Voice Response Configuring WebSphere Voice Response to provide fax support Using fax in WebSphere Voice Response applications Brooktrout fax support in WebSphere Voice Response Chapter 2. Installing the Brooktrout Fax Card System requirements and prerequisites... 9 Installing the TR114 card Installing the TR1034 card Chapter 3. Installing the Brooktrout Fax Software Preparing to install Installing the Brooktrout fax feature The components of the Brooktrout fax feature 16 Chapter 4. Writing a Fax Application Fax-tone detection Adding fax-tone detection to a state table.. 20 State tables BFAX_SEND_FAX BFAX_RECV_FAX BFAX_CALL_BACK BFAX_LOG Chapter 5. Brooktrout Fax Interface Tool 33 Use of BFIT Chapter 6. Fax Queue Manipulation btq_list command btq_delete command Chapter 7. Troubleshooting TIFF file formats Logging Appendix A. The Fax Sample Application (FSA) How the fax sample application works Contents of the fax sample application import file How faxes are stored in the FSA FaxSample - the FSA state table FaxSample_CS - the FSA custom server Installing the fax sample application Starting the fax sample application Using the fax sample application System errors Modifying the fax sample application Appendix B. Error Messages Message content Fax error messages Example message <message number>: <message text> Error messages : ERROR: We have an error writing to the message Q, rc='number', errno='number' : FILE ACCESS ERROR ('reason') file: 'list-filename' : FILE ACCESS ERROR ('reason') file: 'filename' : FILE ACCESS ERROR - invalid filename specified 'filename' : FILE EXTENSION ERROR - unsupported extension on file: 'filename' : FILE EXTENSION ERROR - unsupported extension on file: 'filename'. 64 Copyright IBM Corp. 1996, 2011 iii

6 20503: FILE PARSING ERROR - unable to parse list file: 'list-filename' : FILE PARSING ERROR - unable to parse list file: 'filename' : LISTFILE ERROR - bad file detected in list, file: 'list-filename' : LISTFILE ERROR - bad file detected in list, file: 'filename' : Max transmission attempts failed for fax ''filename'' : SendFax : FILE ACCESS ERROR ('reason') file: 'filename' : SendFax : FILE EXTENSION ERROR - unsupported extension on file: 'filename' : Send Fax : FILE SIZE ERROR - file: 'filename' is zero bytes : SendFax: MEMORY ALLOCATION ERROR ('reason') file: 'filename' in listfile: 'filename' : SendFax : UNABLE TO CONVERT FILE: 'filename' : SendFax : UNABLE TO CONVERT FILE: 'filename' : SendFax : UNABLE TO CONVERT FILE: 'filename' : Unable to Close CHP Link 'link-id', CA_errno: 'string' ('number') : Unable to Close CHP Link 'link-id', CA_errno: 'string' ('number') : Unable to Execute StateTable 'state-table-name', CA_errno: 'string ('number') : Unable to Execute StateTable 'state-table-name', CA_errno: 'string' ('number') : Unable to Open CHP Link, CA_errno: 'string', 'number' : Unable to Open CHP Link, CA_errno: 'string', 'number' : Unable to open tiff file: 'filename' : Unable to open tiff file: 'filename' : Unable to read configuration data from ODM 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 112 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 115 Index iv Fax using Brooktrout

7 Figures 1. Possible configuration for fax support 5 2. Layout of the TR114 +P16S Card Layout of the TR1034 Card GUI version of the main window Plain-text version of the BFIT main window GUI version of the help window Plain-text version of the help window GUI version of the list window Plain-text version of the list window GUI version of the progress window Plain-text version of the progress window Message information in the WebSphere Voice Response error log Copyright IBM Corp. 1996, 2011 v

8 vi Fax using Brooktrout

9 Tables 1. Field names and descriptions in the BFIT main window FaxSample_CS input and output parameters Error codes reported by voice messages Error codes, types and descriptions 59 Copyright IBM Corp. 1996, 2011 vii

10 viii Fax using Brooktrout

11 About this information This book is an overview of the Brooktrout fax support implemented in IBM WebSphere Voice Response for AIX with DirectTalk Technology, which provides fax capability and enables customers to develop fax applications within the WebSphere Voice Response product. Throughout this book, we refer to the IBM WebSphere Voice Response for AIX voice processing system as WebSphere Voice Response, and the Brooktrout fax feature as Brooktrout fax. This book should help you to install the Brooktrout fax card, build your own custom fax applications and provide system administration support. Who should use this information This book is for application programmers with some knowledge of WebSphere Voice Response for AIX, AIX, and pseries computer hardware. You should also know how to use WebSphere Voice Response state tables and custom servers. If you are a newcomer to WebSphere Voice Response and the Brooktrout fax feature, you should familiarize yourself with Chapter 1, Introducing Brooktrout Fax, on page 1, before beginning the installation and configuration process. To use this book successfully we recommend that you use it in conjunction with WebSphere Voice Response for AIX: Designing and Managing State Table Applications, WebSphere Voice Response for AIX: Application Development using State Tables, and WebSphere Voice Response for AIX: Custom Servers. 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. Copyright IBM Corp. 1996, 2011 ix

12 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 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 book. 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 see List of WebSphere Voice Response and associated documentation on page 111). x Fax using Brooktrout

13 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 p5 and 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 publications and where you can obtain them is shown in List of WebSphere Voice Response and associated documentation on page 111. Useful Web sites The following Web sites are useful sources of information about WebSphere Voice Response and related products: WebSphere Voice Response 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 About this information xi

14 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. xii Fax using Brooktrout

15 Chapter 1. Introducing Brooktrout Fax The transmission of facsimile (fax) documents across the public switched telephone network is well established as a popular means of business communication. The addition of fax support can significantly enhance the functions of existing WebSphere Voice Response applications. It can also allow several new application possibilities. This chapter provides some background information about fax, how it is supported in WebSphere Voice Response, how to plan for fax applications, and how to configure the system to include them. A fax sample application is supplied with WebSphere Voice Response to show you how fax can be integrated with WebSphere Voice Response. This has to be installed and imported into WebSphere Voice Response, and it comes with its own documentation in a file contained in the import file. For more information see, Appendix A, The Fax Sample Application (FSA), on page 51. WebSphere Voice Response has fax functionality incorporated into the base product. Previously, the fax capability in WebSphere Voice Response was provided by the Brooktrout fax feature within the unified messaging application, IBM Unified Messaging. The Brooktrout fax feature was first introduced in Unified Messaging Version 6.3 and Version 6.4. Unified Messaging is now provided without fax support and instead uses the fax support supplied with WebSphere Voice Response. The previous Unified Messaging fax functionality was designed for use with Unified Messaging only. The purpose of the fax feature in WebSphere Voice Response is to provide a basis upon which application programmers can build their own custom fax applications. Examples of such applications might include 'fax on demand', where there exists a database of files for each of a range of products, or for faxing messages which have been received in the form of s. If you have the version of Brooktrout fax supplied with Unified Messaging installed at any time, you must complete the following tasks, in order, before attempting to use Brooktrout fax with Unified Messaging or WebSphere Voice Response: 1. Apply the latest PTF for Unified Messaging Version Install WebSphere Voice Response Version 4.2 (if you have not already done so). 3. Execute the migrate_btfax.sh script supplied with the latest PTF for Unified Messaging Version 6.4. Copyright IBM Corp. 1996,

16 Brooktrout fax uses either the Brooktrout TR1034 digital fax card for PCI or the redundant Brooktrout TR114+P16S digital fax card for PCI. The TR114+P16S provides 16 independent fax channels through an SCbus interface. A maximum of three TR114+P16S fax cards, providing up to 48 channels of fax, may be installed in any one machine. The supported TR1034 series cards provide independent fax channels through an H100 interface. A maximum of one TR1034 fax card can be installed in any one machine. The supported TR1034 cards are as follows: v TR1034+P4H-E1-1N-R providing 4 fax channels v TR1034+P16H-E1-1N-R providing 16 fax channels v TR1034+P30H-E1-1N-R providing 30 fax channels The Brooktrout TR1034 and TR114+P16S are not supported when both installed in the same machine. What is fax? The main reason for the success of fax is the standardization of fax machine communication by the ITU-T. The ITU-T have published standards for four types of fax machine. These are known as Groups 1, 2, 3, and 4. Groups 1 and 2 are now considered to be obsolete. Almost all fax machines in use today are ITU-T standard Group 3. Group 4 is intended for all-digital transmission and, although Group 4 machines are available, their usage is limited to ISDN networks. The Brooktrout fax card uses Group 3 standard to send image data (a picture of the page being sent) using: v Sampling of the image into a matrix of dots (pixels), each pixel being either on or off. The standard resolution for faxes is about 204 dots per inch horizontally and about 98 dots per inch vertically, giving about 20,000 dots per square inch. v Compression of the zeros and ones representing the image by a factor of around 15 using a run-length technique This means that rather than sending each dot separately, a code is sent representing the number of zeros and ones that occur together. v The resulting data (a stream of zeros and ones representing the compressed image) is sent down the telephone wire using a technique identical to that which is used by modems to send computer data. Before and after sending the image data itself, the two fax machines communicate with each other in order to exchange information such as the resolution of the image and their respective Station IDs. They also go through 2 Fax using Brooktrout

17 a training sequence in order to determine what speed of data transfer can be supported on a particular telephone line. Planning for fax applications on WebSphere Voice Response The questions you must consider when designing a fax application based on WebSphere Voice Response are listed here. v What is my fax application? Define the interactions between the voice and fax parts of the application. v Do I need inbound support, outbound support or both? See Inbound routing for more information. v How do inbound faxes get routed to the right user? See Inbound routing for more information. v Do I need one-call or two-call fax support? See One-call and two-call fax modes on page 4 for more information. v How many lines do I need? Calculate this from the average length of your faxes and the expected number of faxes per hour to be transmitted or received. v Do I have spare processor capacity, disk and RAM storage available to run fax on the pseries computer? You may need to upgrade to a more powerful member of the pseries family. Inbound routing The question of inbound routing is probably one of the most difficult issues associated with fax processing by computer. For shared fax machines, the standard approach is to print all received faxes and then to route them manually. The possibilities for doing this when the fax machine is replaced by a computer and fax system are: v Use direct inward dialing (DID) to give each user a different fax number. All the numbers are routed into one or more inbound lines, the actual number dialed being communicated to the fax machine when the call is answered. v Use DTMF-tone routing. Between the time when the call is answered and the Start button is pressed on the remote fax machine, the caller will enter a sequence of DTMF keys which may be the local telephone number or extension of the desired recipient of the fax. Which inbound routing method you use depends upon how your fax application has been designed. However, WebSphere Voice Response can be used as a front-end to route inbound fax calls by any method the call being transferred to a fax line. It is even possible to offer very sophisticated routing Chapter 1. Introducing Brooktrout Fax 3

18 capabilities using WebSphere Voice Response voice recognition to select a recipient for an inbound fax. However, this requires support for the one-call fax mode described below. One-call and two-call fax modes Fax integrated with a voice application can operate in one of two modes: one-call and two-call. One-call fax is a mode of operation where the initial telephony operation (the caller interacting with a voice application) and the actual fax data transfer occur in the same telephone call. In this mode of operation, the caller pays for both parts of the call. Two-call fax is a mode of operation in which the initial telephony and fax transfer parts of the call occur in two separate telephone calls: the caller hangs up after the initial telephony interaction and the fax data is transferred in a second call initiated by the called party. Configuring WebSphere Voice Response to provide fax support To facilitate fax support, WebSphere Voice Response provides a state table interface to a custom server, which uses a Brooktrout fax card. All these components, which make up the fax system, reside on the same physical pseries computer. The powerful application programming features of WebSphere Voice Response and AIX enable you to implement a wide range of fax applications on WebSphere Voice Response. WebSphere Voice Response provides an open system approach to fax support, making it easy to implement any fax application. To help you in the design and implementation of your fax applications, there is a sample fax application that implements a simple yet powerful personal fax filing system. Full sample source and documentation are supplied (see Appendix A, The Fax Sample Application (FSA), on page 51). Since WebSphere Voice Response and the fax server application must both be run in the same pseries computer, you will have a configuration similar to the following: v WebSphere Voice Response software installed on the pseries computer v Digital Trunk Telephony Adapter (DTTA) v The BrooktroutFax custom server v Brooktrout fax cards and associated drivers 4 Fax using Brooktrout

19 Telephone Network Voice Processing WebSphere Voice Response State Tables BrooktroutFax Custom Server Data Communications Network LAN Information (including stored faxes) Fax Machine DTTA pseries Brooktrout Brooktrout fax fax card card Local Information (including stored faxes) Figure 1. Possible configuration for fax support Using fax in WebSphere Voice Response applications In much the same way that almost every voice application on WebSphere Voice Response is different, it is likely that each new fax application will have a different set of requirements. Some of the differences between fax applications and possible ways in which fax could be used in voice applications are described here. Some of the differences between fax applications are: v The type of application, such as fax-on-demand or fax store-and-forward. v The source of information for the fax: from a local database, a networked database, or from a source such as a CICS system, for example. v The formatting of data on the fax: will the fax have letterheads, image and graphics as well as text? v The structure of the application: how processing is split between a state table and custom server(s). Chapter 1. Introducing Brooktrout Fax 5

20 v The interface between the state table and custom server(s). Some ways in which fax could be used in voice applications are: v Fax-on-demand. An application where a caller rings into WebSphere Voice Response and makes a request for information to be faxed back to a remote fax machine. It is possible to categorize the information for the fax into three distinct groups: Static. Information such as sales brochures and forms, which very rarely change and can be held in a static database. Dynamic. Information such as weather forecasts, stock prices, and news, which change regularly during the day. Reactive. Information such as bank statements and transport timetables, which are generated specifically as a result of a customer request. v Fax depository. An application which allows a caller to send faxes into WebSphere Voice Response which are then stored in a database for later static fax-on-demand requests. v Fax store-and-forward. An application in which a fax is temporarily stored if all fax machines are busy. This allows the fax to be accepted and then printed at a later point when a fax machine becomes available. v Fax mail. The equivalent of voice mail and electronic-mail, but for fax. This can provide user mailboxes for fax documents. How a typical fax application might work WebSphere Voice Response provides base fax functionality to allow application programmers to build their own custom fax applications. The fax interface is accessed via two state tables one for sending faxes and one for receiving them. This means that you must create, or modify an application such as a custom server or another state table, in order to use the Brooktrout fax functions, via the two state tables. For an example of such an application see Appendix A, The Fax Sample Application (FSA), on page 51 Brooktrout fax support in WebSphere Voice Response The functions of the Brooktrout fax feature are listed here: v A state table interface for sending and receiving faxes. v A fax-queueing mechanism to allow outgoing faxes to be queued and sent after a specified time delay (Two-call functionality) v Utilities for viewing the contents of the fax queue and for manipulating the fax queue. v Faxing of single, named TIFF files. v Faxing of single, named text files. 6 Fax using Brooktrout

21 v Ability to fax lists of files. These files can be TIFF or text or a mixture of the two types. v Headers and Footers (Value Added Text). Note: Headers and Footers are set on a system-wide basis using the BFIT tool (see Chapter 5, Brooktrout Fax Interface Tool, on page 33). They cannot be changed from a state table. Chapter 1. Introducing Brooktrout Fax 7

22 8 Fax using Brooktrout

23 Chapter 2. Installing the Brooktrout Fax Card This chapter explains how to install the Brooktrout fax card. System requirements and prerequisites To use the Brooktrout fax feature you require: v A PCI-based pseries (a Micro Channel RS/6000 cannot be used with this feature) v WebSphere Voice Response Version 6.1 v The following adapter configuration: A Brooktrout fax card TR1034 and a H.100 connector (4-way connector feature code: 2877, 8-way connector feature code: 4353) A Digital Trunk Telephony Adapter (DTTA) installed in the system unit, and connected directly to the telephony network. This is the only telephony adapter supported for use with this fax card. Full details on both the power and environmental requirements for the TR114 Brooktrout fax card are provided in the Brooktrout Technology: TR114 PCI Digital Hardware Guide. Similar details for the TR1034 Brooktrout fax card are provided in the Brooktrout Technology: Installing the TR1034 Digital PCI Board. Installing the TR114 card How to install the TR114 card. 1. Turn off the computer. 2. Remove the bracket from a vacant PCI slot. 3. Remove the PEB resistor bank from the TR114 card (see Figure 2 on page 10) 4. Insert the TR114 firmly into the slot while holding the card at each top corner. 5. Screw the TR114 card's mounting bracket to the computer's frame. 6. Connect the SCbus interface by locating the 26-pin SCbus connector on the TR114 card (see Figure 2 on page 10) and inserting the cable. Note: Cable length should not exceed 21"; maximum number of SCbus connectors is 21; distance between connectors should not be less than 1.0". 7. Turn on the computer. Copyright IBM Corp. 1996,

24 8. Check that all the LEDs come on at once, stay on momentarily and then go off in pairs. Once the computer has booted up, the LEDs should appear to flash at random. SCbus Connector Channel Status LEDs ID Switches (On back of board) PEB Resistors PCI Bus Connector Figure 2. Layout of the TR114 +P16S Card The SCbus will operate in SCSA mode and the PEB resistor bank should therefore be removed from the card. For further information on card settings see Brooktrout Technology: TR114 PCI Digital Hardware Guide Warning Electrostatic Discharge (ESD) can cause immediate or latent damage to Integrated Circuits. In order to minimize ESD you should wear an antistatic wrist strap whose lead has been clipped onto the metal chassis of the computer or, at the very least, touch the computer's chassis before you handle the fax card, in order to discharge any static electricity you may be carrying. Installing the TR1034 card How to install the TR1034 card. Before you begin: Before installing the TR1034 card into a pseries computer, the TR1034 card firmware must be at version 1.4.1B9. If the firmware is not at this level, you must flash the firmware to version 1.4.1B9. To do this, install the TR1034 card into a PC running Windows XP, and use the Brooktrout utilities to update the firmware as described in the Flashing ROM and Downloading Firmware chapter of the TR1000 Series Software Installation, Configuration, and User's Guide. 1. Turn off the computer. 10 Fax using Brooktrout

25 2. Remove the bracket from a vacant PCI slot. 3. Insert the TR1034 firmly into the slot while holding the card at each top corner. 4. Screw the TR1034 card's mounting bracket to the computer's frame 5. Connect the H100 interface 6. Turn on the computer. Rotary Switch T1/E1 Connector T1/E1 Status LED Board Status LED H.100 Termination Switch H.100 Connector PCI Bus Connector Figure 3. Layout of the TR1034 Card For further information on card settings see Brooktrout Technology: Installing the TR1034 Digital PCI Board. Warning Electrostatic Discharge (ESD) can cause immediate or latent damage to Integrated Circuits. In order to minimize ESD you should wear an antistatic wrist strap whose lead has been clipped onto the metal chassis of the computer or, at the very least, touch the computer's chassis before you handle the fax card, in order to discharge any static electricity you may be carrying. Chapter 2. Installing the Brooktrout Fax Card 11

26 12 Fax using Brooktrout

27 Chapter 3. Installing the Brooktrout Fax Software This chapter tells you how to install the Brooktrout fax feature and describes the components that make up the feature. It contains the following sections: v Preparing to install below v Installing the Brooktrout fax feature below v The components of the Brooktrout fax feature on page 16 v Restrictions on page 16 v Testing the TR114 card on page 17, if installed. v Testing the TR1034 card on page 18, if installed. Preparing to install Before you start installing the software: v Ensure that your WebSphere Voice Response system is installed and that it operates correctly. For information on how to do this, see the WebSphere Voice Response for AIX: Installation book. v Ensure that you have enough disk space for the components you are installing, in addition to the disk space required for the feature software; use the procedure described in Planning to install WebSphere Voice Response in the WebSphere Voice Response for AIX: General Information and Planning book. Installing the Brooktrout fax feature The Brooktrout fax feature is supplied as installp images which you install using the smitty command of the System Management Interface Tool (SMIT). You will need to refer to the Installing the WebSphere Voice Response Software procedure in the WebSphere Voice Response for AIX: Installation book. When you have installed the Brooktrout fax feature, import the custom server and state tables. To install the Brooktrout fax feature you will need to take the following steps: 1. Shut down WebSphere Voice Response: Shut down WebSphere Voice Response and log in as root 2. Install the feature: Follow the instructions in Installing the WebSphere Voice Response software in the WebSphere Voice Response for AIX: Copyright IBM Corp. 1996,

28 Installation book to use the System Management Interface Tool (SMIT) to install the dirtalk.brooktroutfax and devices.dirtalk.brooktroutfax file sets. 3. Reboot : Reboot the computer 4. Test: For a TR114 installation, see Testing the TR114 card on page For a TR1034 installation, see Testing the TR1034 card on page Start: Start WebSphere Voice Response and log in to the user account you use for the WebSphere Voice Response administration 7. Import the BrooktroutFax custom server and state tables: From the WebSphere Voice Response Welcome window, select Applications > Applications to open the Applications window. Then select Application > Import > Replace > File to import /usr/lpp/dirtalk/sw/fax/brooktroutfax.imp The BrooktroutFax custom server and the state tables are imported into the BrooktroutFax application. When the import is complete, select View > Refresh Now to see the imported objects. For more information about using the Application windows, see the WebSphere Voice Response for AIX: Designing and Managing State Table Applications book. 8. Starting the custom server: To start the BrooktroutFax custom server, from the WebSphere Voice Response Welcome window: a. Select Operations > Custom Server Manager. b. Select the Run Status of BrooktroutFax. c. Select Start. The Run Status changes to Waiting. A process ID (PID) is filled in. 9. Start the appropriate custom server for the installed card. For the TR114 fax card, start the BTFAX_100 custom server. To do this, from the WebSphere Voice Response Welcome window: : a. Select Operations > Custom Server Manager. b. Select the Run Status of BTFAX_100. c. Select Start. The Run Status changes to Waiting. A process ID (PID) is filled in. For the TR1034 fax card, start the BTFAX_1000 custom server. To do this, from the WebSphere Voice Response Welcome window: : a. Select Operations > Custom Server Manager. b. Select the Run Status of BTFAX_1000. c. Select Start. The Run Status changes to Waiting. A process ID (PID) is filled in. 14 Fax using Brooktrout

29 10. Disabling the custom servers from starting automaticallythe BrooktroutFax custom server is set to start automatically whenever the system is restarted. To stop this happening: a. Select Operations > Custom Server Manager. b. Select the IPL Status of BrooktroutFax. c. Select Auto-Start Off. 11. The BTFAX_100 custom server is set to start automatically whenever the system is restarted. To stop this happening: a. Select Operations > Custom Server Manager. b. Select the IPL Status of BTFAX_100. c. Select Auto-Start Off. 12. The BTFAX_1000 custom server is set to start automatically whenever the system is restarted. To stop this happening: a. Select Operations > Custom Server Manager. b. Select the IPL Status of BTFAX_1000. c. Select Auto-Start Off. When the Brooktrout fax card is installed you will be able to use the Brooktrout fax feature. Use the sample application to check that the Brooktrout fax feature is operating correctly. For information on how to do this, see Appendix A, The Fax Sample Application (FSA), on page 51. Hang-up detection Note that for fax to function correctly, the Hang-up detection criterion for the fax channels in WebSphere Voice Response must be set to Off. For information on how to do this see WebSphere Voice Response for AIX: Configuring the System Single system image If you are intending to use Brooktrout fax on more than one node in a single system image (SSI) you must ensure that the directories used by the Brooktrout fax custom server to store received fax files and to hold the fax requests to be sent to fax machines are local to each machine and not shared. These directories are called Fax Reception Directory and Fax Queue Location and are set using the BFIT tool. Chapter 3. Installing the Brooktrout Fax Software 15

30 The components of the Brooktrout fax feature The installp image is named dirtalk.brooktroutfax.it contains two import files. The first, /usr/lpp/dirtalk/sw/fax/brooktroutfax.imp which includes: v A state table interface which takes the form of two state tables using the custom server, one for sending and one for receiving faxes. Both one-call and two-call fax transmission are supported, as well as fax reception. Faxes can be sent immediately, or queued for future transmission after a set minimum time delay. The state tables are listed and described in Chapter 4, Writing a Fax Application, on page 19. v The BrooktroutFax custom server interfaces to the BTFAX_100 and BTFAX_1000 custom servers. The custom server provides functions to state tables to send and receive faxes. It requires no adjustments or further configuration. v The BTFAX_100 custom server which uses the TR114 fax card. v The BTFAX_1000 custom server which uses the TR1034 fax card. The second, /usr/lpp/dirtalk/sw/fax/faxsample.imp which includes v A sample fax application, comprising a state table and custom server described in Appendix A, The Fax Sample Application (FSA), on page 51. Restrictions The BrooktroutFax custom server is responsible for: v Using the Brooktrout fax API for sending and receiving faxes. v Supporting both one-call and two-call fax transmission. The user has no direct access to the Brooktrout API. Its functions are accessible only via the BrooktroutFax custom server. The BrooktroutFax custom server is accessible via the supplied Brooktrout fax state tables only. Note: To ensure system integrity, direct access to the Brooktrout fax API should not be attempted. 16 Fax using Brooktrout

31 Testing the TR114 card Note: This is only applicable for the TR114 and not the TR1034 To check if the device drivers are properly installed, at the AIX command line, type: lsdev -C grep fax which should show you: bfax0 Available xxxxx N/A bfax1 Available xxxxx N/A. (There will be one line for each card which has been installed, up to a maximum of three.) Also type: ls /dev grep fax which should show you: fax0 fax1. fax47 faxctl There are 48 fax(n) values, one for each potential channel or line. If one fax card is installed the first 16 (fax0 fax15) will be usable. For two and three cards it will be 32 (fax0 fax31) and 48 (fax0 fax47) respectively. There is only ever one faxctl device. The faxinit utility program lists, identifies and initializes each channel in the system. The device driver must be installed before attempting to run faxinit. It must be run after each reboot (this is usually done automatically as the device driver installation process inserts an appropriate entry into the file /etc/inittab). However, faxinit may also be run to check that the device drivers are correctly communicating with the fax card(s). At the system prompt, type: /etc/faxinit Data similar to that below should be displayed on the console (for two cards) PCI TR114 port BFF800, IRQ 2, 16 chans, Bus 0, Dev 16, Fn 0, Switch 0. PCI TR114 port BFFC00, IRQ 1, 16 chans, Bus 0, Dev 16, Fn 0, Switch 0. fax0 bff804 TR114+ fax1 bff808 TR114+ fax2 bff80c TR114+ fax3 bff810 TR114+ fax4 bff814 TR114+ fax5 bff818 TR114+ Chapter 3. Installing the Brooktrout Fax Software 17

32 fax6 bff81c TR114+ fax7 bff820 TR114+ fax8 bff82c TR114+ fax9 bff830 TR114+ fax10 bff834 TR114+ fax11 bff838 TR114+ fax12 bff83c TR114+ fax13 bff840 TR114+ fax14 bff844 TR114+ fax15 bff848 TR114+ fax16 bffc04 TR114+ fax17 bffc08 TR114+ fax18 bffc0c TR114+ fax19 bffc10 TR114+ fax20 bffc14 TR114+ fax21 bffc18 TR114+ fax22 bffc1c TR114+ fax23 bffc20 TR114+ fax24 bffc2c TR114+ fax25 bffc30 TR114+ fax26 bffc34 TR114+ fax27 bffc38 TR114+ fax28 bffc3c TR114+ fax29 bffc40 TR114+ fax30 bffc44 TR114+ fax31 bffc48 TR114+ Total channels: 32 TR114; 0 TruFax; 0 TR112/TR111MC; 0 TR200 No BRI TR114s found. Three columns of information are generated. These are channel number, channel address and card type. The first channel address is the base address +4, and each subsequent channel address is the previous address +4. If you have one fax card installed, the highest fax(n) value displayed should be fax15 and if you have three cards it should be fax47. Note: When running faxinit, be sure that there is no application running on any channels and that no channels are attached: otherwise, fax operations in progress could be aborted. Testing the TR1034 card Note: This is only applicable for the TR1034 and not the TR114. To check if the device drivers are properly installed, at the AIX command line, type: lsdev -C grep bost which should show you: bostfax0 Available xxxxx N/A 18 Fax using Brooktrout

33 Chapter 4. Writing a Fax Application Brooktrout fax supports the sending of ASCII text files, standard TIFF files, a list of ASCII and TIFF files. (PCX files can be converted to TIFF files.) If the user has specified an appropriate conversion utility in the PCX to TIFF configuration parameter (see Chapter 5, Brooktrout Fax Interface Tool, on page 33 for details of how to do this), PCX files can also be handled. Filenames of such files must have the extension.pcx. If an attempt is made to send any other type of file, an error will be reported and the file will not be sent. The processing that occurs when you send a fax depends on the type of file being sent. See tif - tag image format, txt - ASCII and lst - ListFile for descriptions of each of the file types and its appropriate processing. Fax-tone detection The tones generated by fax machines can be detected during a voice application. If fax-tone detection is activated and tones are detected, they will stop the following actions: v PlayAudioName v PlayPrompt (when Force Play is not selected) v PlayUserGreeting v PlayVoiceFromHost (when Force Play is not selected) v PlayVoiceMessage v PlayVoiceSegment To set fax-tone detection on, use the System : Fax detection system variable (SV227). The value of SV227 must be 1 to detect inbound fax tones, 2 to detect outbound fax tones, or 3 to detect both. No distinction is made between the different tones generated by fax machines. Merely the occurrence of a tone is recognized. When a tone is detected during one of the actions listed, the action terminates with a Success result and the System : Action additional information system variable (SV180) indicates that a fax tone was detected during the action. Copyright IBM Corp. 1996,

34 Adding fax-tone detection to a state table If you want to detect fax tones for inbound calls in a state table, for example the WELCOME state table, do the following: 1. Before the AnswerCall action use the AssignData action to set the System : Fax detection system variable (SV227) to 3, to set up both-way fax detection. 2. After the AnswerCall action, use the PlayPrompt action to play a prompt that lasts for at least 7 seconds to ensure that the application can receive at least one fax tone. This prompt should be interruptible, that is, it should not be force played. 3. When the PlayPrompt action returns succeeded or nothing played check the System : Action additional information system variable (SV180). If SV180 is set to 3 (stopped by fax) then a fax tone has been detected and you can transfer the call to a fax machine, invoke the BFAX_RECV_FAX state table or hang up. For outbound calls: 1. Use the AssignData action to set the System : Fax detection system variable (SV227) to 3, for both-way fax detection. 2. Use the MakeCall action to set up the call. 3. Use the PlayPrompt action to play a prompt for at least 7 seconds. 4. When the PlayPrompt action returns succeeded or nothing played check the System : Action additional information system variable (SV180). If SV180 is set to 3 (stopped by fax) then a fax tone has been detected and you can send a fax. Use only the PlayPrompt action to detect fax tones at the beginning of a call, because most other play and record actions flush any input as part of their normal operation. If you want to turn off fax-tone detection for the remainder of a call, set SV227 to 0. Using the state table debugger with fax-tone detection When you use the State Table Debugger an AnswerCall action is converted to a MakeCall action by the debugger so an AnswerCall in your state table will be seen by your telephone or fax machine as an outbound call from WebSphere Voice Response, and the tone it generates will be the detect outbound tone, not the detect inbound tone. So, when you are using the State Table Debugger, set SV227 to the inverse of what it will be in normal operation, or set it to 3 for both-way detection. 20 Fax using Brooktrout

35 State tables This section describes the state tables used by Brooktrout fax: v BFAX_SEND_FAX v BFAX_RECV_FAX on page 27 v BFAX_CALL_BACK on page 30 v BFAX_LOG on page 32 Note: Only the BFAX_CALL_BACK and BFAX_LOG state tables are user-modifiable. BFAX_SEND_FAX and BFAX_RECV_FAX provide the only way to access the Brooktrout fax functions, and must not be altered. BFAX_SEND_FAX Purpose This state table provides the interface to the Brooktrout functionality in WebSphere Voice Response for sending a fax. There are two ways that a fax can be sent: v On the same call (one-call fax) v Queued to be sent after a specified time delay (two-call fax) BFAX_SEND_FAX will determine which method is being used by the callback_st parameter. If callback_st is empty, the fax will be sent on the same call. If, however, callback_st contains a state table name the fax will be queued, and when the fax is actually sent (during a second call) the specified state table will be invoked in order to log the status of the fax-send operation. ASCII syntax InvokeStateTable ("DIRECT", BFAX_SEND_FAX, begin, filename, profile_id, callback_st, curlistfile, calling_number, called_number, device_rc, device_state); Entry Point The entry point for this state table is begin Parameters filename (STRING) Full path and file name of the file containing the fax image or file containing a file-list (that is, names of fax image or text files). The file permission must be set so that the file is readable by all users. The file extension determines the file type. Supported extensions are: tif - tag image format Chapter 4. Writing a Fax Application 21

36 When a single.tif file is processed an initial check is made to see whether the file exists and can be read. If it cannot, an error is reported; otherwise, the.tif file is sent using the Brooktrout API. If a problem is detected while the fax is being sent, an error is reported. TIFF files have been categorized into Classes to reduce the information burden on TIFF readers and writers that want to support narrow applications. TIFF Class F file format defines a file format that is simultaneously suitable for native use in Group 3 computer facsimile products and for use as a file-interchange medium with the outside world. Greater details concerning TIFF Classes, in particular TIFF Class F file format, are available in a Brooktrout Technology Technical White Paper and can be found at the Brooktrout Web site by going to txt - ASCII When a single.txt file is processed, an initial check is made to see whether the file exists and can be read. If it cannot, an error is reported; otherwise, a temporary.tif file name is generated and the.txt file is then converted to a.tif file. If there is an entry in the Text2TifConversion field in the BFIT screen then this script or utility will be used to carry out the conversion; otherwise, the one supplied by the Brooktrout API will be used. The conversion utility must adhere to the following command syntax: <text-tiff-utility-name> <filename.txt> <filename.tif> The.tif file is then sent using the Brooktrout API. If a problem is detected while the fax is being sent, an error is reported. pcx - PCX Provided that the user can supply a utility to convert files from PCX to TIFF-F format, the fax feature is able to handle PCX files for transmission. The full path and file name of the utility must be specified in the PCX to TIFF conversion configuration parameter (for information on how to do this see Chapter 5, Brooktrout Fax Interface Tool, on page 33). The conversion utility must adhere to the following command syntax: <pcx-tiff-utility-name> <filename.pcx> <filename.tif> Note that the PCX files themselves must have.pcx as their file extension. lst - ListFile 22 Fax using Brooktrout

37 When a.lst file is processed, an initial check is made to see whether the file exists and can be read. If it cannot, an error is reported; otherwise, the file is opened and each line of the file is read and checked. The checks are to ensure that the file specified by the line exists, can be read, and has a supported file extension (that is.tif,.txt and.pcx, but a list file within a list is not supported). If any of the files do not exist, an error is reported and the whole job is abandoned (even good files are not transmitted in this case). The list file is then processed, by creating an array of.tif files to be sent. For each file in the list, if it is a.tif file then the file name is just added to the array. If it is a.txt file then a temporary.tif file name is created and added to the array and the.txt file is converted (in accordance with the method specified above for a single.txt file). If the file cannot be converted, an error is reported and the transmission of the list is terminated. Once all the lines in the list file have been read and added to the array, the entire array (of.tif files) is sent using the Brooktrout API. If a problem is detected while sending the fax, an error is reported. At this point any temporary.tif files are then deleted. profile_id (STRING) This is the WebSphere Voice Response profile that is sending the fax (usually set to SV20). This is optional and is used only for logging purposes. callback_st (STRING) This is the name of the state table to be invoked after the fax is sent from the queue. If this is empty, the fax will be sent on the same call. See the section BFAX_CALL_BACK on page 30 for details of the BFAX_CALL_BACK state table. curlistfile (STRING) This parameter is reserved for future use. Set it to be an empty string. calling_number (STRING) This is the number of the device sending the fax. This is usually set to SV186. Within the context of a call, the calling number and called number may switch roles. This will require swapping these two fields and it is the responsibility of the application to determine when swapping is appropriate. called_number (STRING) This is the telephone number to which the fax will be sent. This is usually set to SV185. See the parameter description for calling_number above, regarding swapping calling number and called number. Chapter 4. Writing a Fax Application 23

38 device_rc (NUMBER) This will be set to zero if the fax was successfully sent or queued. See Return codes for the possible return codes. device_state (NUMBER) This indicates the state of the fax handler. If a fax was queued (if callback_st does not equal null) the number will be 7; if the fax was sent (if callback_st was null) the number will be 8, and if the number is -1 an error has occurred and device_rc should be checked. Return codes 0 success -500 failed to communicate with the custom server 400 v file does not exist (for example, invalid file name specified) v file is not accessible (check file permissions) v file is empty 401 unable to parse list file 402 unsupported extension on file name 403 bad file detected in list file: that is, error code 400 or 402 applies to it 404 Brooktrout fax API failed to handle text file. Problems include: v unable to open it v unable to close it v unable to send part or all of it v unable to receive all or part of it (for example, nonexistent directory specified) 405 Brooktrout fax API failed to handle TIFF file. Problems include: v unable to open it v unable to close it v unable to send part or all of it v unable to receive all or part of it (for example, nonexistent directory specified) 24 Fax using Brooktrout

39 406 dynamic memory allocation error 407 failed to convert fax file to.tif format (with user-supplied utility) 408 channel number is invalid 409 file name error: for example, generated file name too long 410 failed to get free fax channel 411 name of callback state table is too long 412 invalid characters in the state table name 413 invalid fax number (for example, wrong number of digits) 414 failed to place fax on the queue 415 invalid send type (allowed values are: 0 = send immediately; 1 = queue it) 416 failed to get timeslot for fax card or DTTA card 460 failed to invoke custom server function 470 state table action MakeCall() failed 480 internal error (for example, function called with invalid parameter) 490 device error (Brooktrout fax API call failed) In addition, many of the error codes corresponding to values of CA_errno may be returned in the variable device_rc if an invocation by the custom server of one of the CA_XXX family of functions fails for some reason. These error codes start at value 51 (50 is actually the first code but as this represents the 'no error' case it will never actually be seen). For an explanation of these error codes, see WebSphere Voice Response for AIX: Custom Servers, "Error Return Codes". Chapter 4. Writing a Fax Application 25

40 Edge 0 success 1 failure Description On return from BFAX_SEND_FAX for queued requests (callback_st not null) device_rc will be set to 0, and device_state set to 7 (QUEUED). If device_state is set to -1, fax queuing failed and device_rc should be checked for the failure reason. BFAX_SEND_FAX also allows immediate faxing (no queuing). For immediate operation, callback_st must be set to null. The status of an immediate send fax operation is returned in device_rc and device_state. On return, for immediate SendFax request (callback_st = null), device_rc will be set to 0, and device_state set to 8 (SENT). If device_state = -1, immediate fax send failed: check device_rc for failure reason. SendFax can be invoked again when control returns to the application state table. If device_state does not = 7 (QUEUED) or 8 (SENT), this does not prevent the application state table from retrying the SendFax operation. If the filename parameter contains a listfile (.lst), each line in the listfile must have the following format: <One or two digit record number><comma></full-pathname/filename> For example: 01,/myfax_directory/fax01.tif 02,/myfax_directory/fax02.tif 03,/myfax_directory/fax03.tif Record numbers must start at 1; they must be sequential and unique duplicate record numbers are not allowed. Listfiles can be used on immediate or queued send-fax requests to send a list of faxes within the context of a single call. Verification (existence and accessibility check) of each file within the list is performed prior to processing any files in the list. If verification fails, listfile processing is terminated, device_rc will be set to the appropriate value see Return codes on page 24 and device_state will be set to -1. If unrecoverable errors occur during transmission of a listfile, the fax operation will terminate, device_rc will be set to the appropriate error code, and device_state will be set to -1 (FAIL). Prerequisite: An available WebSphere Voice Response channel and enough file system space to create fax-record-file(s) for requested fax operation. 26 Fax using Brooktrout

41 Queued faxes are processed in First-In-First-Out (FIFO) order. The status of a queued send-fax operation is made available to the application via the application callback state table. After each BFAX_SEND_FAX attempt, the specified callback state table indicated in callback_st is invoked at the entry point labelled begin and passed a set of parameters as detailed in the section which deals specifically with the BFAX_CALL_BACK state table. Note: The BFAX_CALL_BACK state table must return control using the ExitStateTable action after processing BFAX_SEND_FAX status information. The expected return edge from the BFAX_CALL_BACK state table is '0'. BFAX_RECV_FAX Purpose This state table provides the interface to the BrooktroutFax functionality in WebSphere Voice Response for receiving a fax in.tif format (see tif - tag image format). ASCII syntax InvokeStateTable ("DIRECT", BFAX_RECV_FAX, begin, filename, calling_number, called_number, device_rc, device_state); Entry Point The entry point for this state table is begin Parameters filename (STRING) This parameter is optional. If it is supplied, then the specified file in the form of a file name only (the file name will be concatenated with the path set with BFIT) will be used for the fax being received. The directory must have write permission for all users. If it is not supplied, then the custom server will generate a file name which will be returned to the calling state table. The file extension is set to.tif, and the file name has the form, YYYYMMDDhhmmss.dtchannelnum.tif where YYYY is the year, MM is the month, DD is the day, hh is the hour, mm is the minutes and ss the seconds, and where dtchannelnum is the WebSphere Voice Response channel on which the fax was received. calling_number (STRING) Not used. Retained for backwards compatibility only. called_number (STRING) Not used. Retained for backwards compatibility only. Chapter 4. Writing a Fax Application 27

42 device_rc (NUMBER) This is set to zero if the fax was received successfully. If there was an error, it will be non-zero. See Return codes below for a description of the possible return codes device_state (NUMBER) This is the state of the fax handler. If the fax was received successfully, this will be 9. If it is -1, it means that an error has occurred and device_rc should be checked. Return codes 0 success -500 failed to communicate with the custom server 400 v file does not exist (for example, invalid file name specified) v file is not accessible (check file permissions) v file is empty 401 unable to parse list file 402 unsupported extension on file name 404 Brooktrout fax API failed to handle text file. Problems include: v unable to open it v unable to close it v unable to send part or all of it v unable to receive all or part of it (for example, nonexistent directory specified) 405 Brooktrout fax API failed to handle TIFF file. Problems include: v unable to open it v unable to close it v unable to send part or all of it v unable to receive all or part of it (for example, nonexistent directory specified) 406 dynamic memory allocation error 28 Fax using Brooktrout

43 408 channel number is invalid 409 file name error: for example, generated file name too long 410 failed to get free fax channel 413 invalid fax number (for example, wrong number of digits) 416 failed to get timeslot for fax card or DTTA card 460 failed to invoke custom server function 480 internal error (for example, function called with invalid parameter) 490 device error (Brooktrout fax API call failed) In addition, many of the error codes corresponding to values of CA_errno may be returned in the variable device_rc if an invocation by the custom server of one of the CA_XXX family of functions fails for some reason. These error codes start at value 51 (50 is actually the first code but as this represents the 'no error' case it will never actually be seen). For an explanation of these error codes, see WebSphere Voice Response for AIX: Custom Servers, "Error Return Codes". Edge 0 success 1 failure Description To receive a fax, an application state table should call BFAX_RECV_FAX. BFAX_RECV_FAX operates within the context of the current call and requires that appropriate fax tones from the remote fax device be detected by WebSphere Voice Response prior to the application invoking BFAX_RECV_FAX. Once BFAX_RECV_FAX is called, control is not returned until the fax operation is complete. If successful, device_rc is set to 0, and device_state is set to 9. If device_state returns with a value other than 9, the request failed and device_rc should be checked for failure reason. Chapter 4. Writing a Fax Application 29

44 BFAX_RECV_FAX can be invoked again when control returns to the application state table. If device_state does not = 9, this does not prevent the application from retrying BFAX_RECV_FAX. Note: It is the responsibility of the user application to move received faxes from the directory specified in FaxReceptionDirectory (see BFIT configuration entries in Chapter 5, Brooktrout Fax Interface Tool, on page 33) to prevent overwriting or deletion. The appropriate time to move or copy a received fax is when control returns to the application state table. Prerequisites: v fax tone detected on active WebSphere Voice Response telephony channel v file system space is available to receive fax BFAX_CALL_BACK Purpose When invoking the BFAX_SEND_FAX state table to send a two-call fax, you must specify the name of a state table in the callback_st parameter. This state table will be invoked after the fax has been taken from the queue and an attempt has been made to send it. The state table is invoked whether or not the fax was sent successfully. A state table called BFAX_CALL_BACK is provided as an example of a state table which conforms to the interface specification which follows. It makes an entry in the log file called BFAX_CALL_BACK.log in the directory specified by the environment variable OAM_LOG_PATH. The fax application developer is free to replace the BFAX_CALL_BACK state table with one of his own design to perform any actions which may be required at this stage of processing a two-call fax. The only constraint is that the number and type of its parameters must exactly match those described in this section. ASCII syntax This BFAX_CALL_BACK is not called by a user's state table as the invocation of this state table is from inside the BrooktroutFax custom server. However, for completeness the syntax of a typical invocation of this state table is included here: InvokeStateTable ("DIRECT", BFAX_CALL_BACK, start, filename, profile_id, start_date, start_time, duration, retry_count, called_number, device_state, device_rc); Entry Point The entry point for this state table is start 30 Fax using Brooktrout

45 Parameters filename (STRING) The file name of the fax. This was provided by the call to BFAX_SEND_FAX when the fax was queued. profile_id (STRING) The WebSphere Voice Response profile ID. This was provided by the call to BFAX_SEND_FAX when the fax was queued. start_date (STRING) The date the fax was sent (yyyy/mm/dd) start_time (STRING) The (local) time the fax was sent (hh:mm:ss) duration (NUMBER) The duration of the fax operation in seconds retry_count (STRING) Number of retries required to send the fax called_number (STRING) The telephone number to which the fax was sent. This was provided by the invocation to BFAX_SEND_FAX when the fax was queued. device_state (NUMBER) This is the state of the fax handler. If the fax was sent successfully, this will be 8. If it is -1, it means that the transmission has failed. 8 Sent -1 Failure device_rc (NUMBER) Code which reflects the outcome of sending or attempting to send the fax. -1 Failed to invoke the BFAX_SEND_FAX state table 0 Fax sent successfully 1 Fax send operation failed Note: Unlike the parameters in the BFAX_SEND_FAX and BFAX_RECV_FAX state tables, the parameters device_state and device_rc are input parameters. Return codes None of the state table parameters are used to return values to the invoker, and any edges returned are ignored. The state table is invoked by the BrooktroutFax custom server which cannot be accessed internally or modified by the fax application developer Chapter 4. Writing a Fax Application 31

46 Description This state table, as specified in the callback_st parameter is invoked once a fax has been sent from the queue (that is, in a two-call fax). BFAX_LOG Purpose This state table adds a date and time stamp to the supplied message and writes it to a log file. ASCII syntax InvokeStateTable ("DIRECT", BFAX_LOG, begin, Logeventstring); Entry Point The entry point for this state table is begin Parameters Logeventstring (STRING) Message to be logged Description Use the BFAX_LOG state table to write information to the log file. The log file is named $OAM_LOG_PATH/Appl.appl_name.log, where appl_name is the name of the state table that called the Brooktrout fax state tables. Also, if the Brooktrout fax state tables detect an error, they invoke the BFAX_LOG state table to put information about that error in the log file. 32 Fax using Brooktrout

47 Chapter 5. Brooktrout Fax Interface Tool The BrooktroutFax server is configured using the Brooktrout Fax Interface Tool (BFIT). BFIT is a System Management Interface Tool (SMIT) front-end which allows the WebSphere Voice Response user to display and modify the Brooktrout Fax Server runtime configuration parameters. BFIT uses the standard SMIT interface, so the keystrokes and mouse clicks for navigation, scrolling, fields, lists and help in BFIT will be familiar to SMIT users. Use of BFIT You must be logged in as the WebSphere Voice Response user to use BFIT. If you did not log in as the WebSphere Voice Response user (dtuser in this example), at the AIX command line, type su - dtuser and give the password. You must include the minus sign in this command, so that AIX will execute the.profile for dtuser. Invocation Both the Curses (plain-text) and Motif (GUI) versions are supported. The appropriate version is invoked depending on the command you issue and your terminal type. Both versions provide the same functions. To invoke the GUI version of BFIT, type bfit at the AIX command line in an AIX terminal window. If the Motif GUI is not available for your terminal type, AIX will automatically invoke the plain-text version instead. To invoke the plain-text version of BFIT, type bfitty at the AIX command line in any terminal window. The bfit or bfitty command invokes SMIT to display and modify the BrooktroutFax server runtime configuration parameters. Note: SMIT requires a minimum of 24 lines x 80 characters to display its output in the plain-text version. Viewing values When you type bfit, the GUI version first displays the SMIT window, followed immediately by the BFIT main field entry window. All variables are Copyright IBM Corp. 1996,

48 presented on a single, scrollable window. Figure 4. GUI version of the main window Here are the descriptions, meaning and use of the fields available in the BFIT main window, as covered in the help text: 34 Fax using Brooktrout

49 Table 1. Field names and descriptions in the BFIT main window Parameter Description Fax Reception Directory The directory used by the Brooktrout custom server to save received fax files. Default = "/usr/lpp/dirtalk/db/current_dir/oamlog" Fax Queue Location Max length: 255 The directory used by the Brooktrout custom server to hold the queue of fax requests to be sent to fax machines. Default = "/usr/lpp/dirtalk/db/current_dir/oamlog" Max Processes To Spawn Max length: 255 The number of processes that are started to handle fax requests. Each concurrent fax requires one process. Increasing this value will consume more memory. With the TR1034 board, set this value to the maximum number of concurrent fax channels you require, up to the limit of 30. Default = 16 Logging Level Range: 1-48 Determines the amount and detail of trace information stored into the BrooktroutFax.log file in OAM_LOG_PATH. This entry should be changed only under the direction of IBM service personnel. Default = normal Max Queue Fax Channels Choices: normal; errors; warnings; information; debug. The maximum number of channels allowed to transmit fax files to fax machines using 2-call fax transmission. This leaves the remaining number of channels free for 1-call fax transmission and fax reception. Default = 8 Max Transmission Attempts Range: 0-48 The maximum number of attempts to transmit a fax to a fax machine. If this number is reached, no further transmission attempts are made, and an exception record is placed in the log file. Default = 4 Range: Chapter 5. Brooktrout Fax Interface Tool 35

50 Table 1. Field names and descriptions in the BFIT main window (continued) Parameter Description Wait Time On Empty Queue The time (in seconds) that the queue process waits before rereading the queue when there are currently no items on the queue. Default = 30 Wait Time On Non-Empty Queue Range: The maximum time (in seconds) that the queue process waits before rereading the queue after starting to process an entry. The queue is next checked after the entry has been processed or after this time period has expired, whichever occurs first. Default = 30 Wait Time For Fax Line Available Range: The time (in seconds) that the custom server will wait for a free channel before aborting transmission and logging a failure to transmit a fax. Default = 5 Wait Time On Line Exception Range: The time (in seconds) to wait before retrying a fax transmission after a line exception condition has been detected. Line exceptions include busy and line problem. This limit applies only to faxes queued for sending. Default = 60 Fax ID Range: A counter that is used to identify a fax when adding it to the fax queue. The counter starts at 0 and is incremented by 1 before each fax is queued, so the first fax will have a FaxID of 1. It is not incremented when receiving a fax, or when sending a one-call fax. If an item is re-queued due to an error then it will receive a new FaxID. The FaxID is initialized to 0 when BFIT is installed, and the FaxID is maintained across restarts of AIX, WebSphere Voice Response and the BrooktroutFax Custom Server. When the FaxID exceeds , it is reset to 1. The FaxID can not be changed by the user. Default = 0 Range: Fax using Brooktrout

51 Table 1. Field names and descriptions in the BFIT main window (continued) Parameter Description Right Margin Units in tenths of an inch. Applicable to text-to-tiff conversion only. Default = 2 Left Margin Range: Units in tenths of an inch. Applicable to text-to-tiff conversion only. Warning: If the value is set too low, some fax machines may clip the left-hand edge of the faxed image. Default = 3 Page Width Range: 0-12 A4 = 215 mm, 1728 pixels normal resolution B4 = 255 mm, 2048 pixels normal resolution A3 = 303 mm, 2432 pixels normal resolution. Applicable to text-to-tiff conversion only. Page Resolution Default = A4 200H_100V = 204 dpi horizontal, 98 dpi vertical (Normal) 200H_200V = 204 dpi horizontal, 196 dpi vertical (Fine) Applicable to text-to-tiff conversion only. Fax Header Default: 200H_100V The label format uses date/printf style specifications to place items of information into the header or footer text lines. All characters, except %, represent themselves on output. When the function encounters a '%' character, it bases its output format on the format character immediately following the '%' character. Chapter 5. Brooktrout Fax Interface Tool 37

52 Table 1. Field names and descriptions in the BFIT main window (continued) Parameter Description Fax Header (contd) The format characters include: a A Day of the week, 3-character abbreviation Day of the week, full-length d Day of the month, Nf Switch to font #N. (Applications can mix fonts of the same height) H Hour, I Hour, m Month, M Minute, p np AM/PM Page number, (leading 0 is rendered as a space), optional 'n' resets page numbering as specified, and when sent together, the 'n' in the header overrides the 'n' in the footer nr Same as np, but uses 3-digit page numbers S Seconds, y Year, Y 4-digit year % '%' character N^ Insert N blank G3 lines before header/footer N_ Insert N blank G3 lines after header/footer Note: Some roll paper fax machines may have a gap of about 1/8 inch when printing a fax. This means that the fax machine may not display the first character of the header/footer because the header/footer is positioned at address 0. To avoid this condition, add leading spaces to the fax header/footer. Default = "Brooktrout Fax %A %d %m %Y %H:% M:% S Page:%P" Max length: Fax using Brooktrout

53 Table 1. Field names and descriptions in the BFIT main window (continued) Parameter Description Fax Footer The same as Fax Header, except that the output is placed in the fax footer. Refer to Fax Header help for details of the format string. Default = Page:%P Fax Local ID Max length: 255 The local ID (usually the phone number) used in the TSI, CSI or CIG commands. Default = null string Fax Local Name Max length: 20 The local name. Default = null string Text to Tif Conversion (Path) Max length: 80 The full path and file name of a utility program that converts a text file to TIFF format. If you leave this field empty, the utility program provided by the Brooktrout API will be used, which uses margins and resolution specified elsewhere on this screen. If you enter a value in this field, the program you specify will be used instead, but it will not have access to the margins and resolution specified elsewhere on this screen. The program must conform to the following command syntax <utility-name> <filename.txt> <filename.tif> Default = null string PCX to Tif Conversion (Path) Max length: 255 The full path and file name of a utility program that converts a PCX file to TIFF format. The Brooktrout API does not provide such a utility program, so if you do not enter a value in this field, the conversion cannot be done. The program must conform to the following command syntax <utility-name> <filename.pcx> <filename.tif> Default = null string Max length: 255 Chapter 5. Brooktrout Fax Interface Tool 39

54 The plain-text version by-passes the SMIT window and goes directly to the BFIT main field entry window. Brooktrout Fax Interface Tool Type or select values in entry fields. Press Enter AFTER making all desired changes. [Entry Fields] * Fax Reception Directory [/usr/lpp/dirtalk/db/current_dir/oamlog] / * Fax Queue Location [/usr/lpp/dirtalk/db/current_dir/oamlog] / * Max Processes To Spawn [16] # * Logging Level [normal] +# * Max Queue Fax Channels [8] # * Max Transmission Attempts [4] # * Wait Time On Empty Queue [30] # * Wait Time On Non-Empty Queue [30] # * Wait Time For Fax Line Available [5] # * Wait Time On Line Exception [60] # Fax ID (Sequence Number) 21 * Right Margin [2] +# * Left Margin [3] +# * Page Width [A4] +# * Page Resolution [204dpi H x 98dpi V (Normal)] +# Fax Header [Brooktrout Fax %A %d %m %Y %H:%M:%S Page:%P] Fax Footer [Page:%P] Fax Local ID [] Fax Local Name [] Text to Tif Conversion [] / PCX to Tif Conversion [] / F1=Help F2=Refresh F3=Cancel F4=List F5=Reset F6=Command F7=Edit F8=Image F9=Shell F10=Exit Enter=Do Figure 5. Plain-text version of the BFIT main window BFIT displays the current values of the variables. If you have never run BFIT before, these variables will have their default values. Help text BFIT provides help text for each field. To get help in the GUI version, click on the? button at the bottom of the GUI version of the main window and place the mouse pointer on the desired field. The help text for that field will appear in a new help window. 40 Fax using Brooktrout

55 Figure 6. GUI version of the help window Moving the mouse pointer to another field will cause the help window to display the help text for the other field: you do not need to click the mouse buttons or press any key. The help window stays open until you close it or quit BFIT. To get help in the plain-text version, place the cursor on the desired field and press F1. The help text for that field will appear in a new help window. Chapter 5. Brooktrout Fax Interface Tool 41

56 Brooktrout Fax Interface Tool Type or select values in entry fields. Press Enter AFTER making all desired changes. [Entry Fields] * Fax Reception Directory [/usr/lpp/dirtalk/db/current_dir/oamlog] / * Fax Queue Location [/usr/lpp/dirtalk/db/current_dir/oamlog] / * Max Processes To Spawn [16] # * Logging Level [normal] +# * Max Queue Fax Channels [8] # * Max Transmission Attempts [4] # * Wait Time On Empty Queue [30] # * Wait Time On Non-Empty Queue [30] # * Wait Time For Fax Line Available [5] # * Wait Time On Line Exception [60] # Fax ID (Sequence Number) 21 * Right Margin [2] +# * Left Margin [3] +# * Page Width [A4] +# * Page Resolution [204dpi H x 98dpi V (Normal)] +# Fax Header [Brooktrout Fax %A %d %m %Y %H:%M:%S Page:%P] Fax Footer [Page:%P] Fax Local ID [] Fax Local Name [] Text to Tif Conversion [] / PCX to Tif Conversion [] / CONTEXTUAL HELP Press Enter or Cancel to return to the application. The directory used by the Brooktrout Custom server to save received Fax files. Default: "/usr/lpp/dirtalk/db/current_dir/oamlog" Max length: 255 F1=Help F1=Help F2=Refresh F3=Cancel F5=Reset F8=Image Enter=Do F9=Shell Figure 7. Plain-text version of the help window Use the arrow keys or PageUp/PageDown function keys to scroll through the help text if necessary. Press F3 to close the help window. You have to close the help window before you can type any more text or move the cursor to another field. Editing values You can alter any of the variables by overtyping their values or selecting from a list on those fields where a list option is provided. In the GUI version, select the field you wish to alter by clicking on it, or use the Tab key to step through the fields. Numeric fields are designated by the string (Num.) after the field name. Path names are designated by the string (Path) after the field name. Fields where values are selected from a list are designated by a button marked List after the field name. 42 Fax using Brooktrout

57 Figure 8. GUI version of the list window For list fields, click on the adjacent arrow buttons to move your selection up or down the list. To display the complete list, click on the List button. While the list is displayed, use the arrow keys to move your selection up and down the list, then press the Spacebar, or just click on the desired list item, to make your selection and close the list display. In the plain-text version, select the field you wish to alter by using the up/down arrow keys. Numeric fields are designated by the symbol # after the entry field. Path names are designated by the symbol / after the field name. Fields where values are selected from a list are designated by the character + after the field name. Chapter 5. Brooktrout Fax Interface Tool 43

58 Brooktrout Fax Interface Tool Type or select values in entry fields. Press Enter AFTER making all desired changes. [Entry Fields] * Fax Reception Directory [/usr/lpp/dirtalk/db/current_dir/oamlog] / * Fax Queue Location [/usr/lpp/dirtalk/db/current_dir/oamlog] / * Max Processes To Spawn [16] # * Logging Level [normal] +# * Max Queue Fax Channels [8] # * Max Transmission Attempts [4] # * Wait Time On Empty Queue [30] # * Wait Time On Non-Empty Queue [30] # * Wait Time For Fax Line Available [5] # * Wait Time On Line Exception [60] # Fax ID (Sequence Number) 21 * Right Margin [2] +# * Left Margin [3] +# * Page Width [A4] +# * Page Resolution [204dpi H x 98dpi V (Normal)] +# Fax Header [Brooktrout Fax %A %d %m %Y %H:%M:%S Page:%P] Fax Footer [Page:%P] Fax Local ID [] Fax Local Name [] Text to Tif Conversion [] / PCX to Tif Conversion [] / Page Width Move cursor to desired item and press Enter. A4 B4 A3 F1=Help F2=Refresh F3=Cancel F1=Help F8=Image F10=Exit Enter=Do F5=Reset /=Find n=find Next F9=Shell Figure 9. Plain-text version of the list window For list fields, press the Tab key to select the next item on the list. Press the Alt+Tab keys to select the previous item on the list. To display the complete list, press F4. While the list is displayed, use the arrow keys to move your selection up and down the list, then press Enter to make your selection and close the list display. Validation BFIT checks each field as you type. Numeric fields can contain only numeric values, and path name fields can contain only legal AIX path names. BFIT checks numeric values are within range, and path names exist on your system. Storing values All values are stored in a single operation. 44 Fax using Brooktrout

59 To store the new values, either press Enter (if you are using the plain-text version) or click Ok (if you are using the GUI version). BFIT will immediately attempt to process the current values in the window and store them for use by the BrooktroutFax server. A progress window is displayed while BFIT processes your input. Figure 10. GUI version of the progress window When processing is complete, BFIT displays Ok if processing was successful, or Failed if not. Chapter 5. Brooktrout Fax Interface Tool 45