/* V_DIAL.CMD - Voice/Fax DIAL Script for FaxWorks/PMfax (REXX) */
/* 
                  Keller Group Inc.  May 1996
   You may freely use or modify this script for use with licensed
        products which are developed by Keller Group Inc.
      For new scripts or to share your scripts with others,
                 see http://www.kellergroup.com
*/
/*******************************************************************
V_DIAL.CMD - Dial Script Example - "Person detection" for fax modems

Supported features:
	Voice announcement during outbound calls
	Called party can cancel fax and have it reported as "Voice"
	Called party can leave a message (to provide correct fax number)
	Can be customized to support voice message broadcasting, etc.
	Full source code in REXX - modify as needed

DESCRIPTION:
-----------
This is a DIAL script which can be used for dialing outgoing fax
calls.  It provides a useful "value-added" service for outbound fax
calls, and it also serves as an example of how you could do
specialized "voice message broadcasting" using a dial script.

Background: Some high-end fax boards such as Brooktrout can detect
the difference between a normal "no carrier" fax call (where
something answered but we never heard the fax carrier tones) and a
"voice" call (where something answered and we never heard the fax
carrier tones, but we also think it was a person).  This "Voice!"
status is useful since it may mean that we dialed a wrong number, and
the software can cancel further automatic retries on this fax job to
avoid bothering the person again.

Fax modems do not provide this feature.  Instead, they would just
report a wrong number as a "no carrier" and we would keep retrying
the fax job.  If we are using automatic retries, the called party may
get quite upset with the repeated calls from the fax modem.

But by using this script as the "dial script" with voice/fax modems,
you can announce that you are sending a fax and give the called party
a chance to cancel retry attempts by pressing a touch tone key.  If
they do this, we will report the status of the fax job as "Voice!"
and further retries will then be cancelled by the software.  The
called party also has the option of leaving you a voice message (to
tell you the correct fax number, yelling at you for bothering them,
etc.).  If no one enters a key, the script assumes that it has
reached a fax machine and sends the fax.

USAGE INSTRUCTIONS:
------------------
You must be using the program with supported voice/fax hardware to
use this script.  Consult the README.DOC file for tested voice/fax
hardware and recommended configuration settings for your hardware.
Before using this script, first test your system with our built-in
voice answering machine feature by enabling "Voice" and setting the
"Answer script" to * (an asterisk character) on the Voice page of the
Settings notebook.  If you are using supported voice/fax hardware
with the proper configuration settings, you can then use
"Fax/Receive/All calls" mode to answer calls, play the outgoing
message (OGM), and record a voice message (or receive a fax).

Then, to try this advanced script, specify the full pathname of this
file in the "Dial script" field on the Voice page of the settings
notebook.  Test the script by sending faxes to both normal fax
machine and to your voice phone line.

NOTE: The script expects to find its Wave audio files in the fax
program (EXE) directory.  The script also uses Wave files from the
c:\mmos2\sounds directory for special effects.

SCRIPT VARIABLES:
----------------
The following script variable is used by this script.  Script
variables are set on the Voice page of the Settings Notebook.

	None.

VOICE PROMPT FILES:
------------------
The script expects to find the following Wave audio files in the fax
program (EXE) directory.  The script also uses Wave files from the
c:\mmos2\sounds directory for special effects.

To record or modify your own voice prompt files, use your OS/2
Multimedia microphone and record voice prompts using the "Fax/New
message" command then save them to a .WAV file with the "Fax/Save
file/Wave" command.  You can also use the OS/2 Digital Audio program
to record, save, edit and modify the Wave files (be sure to use
"Type" of Mono, 8-bit, 11.025 kHz).

	DIAL_FAX.WAV - "This is a fax call.  Please activate your fax
	machine, or press 1 if we called the wrong number."

	DIAL_MSG.WAV - "We are sorry for the inconvenience.  If you
	wish to leave us a message, please press 1.  Thank you."

	ENTR_MSG.WAV - Short: "Enter message."
	Long: "Please leave your message at the beep."

TO MODIFY THE SCRIPT:
--------------------
The script is REXX and uses calls from the Keller REXX API which are
automatically loaded into the OS/2 REXX environment by the retail
versions of Keller's fax products (version 3.0 and later).  See the
Reference Manual for documentation of the FxRx and FxLn calls.  You
may modify the script as desired, and then use it as the "Dial
script" with Keller fax software products.

*******************************************************************/

call FxLnInit

VOXDIR = FxRxPath( 'EXE' )		/* get prompts from exe dir */

call FxLnPlay VOXDIR||'DIAL_FAX.WAV'	/* play the greeting prompt */
    if result = 'NOTOK' then signal fax
    if result = 'FAX' then signal fax
    if result = 'DATA' then signal data

call FxLnDtmf 1, 5, 'digit'		/* get user key, 5 sec timeout */
    if result = 'DTMF' then signal voice   /* key ==> person answered */
    if result = 'DATA' then signal data
    signal fax				   /* otherwise try to send */

voice:
    call FxLnMsg 'Person detected'
    LREC.!Status = 'Voice!'		/* fax status will be Voice */
    
    call FxLnPlay VOXDIR||'DIAL_MSG.WAV'   /* play the message prompt */
        if result = 'NOTOK' then signal out

    call FxLnDtmf 1, 10, 'digit'	/* get user key, 10 sec timeout */
        if result <> 'DTMF' then signal out

    /* caller wishes to leave us a message... */
    /* first save fax record  */
    /* You'd think REXX would do "FaxRec. = LREC.", but it doesn't. */ 
    /* So rather than using REXXLIB, we'll use our format/parse.    */
    FaxRec = FxRxFormatLog( 'LREC' )
    LREC. = ''				/* clear the log record */
    
    call FxLnMsg "Record Msg"
    call FxLnPlay VOXDIR||'ENTR_MSG.WAV'
        if result = 'NOTOK' then signal voiceout
    call FxLnTone 1850
        if result = 'NOTOK' then signal voiceout
    call FxLnDtmf    /* flush dtmf buffer */
    call FxLnRecord
        if result = 'NOTOK' then signal voiceout
    /* Caller can press key or hangup to end message */
    call FxLnTone 1850, 1850, 1850

voiceout:
    call FxLnLog			/* log the voice message */
    call FxRxParseLog FaxRec, 'LREC'	/* restore the fax record */
    signal out

fax:					/* send fax and hangup */
    call FxLnSend
    signal out

data:					/* report data call, hangup*/
    call FxLnMsg 'Data call, oh well...'
    LREC.!Status = '*Data!'		/* set status of call */
    signal out

out:					/* log fax status and quit */
    call FxLnTerm
    exit
