PART II HEARSAY PROGRAMMER'S GUIDE INTRODUCTION Hearsay Gold allows programmers to call speech functions directly from programs they write, without going through the Hearsay menus. These functions can be called directly from assembly language or by high level languages with register-access capability such as "C". For programmers working in BASIC, an assembly-language driver program is included on the Hearsay Gold diskette. The available functions are: - SPEAK A LINE OF TEXT - SET SCREEN ECHO PARAMETERS - SET SCREEN ECHO WINDOW - UNHOOK HEARSAY FROM DOS - LOAD DICTIONARY - GET VERSION NUMBER Examples are given in BASIC and Assembly Language. For BASIC programmers, sample code segments are provided, which when copied directly into your program will call the Hearsay driver program and exercise the programmable functions. CALLING HEARSAY FUNCTIONS FROM BASIC To access Hearsay Gold functions from BASIC programs, a machine language "Driver" program must be called from BASIC. A multiple function driver (HSGOLDDR.BAS) is supplied on the Hearsay Gold diskette. In order to use the Hearsay functions, your BASIC program must load the driver program into high memory, and then "Call" the driver for each function required. To load the driver into high memory: 1. When loading BASIC, reserve memory for the driver by using a /M switch. Type in: BASIC/M:65024 (BASICA/M:65024 if you use BASICA) then 2. Include the following lines in your program to load the driver into memory: 10 REM LOAD HEARSAY DRIVERS 20 DEF SEG 30 HSBASE=65024! :REM This must be equal to the 40 :REM number used in the /M switch 50 BLOAD "HSGOLDDR",HSBASE 60 70 :REM INITIALIZE HEARSAY FUNCTIONS 80 SAYSTR=HSBASE+256! :REM Location of SAYSTR Driver 90 BUFFER=HSBASE :REM Location of SAYSTR Buffer 100 SETSCRENCHO=HSBASE+272! :REM Location of SETSCRENECHO 110 SETWINDOW=HSBASE+321! :REM Location of SET WINDOW 120 UNHOOK=HSBASE+352! :REM Location of UNHOOK HS 130 LOADDICT=HSBASE+388! :REM Location of LOAD DICTIONARY 140 GET VERSION+HSBASE+411! :REM Location of GET VERSION Once the driver is loaded, each Hearsay function can be called by setting the proper values & then calling the desired function from the Hearsay driver. SPEAK A LINE OF TEXT The SAYSTR function speaks a line (String) of text. In the BASIC program example given below, this is a line of text typed at the keyboard in response to a prompt, but it could have been hard coded into the program (By initializing A$ as the string to be spoken). PROGRAMMING IN BASIC The BASIC program segment below calls for the SAYSTR function. 100 REM Input a line of text from the keybaord and speak it. 110 SAYSTR=HSBASE+256! :REM Location of SAY driver 120 BUFFER=HSBASE :REM Location of BUFFER 130 INPUT A$ :REM Get line from keyboard 140 A$=A$+"." :REM Add period and space 150 POKE BUFFER,LEN(A$) :REM Store length of line 160 FOR N=1TOLEN(A$) :REM Store line in buffer 170 POKE BUFFER+N,ASC(MID$(A$,N,1)) 180 NEXT N 190 CALL SAYSTR :REM Speak line Lines 110-120 establish the parameters for the SAYSTR function. Once that has been done, it is not necessary to do it again each time a string is to be spoken it remains available to you until you redfine it or leave the program. Lines 130-140 accept input keystrokes to define the string to be spoken, & put a period & space at the end of it. If you were hard coding the string into your program you would replace these lines with a string defining A$, including the period and space in the definition (ie. 130 A$="THIS IS A TEST."). Line 150 pokes the length of the string into the beginning of the buffer and lines 160-180 poke the characters of the string into the buffer. This must done for each string you want Hearsay to speak. Once the string has been defined and poked into the proper location in memory, line 190 calls the SAYSTR function which speaks the phrase. PROGRAMMING IN ASSEMBLER The SAYSTR function speaks the text string passed to it. The first byte of the string must contain the length of the string. You must allocate 256 Bytes for the string even if the length is less than 256 Bytes. USE 1. First push a FAR pointer to string onto the stack. 2. The call Hearsay Gold with a function code of 00h in the AL register. 3. Upon return, pull all parameters from the stack. SAY STRING EXAMPLE DATA SEGMENT WORD PUBLIC 'DATA' String EQU $ DB 24d DB 'I am the Hearsay Gold' DB 13d DATA ENDS CODE SEGMENT BYTE PUBLIC 'CODE' ASSUME CS:CODE,CS:DATA Say demo PROCEDURE NEAR mov ax,ds ;Push far pointer to STRING push ax ;onto the stack. mov ax,offset String push ax mov al,00h ;Call the Hearsay Gold with int 55h ;a function code of 00h. pop ax ;Pull parameters from stack. pop ax ret Say demo ENDP CODE ENDS END SET SCREEN ECHO PARAMETERS The SETSCRENECHO function set Screen Echo ON or OFF, defines punctuation, voice, pitch, and speed for both the Screen Echo and the Say String functions. If SETSCRNECHO is never called, Hearsay will default to voice 1, pitch 6, and speed 7 for Say String functions. PROGRAMMING IN BASIC In the BASIC program sample given below, Screen Echo is set on & the other parameters are set to their default values (All parameters must be included when SETSCRNECHO is called, even if they are to be set to the default values). 100 SETSCRNECHO=HSBASE+272! :REM Location of SETSCRNECHO 110 ECHO%=1 :REM Set ECHO on (0 would be off) 120 PUNCT$=0 :REM Don't speak punctuation 130 LM%=0 :REM Set Line Mode off 140 VOICE%=1 :REM Use voice 1 150 PITCH%=6 :REM Use pitch 6 160 SPEED%=7 :REM Speed 7 170 CALL SETSCRENECHO (ECHO%,PUNCT%,LM%,VOICE%,PITCH%,SPEED%) 180 REM Screen Echo is now set as indicated above Line 100 establishes the location of SETSCRENECHO, the Screen Echo function in the Hearsay driver. This line needs to occur once in your program, the location will be maintained until you leave the program. Lines 110-160 establish the conditions to be implemented. It's necessary to enumerate all conditions every time you change any one. Line 170 calls the SETSCRNECHO driver and establishes the conditions you described in lines 110-160. This command will be included at any point in your program where you want to change to Screen Echo settings. PROGRAMMING IN ASSEMBLER USE 1. First push an integer (1 to 9, 1 is slowest, 7 is default) to specify speed. 2. Next push an integer (1 to 9, 1 is slowest, 6 is default) to specify pitch. 3. Then push an integer (1 or 2, 1 is lower and default) to specify voice. 4. Next push an integer (1 or 0, 0 is off & default) to specify line mode. 5. Then push an integer (1 or 0, 0 is off and default) to specify punctuation mode. 6. Next push an integer (1 or 0, 0 is off and default) to specify screen echo. 7. Now call Hearsay Gold with a function code of 01h in the AL register. 8. Upon return, pull all parameters from stack. SET SCREEN ECHO EXAMPLE CODE SEGMENT BYTE PUBLIC 'CODE' ASSUME CS:CODE Set echo PROCEDURE NEAR push bp ;Save stack pointer mov bp,sp mov ax,7 ;Speed=7 push ax mov ax,6 ;Pitch=6 push ax mov ax,1 ;Voice=1 push ax mov ax,0 ;Line mode off push ax mov ax,0 ;Punctuation mode off push ax mov ax,1 ;Screen echo on push ax mov al,01h ;Call the Hearsay Gold with a int 55h ;function code of 01h mov sp,bp ;Remove parameters from stack pop bp ret Set echo ENDP CODE ENDS END SET WINDOW The SETWINDOW function sets Hearsay's Screen Echo window parameters. The function defines the top & bottom lines of the window, and whether text inside or outside of it is to be echoed. Remember, text will only be spoken when Screen Echo is turned on. PROGRAMMING IN BASIC The BASIC program segment below calls the Set Window function. 100 REM speak text from lines 10 to 15. 110 SETWINDOW=HSBASE+321!:REM Location of SETWINDOW. 120 MODE%=1: REM Speak text inside window. 130 TOP%=10: REM From line 10 to 15 140 BOTTOM%=15 150 CALL SETWINDOW (MODE%,TOP%,BOTTOM%) Line 110 establishes the location of the SETWINDOW function. This command only needs to be executed once within your program. Lines 120-140 set window parameters of inside or outside, top and bottom. Line 150 calls the SETWINDOW function and implements the parameters set in lines 120-140. This line will be used whenever it is necessary to change the Hearsay window settings. PROGRAMMING IN ASSEMBLER USE 1. First, push an integer (1 to 25, 25 is the bottom row of the screen) specifying the bottom row of the window. 2. Next push an integer (1 to 25, 1 is the top row) specifying the top row of the window. 3. Then push an integer (0 or 1, 1 is inside) specifying the mode (Whether text inside or outside the window is to be spoken). 4. Now call Hearsay Gold with a function of 2 in the AL register. 5. Upon return pop all parameters from the stack. SET WINDOW EXAMPLE CODE SEGMENT BYTE PUBLIC 'CODE' ASSUME CS:CODE WINDOW PROCEDURE NEAR mov ax,20d ;Only speak text printed from push ax ;Line 10 to line 20 mov ax,10d push ax mov ax,1 ;Set mode to speak inside window push ax mov al,02h ;Call the HEARSAY GOLD with a int 55h ;function code of 02h pop ax ;Pull parameters from stack pop ax pop ax ret WINDOW ENDP CODE ENDS END UNHOOK HEARSAY FROM DOS This command "Unloads" the Hearsay Gold program, removing all hooks to DOS and returning all reserved memory to DOS. To rerun Hearsay after unhooking, you must rerun the SpeechV2 or SPEECHV3 and Hearsay programs and redefine the Hearsay Key as you normally do at setup. PROGRAMMING IN BASIC The BASIC program segment below shows the Unhook function in use. 100 REM Unhook the HSGOLD from DOS 110 UNHOOKHS=HSBASE+352!: REM Location of UNHOOK HS. 120 CALL UNHOOKHS: REM Unhook HSGOLD from DOS. Line 110 established the location of the Unhook function (Only needs to be done once) and line 120 calls the function. PROGRAMMING IN ASSEMBLER USE 1. Issue a call to the Hearsay Gold with a function code of 3 in the AL register. 2. No parameters are passed or returned. UNHOOK EXAMPLE CODE SEGMENT BYTE PUBLIC 'CODE' ASSUME CS:CODE UNHOOK HS PROCEDURE NEAR mov al,03h ;Call the Hearsay Gold with int 55h ;a function code of 03h ret UNHOOK HS ENDP CODE ENDS END LOAD DICTIONARY This command loads a dictionary file (Created with the Speech Editor) from disk. PROGRAMMING IN BASIC An example of its use is given below: 100 REM load dictionary file SAMPLE. 110 LOADDICT=HSBASE+388!: REM Location of Load Dictionary 120 BUFFER=HSBASE: REM Location of buffer 130 FILENAME$="SAMPLE": REM Name of file to load 140 FLAG%=0: REM Initialize ERROR 150 POKE BUFFER,LEN(FILENAME$): REM Store length of filename 160 FORN=1TOLEN(FILENAME$): REM Store filename in buffer 170 POKE BUFFER+N,ASC(MID$(FILENAME$,N,1)) 180 NEXT N 190 CALL LOADDICT(FLAG%): REM Load the file 200 IF FLAG%=0THEN220: REM If error then print message 210 PRINT "ERROR LOADING FILE" 220 END Lines 110-120 establish the location of the LOADDICT function (Only needs to be done once), line 130 provides the filename of the dictionary file, & line 140 initializes the error flag. Lines 150-180 poke the filename into the buffer, & line 190 actually calls the LOADDICT function which loads the specified dictionary in Hearsay's memory. The LOADDICT function will check for errors in loading the file and set the FLAG% variable if any are encountered. Lines 200-210 check for errors and print an error message on the screen if one is encountered. (In your own program, you may choose to handle file loading errors in some other way, but you will still test it by checking the value of FLAG%). PROGRAMMING IN ASSEMBLER The LOADDICT function is called with a FAR pointer to the filename on the stack. The filename can be any legal DOS filename without the file extension, which Hearsay Gold will add automatically. If the file is to be loaded from other than the current drive & directory, an optional path name must be included with the filename. If the file loads OK, 0 will be returned in the AX register. If there was an error in loading the file, a non-zero value will be returned. Use the DOS function call 59h (GET EXTENDED ERROR) to get further information on the error. USE 1. Push a FAR pointer to the filename onto the stack. 2. Call Hearsay Gold with the function code 05h in the AL register. 3. Upon return, pull all parameters from the stack. LOAD DICTIONARY EXAMPLE DATA SEGMENT WORD PUBLIC 'DATA' filename EQU $ DB 10d ;Length of filename DB C:\HS\DEMO ;Filename with drive C and directory HS DATA ENDS CODE SEGMENT BYTE PUBLIC 'CODE' ASSUME CS:CODE,DS:DATA Load dict PROCEDURE NEAR push bp ;Save stack pointer mov bp,sp mov ax,ds ;Push far pointer to filename push ax mov ax,offset filename push ax mov al,05h ;Call the Hearsay Gold with a int 55h ;function code of 05h mov sp,bp ;Remove filename from stack pop bp cmp pax,0 ;Error? je Done ;no,exit mov bx,0h ;DOS version # mov ah,59h ;Get extended error information int 21h ;Process error Done: ret Load dict ENDP CODE ENDS END GET VERSION NUMBER This command extracts the version of Hearsay Gold currently being used. This permits software developers to check version number and version level as part of their program. Hearsay is committed to upward compatibility, so that any program written for the Hearsay Gold will run on any later version. If you are developing programs to use Hearsay, check that the version number is no lower than the one you used for development. The Version ID codes for Hearsay Gold versions 2 and 3 are 0300h and 0400h respectively. The first two digits indicate the product code, and the last two indicate the release number of that product. Release 2 of Version 2 will have a Version ID of 0301h or 769 decimal. PROGRAMMING IN BASIC The program segment below shows the function in use. 100 REM Display the HSGOLD version number. 110 HSVERSION=HSBASE+411!: REM Location of GET VERSION 120 VERSION%=0: REM Initialize number. 130 CALL HSVERSION (VERSION%): REM Get version number. 140 IF VERSION%=768 THEN PRINT "VERSION 2" 150 IF VERSION%=1024 THEN PRINT "VERSION 3" Line 110 locates the GET VERSION function (Only needs to be done once) and line 120 initializes VERSION to 0. Line 130 actually calls the GET VERSION function, returning a version number of 768 if Version 2 is loaded or 1024 if Version 3 is loaded. Lines 140- 150 test to see which version is loaded, in the example given printing the version number. PROGRAMMING IN ASSEMBLER The product code is returned in register AH and the release number is returned in register AL. USE 1. Call Hearsay Gold with function code 06h in the AL register. 2. The Version ID will be returned in register AX. GET VERSION EXAMPLE CODE SEGMENT BYTE PUBLIC 'CODE' ASSUME CS:CODE Get version PROCEDURE NEAR mov al,06h ;Call the Hearsay Gold with a int 55h ; function code of 06h ret Get version ENDP CODE ENDS END