Date: 16 December 1998

KFSDTNT and KFSDT2V2 User Action Libraries

These libraries contain several useful user actions that can be used with any DirectTalk system. The two libraries contain the same set of actions (with one exception). 

Note #1: The KFSDT2V2 user action, Get_Mailbox_Data, is not included in the KFSDTNT Library since the Voice Messaging Feature is not available on DirectTalk for Windows. 

Note#2: If you are coding your application using Rexx, the functionality of several of the actions is redundant with features provided by Rexx itself. In those cases, I recommend using the Rexx methods over the actions here.  

 

Download the version for OS/2. (100,488 bytes)

Download the version for Windows. (65,325 bytes)

 

Installation for Windows

  1. Unzip the contents of the file to a temporary directory.
  2. Copy KFSDTNT.DLL to the \DTALK directory.
  3. Copy KFSDTNT.UAI to the \DTALK\DATA directory.
  4. Copy KFSDTNT.HTML  to the \DTALK\DOCS directory.
  5. Import the user action definitions using the Development Work Area. See the Application Development User's Guide for more information.

Note: If you intend to use the Get_Alpha_String action, see the usage instructions for that action for some additional installation instructions.

Installation for OS/2

  1. Unzip the contents of the file to a temporary directory.
  2. Copy KFSDT2V2.DLL to the \DTALK directory.
  3. Copy KFSDT2V2.UAI to the \DTALK directory.
  4. Copy KFSDT2V2.INF  to the \DTALK directory. (Use OS/2 View command to view this help file.)
  5. Copy all of the *.HLP files to the \DTALK directory.
  6. Import the user action definitions using the Voice Application Developer. See the Application Development User's Guide for more information.
  1. Start the Voice Application Developer.
  2. Select User Actions from the Utlities pulldown menu.
  3. Select F7 Import. Type KFSDT2V2 as the name of the import file and press enter.
  4. The actions imported will be added to the list. Save your work by pressing F4.

Note: If you intend to use the Get_Alpha_String action, see the usage instructions for that action for some additional installation instructions.

Action Summary

Convert_Date -- Convert dates in MM/DD/YY or DD/MM/YY format to the YYYYMMDD format DirectTalk voice logic modules use
Do_Date_Math -- add or subtract a specified number of days from a supplied date to arrive at a new date.
Compress_DB -- compress a DirectTalk database
Copy Voice -- copy a voice record from one key to another in the same voice database
Copy_Voice_DB -- copy a voice record from one database to another
Mirror_Voice -- copy a voice record from a database on the local DirectTalk system to another remote DirectTalk system
Create_Database -- create a new DirectTalk database
Get_Date_Diff -- calculate the number of days between two supplied dates
Pad_Variable     * -- pad data to a desired length with any character
Log_Record     * -- log a record to any text file or printer
Set_Var_Indirect    * -- indirectly set a variable's value
Get_Var_Indirect    * -- indirectly get a variable's value
Pause_Until_Time -- delay application execution until a specified time
Get_Alpha_String --  allows callers to enter alphabetic data via DTMF tones
Play_Voice_Ext -- enhanced Play_Recording action where caller can pause, fast-forward, or rewind while listening.
Load_Variables -- reads a control file and immediately creates/loads all variables within
Get_Mailbox_Data -- (OS/2 only) checks number of messages are stored in a DirectTalk/2 Voice Messaging mailbox.

Note(1) Many of the parameters on the actions will have default values. These defaults are only applicable to applications written using the DirectTalk/2 Voice Program Editor. Applications written using T-Rexx must assume that no default values have been specified. In other words, all desired parameters must be specified when the action is used.

Note(2) The development facility in DirectTalk for Windows NT is called the Development Work Area. In DirectTalk/2, it was called the Voice Application Developer. In the usage instructions, any references to the Voice Application Developer should be interpreted as referring to the Development Work Area.

* Note(3)  These actions are provided for compatibility with DirectTalk/2 and to allow you to run any applications written with the DirectTalk/2 Voice Program Editor. While they can be used with new T-Rexx applications, you should use the equivalent function already available in Rexx.

 

Help for Convert_Date

Use the Convert_Date action to convert dates to the format
needed by DirectTalk/NT to speak the date in a voice logic
module. DirectTalk/NT requires that a date to be spoken be
in the following format:
              YYYYMMDD
where:
YYYY is the four digit year;
MM is the two digit month; and
DD is the two digit year.

The action will accept an input date in the following,
different formats:
  - MM/DD/YY format which is used in the USA, or
  - DD/MM/YY format which is used in the rest of the
    world, or
  - YY/MM/DD format.

The action will accept a date such as 7/6/92 or 12-25-92
and convert it to the format above. The action will
check the date and verify it is valid before conversion.
The input date may contain leading, imbedded, or trailing
blanks. They will be ignored. The input date must use
either slash (/) or dash (-) to separate the date compo-
nents.
 

Parameters:


Input date (Input, Required, Default= none)
          Either a literal or variable containing a date
          in any of the following formats:
           o MM/DD/YY
           o MM-DD-YY
           o DD/MM/YY
           o DD-MM-YY
          A leading zero on the month or day is not
          required.  For example, 7/6/92, 7/06/92, and
          07/06/92 are all acceptable dates.

Low year (Input, Required, Default='50')
          Either a literal or variable containing the
          year that determines if a date is in the 20th
          or 21st century. If the year in the date is
          equal to or greater than the Low year value,
          the date is assumed to be in the 20th century.
          If the year is less than the Low date value,
          the date is assumed to be in the 21st century.

Variable for output (Output, Required, Default= none)
          Name of the variable where the converted date
          is to be placed. If the variable does not
          already exist, it will be created in the local
          pool.

Input Date Format (Input, Optional, Default = '1')
          Either a literal or variable which specifys the
          input date format. Set to '1' if input date is
          in MM/DD/YY format. Set to '2' if input date is
          in DD/MM/YY format. Set to '3' if input date is
          in YY/MM/DD format. If not specified, the action
          assumes MM/DD/YY format.
 
 

Return Codes:


Date converted (Return Code=0)
          The date was successfully converted and was
          stored in the variable specified.

Date Invalid (Return Code=1)
          The date was not converted as the input date
          was incorrect:

          o incorrect format -- date is not in the
          required format of MM/DD/YY. A character other
          than '/' or '-' was used as the separator. A
          alphabetic character was in the beginning of
          the date or imbedded in the date.

          o invalid date -- The month, day, or year is
          an invalid value. This includes problems such
          as month greater than 12, year greater than 99,
          or days greater than the number in the month.

Processing Error (Return Code=2)
          The action was unable to find, create, and
          save the converted date in the variable you
          specified. Problems may include an invalid
          value for the Input Data Format parameter.
 

System Variables:


none
 

Comments:


none

Return to top of page

Return to main page


Help for Do_Date_Math

Use the Do_Date_Math action to add or subtract any number
of days from a starting date to arrive at a new date. The
starting date must be specified in the following format:
              YYYYMMDD
where:
YYYY is the four digit year;
MM is the two digit month; and
DD is the two digit year.

The action will add or subtract the specified number of
days and place the new, calculated date in the specified
output variable. The calculated date is in the same
format as the input, starting date.

The action will check the starting date for validity.
 

Parameters:


Starting date (Input, Required, Default= none)
          Either a literal or variable containing a date
          in YYYYMMDD format.

Operation (Input, Required, Default= none)
          Either a literal or variable containing one
          of the following characters:
          o '+' to add the days to the starting date.
          o '-' to subtract the days from the starting
             date.
          Any other character will result in an error.

Days (Input, Required, Default= none)
          Either a literal or variable containing the
          number of days to add or subtract to the
          starting date.

Variable for output (Output, Required, Default= none)
          Name of the variable where the calculated date
          is to be placed. If the variable does not
          already exist, it will be created in the local
          pool.
 
 

Return Codes:


Operation completed (Return Code=0)
          The operation was completed and the new date
          was stored in the variable specified.

Date Invalid (Return Code=1)
          The starting date is not a valid date because
          of one of the following reasons:
          o The date was not in YYYYMMDD format.
          o The year was less than 1800 or greater than
            2100.
          o The month is invalid.
          o The day is invalid for the month.

Processing Error (Return Code=2)
          There was a processing error during the
          operation. Possible causes include an invalid
          operation, invalid number of days, or error
          saving the calculated date.
 

System Variables:


none
 

Comments:


none

Return to top of page

Return to main page


Help for Compress_DB

Use Compress_DB to compress any DirectTalk/NT database. The
function is the same as the Compress feature in the Voice
Application Developer. Data records that were previously
deleted will be physically removed from the database which
will reduce the database file size. Before the compression
is started, the database is backed up to another file
which you must specify. The backup will be deleted if the
compress completes successfully.

NOTE: The action will delete any file with the same name
      as the backup before starting the compression.
 

Parameters:


Database server (Input, Required, Default= none)
          The name of the database server. The server must
          be located on the same system as where the action
          is being executed. Do not specify a remote
          DirectTalk system.

Database to compress (Input, Required, Default= none)
          Either a literal value or variable with the name
          of the DirectTalk database to be compressed.
          The name must follow FAT 8.3 convention.

Backup file name (Input, Required, Default= none)
          Either a literal value or variable with the name
          of the backup file to be created before the
          compress is started. File must not already
          exist. The name must follow FAT 8.3 naming
          convention.

Number of records (Output, Required, Default= none)
          The name of a DirectTalk/NT variable where the
          action will place the number of records in the
          database. If the variable does not already
          exist, it is automatically created (in the local
          pool if the action is run from a DirectTalk
          Voice Program).
 

Return Codes:


Compress complete (Return Code=0)
          The database was successfully compressed. The
          backup file has been deleted.

DB in use or locked (Return Code=1)
          The action was unable to compress the database
          as one or more records were locked or the file
          was already in used by another process.

Error (Return Code=2)
         The action experienced an error while attempting
         to compress the database. If the error occurred
         during the compress, use the backup file to
         restore the data. Possible errors include invalid
         names and the database does not exist.
 

System Variables:


bytes_recovered (Output)
         The number of bytes recovered from the database
         compression. This number may occasionally be
         negative if a fully-optimized database is
         compressed. This small growth will not repeat if
         the file is processed additional times.
 

Comments:


It is extremely important that this action be used only
when there is absolutely NO chance that another process or
phone line would attempt to read or write to the same
database as is being compressed. The file and data in
it may be corrupted if another process attempts to read or
write to a database as it is being compressed.

YOU HAVE BEEN WARNED!!!!

Return to top of page

Return to main page


Help for Copy_Voice

Use the Copy_Voice action to copy a voice record to another
record in the same database. The action requires you to
specify the database file name, the record key of the voice
record, and the new record key.

Note: The database must exist on the same system where the
action is being executed.
 
 

Parameters:


Database server name (Input, Required, Default=none)
              The network name of the database server that
              the action uses to access the DirectTalk
              database.

File name (Input, Required, Default=none)
              The name of the DirectTalk database file
              which contains the voice record. The name
              should be the same file name that was
              used when the database was created. Long
              file names are not allowed.

Source key (Input, Required, Default=none)
              The key that identifies the voice record
              to be copied. It must not be longer than
              15 characters long.

Target key (Input, Required, Default=none)
              The key that the voice record will be
              copied to. It must not be longer than
              15 characters long.
 

Return Codes:


Voice record copied okay (Return Code=0)
              The action copied the voice record.

Record not found (Return code=1)
              The action was unable to find the source
              record to be copied. Make sure that all
              input parameters are correct.

Target exists (Return code=2)
              The action was unable to copy the record
              as the target record already exists. Make
              sure all input parameters are correct.

Error (Return code=3)
              There was some problem copying the record
              due to an incorrect parameter or the
              database does not exist.
 

Comments:


The action creates a temporary file to hold the voice record that
is being copied. There must be sufficient space on the drive
where DirectTalk for Windows NT is installed to hold this temporary
file. Under normal conditions, this file is deleted after the
voice record is copied.

Return to top of page

Return to main page

 

Help for Copy_Voice_DB

Use the Copy_Voice_DB action to copy a voice record from one
voice database to another voice database on the same system.
You must specify the source filename, target filename, and
the key for the voice record. If a record with the same name
exists in the target database, the action will not copy the
record. Delete the record in the targte database with
Delete_Voice first before copying.
 
Parameters:


Database server name (Input, Required, Default=none)
              The network name of the database server that
              the action uses to access the DirectTalk
              database.

Source filename (Input, Required, Default=none)
              The name of the DirectTalk database file
              which contains the voice record. The name
              should be the same file name that was
              used when the database was created. Long
              file names are not allowed.

Key (Input, Required, Default=none)
              The key that identifies the voice record
              to be copied. It must not be longer than
              15 characters long. The voice record in the
              target database will use this same key.

Target filename (Input, Required, Default=none)
              The name of the DirectTalk database file
              where the voice record is to be copied to.
              The name should be the same file name
              that was used when the database was created.
              Long file names are not allowed.
 
 

Return Codes:


Voice record copied okay (Return Code=0)
              The action copied the voice record from the
              source database to the target database.

Record not found (Return code=1)
              The action was unable to find the source
              record to be copied. Make sure that all
              input parameters are correct.

Target exists (Return code=2)
              The action was unable to copy the record
              as a record with the same name as the key
              already exists in the target database.

Error (Return code=3)
              There was some problem copying the record
              due to an incorrect parameter, one or both
              databases does not exist, or there was an
              internal problem with the action.
 

Comments:


The action creates a temporary file to hold the voice record that
is being copied. There must be sufficient space on the drive
where DirectTalk for Windows NT is installed to hold this temporary
file. Under normal conditions, this file is deleted after the
voice record is copied.

Return to top of page

Return to main page

 

Help for Mirror_Voice

Use the Mirror_Voice action to copy a voice record from any
voice database on the local DirectTalk system to another
voice database located on a remote DirectTalk system. You
must specify the local voice source database name, remote
target database name, remote node name, and the key for the
voice record. If a record with the same key exists in the
target database, it will be overwritten with the new voice
record.
 
Parameters:


Local database name (Input, Required, Default=none)
              The name of the DirectTalk database file
              on the local DirectTalk system which
              contains the voice record to be copied. The
              name should be the same file name that
              was used when the database was created. Long
              file names are not allowed.

Target database name (Input, Required, Default=none)
              The name of the DirectTalk database file
              on the remote DirectTalk system where the
              voice record is to be copied. The name should
              be the same file name that was used when
              the database was created. Long file names are
              not allowed. The database must exist prior to
              performing this action.

Target Node (Input, Required, Default=none)
              The network node name of the target Direct-
              Talk system where the record is to be
              copied.

Record key (Input, Required, Default=none)
              The key that identifies the voice record
              to be copied. It must not be longer than
              15 characters. The voice record in the
              target database will have this same key.
 
 

Return Codes:


Record copied (Return Code=0)
              The action copied the voice record from the
              source database to the target database on the
              remote system.

Record not found (Return code=1)
              The action was unable to find the source
              record to be copied. Make sure that all input
              parameters are correct.

Unable to connect (Return code=2)
              The action was unable to establish a path from
              the local system to the remote DirectTalk
              system.

Error (Return code=3)
              There was some problem copying the record due
              to an incorrect parameter, one or both
              databases do not exist, there was an internal
              problem with the action, or the database names
              do not meet the 8.3 FAT name rules.
 
 

System Variables:


voice_segmt_srvr
              The action uses the value in this variable as
              the network name for the local DirectTalk
              system.

kfsdtntlannum
              Set to 0, 1, 2, or 3 to specify the LAN adapter
              number to use to connect to the remote system.
              If this variable does not exist, the action
              will use LAN adapter 1. Refer to the DirectTalk
              for Windows NT Configuration Program Help for
              information on determining which LAN number to
              use.
 
 

Comments:


The action will open a path to the remote system to perform the
copy. The remote system must have an available path for a LAN-
attached client and a free path to the Telephony Server. (No
phone line is required.) The path will be freed when the action
completes.

The action creates a temporary file to hold the voice record that
is being copied. There must be sufficient space on the drive
where DirectTalk for Windows NT is installed to hold this temporary
file. Under normal conditions, this file is deleted after the
voice record is copied.

Return to top of page

Return to main page


Help for Create_Database

Use the Create_Database action to create a new DirectTalk
database. You must specify the database server, name of
the database to be created, and the desired key length and
record size of the database.
 
Parameters:


Database server name (Input, Required, Default=none)
              The network name of the DirectTalk database
              server where the action is to create the
              database.

Database name (Input, Required, Default=none)
              The name of the DirectTalk database to be
              created. The name must conform to FAT
              partition conventions of a 1 to 8 character
              name and an optional 1 to 3 character
              extension separated by a period. Long
              file names are not allowed.

Key length (Input, Required, Default=none)
              The length in characters of the key. Keys
              may be from 1 to 49 characters in length.

Record length (Input, Required, Default=none)
              The maximum length in characters for the
              record data. It may be from 1 to 4096
              characters in length.
 
 

Return Codes:


Database created (Return Code=0)
              The action created the database.

Error  (Return code=1)
              The action was unable to create the database
              due to an error. Check to verify that all
              input parameters are correct.
 

Comments:


This action does not check to see if the database already
exists with the same name. If it does, a new database
with the specified key and record lengths will be created
and the existing database, including all data it may
have contained, will be lost.

Return to top of page

Return to main page

Help for Get_Date_Diff

Use the Get_Date_Diff action to calculate the difference
between two different dates. The signed diiference will be
stored in a DirectTalk variable.
 
Parameters:


Input date 1 (Input, Required, Default=none)
              Either a literal or variable containing the
              first date in YYYYMMDD format. No checking
              on the date validity is performed.

Input date 2 (Input, Required, Default=none)
              Either a literal or variable containing the
              second date in YYYYMMDD format. No checking
              on the date validity is performed.

Output Variable(Output, Required, Default=none)
              The name of the DirectTalk variable where
              the difference is stored. If the variable
              does not exist, it will be created as a
              local variable.
 
 

Return Codes:


Computation complete (Return Code=0)
              The action has calculated the difference
              and saved the result in the Output
              variable.

Error  (Return code=1)
              The action was unable to calculate the
              difference due to some error. Make sure
              all input parameters are correct.
 

Comments:


The difference will be positive if Input date 1 is later
than Input date 2. Otherwise, the difference will be
negative.

Return to top of page

Return to main page

Help for Pad_Variable

Use Pad_Variable to pad an input string to a desired
length. You must specify whether to pad before (leading)
or after (trailing) the input string. You must specify the
desired length for the output string. You can, optionally,
specify the pad character. If not specified, leading
padding is done with zeros. Trailing padding is done with
blanks. The padded output is saved in the specified
DirectTalk variable.
 
Parameters:


Input string to pad (Input, Required, Default= none)
          Either a literal or variable containing a
          string of data (numeric or alphanumeric) to be
          padded.

Output Variable (Output, Required, Default= none)
          Name of the variable where the padded string is
          to be saved. If the variable does not exist, it
          will be created as a local variable.

Length to pad to (Input, Required, Default= none)
          Either a literal or variable containing the
          number of digits to pad the amount to. The
          minimum value is 2, the maximum is 4096 (the
          maximum size of a DirectTalk variable).

Trailing or Leading (Input, Required, Default= 'T')
          Either a literal or variable to specify whether
          leading or trailing padding is to be done. The
          first character should be either 'T' or 'L' in
          upper or lower case. 'T' will make the action
          perform trailing padding. 'L' will make the
          action perform leading padding. If the first
          character is not 'T' or 'L', the action will
          end in an error.
 

Return Codes:


Data padded okay (Return Code=0)
          The input string was padded to the desired
          length and saved in the specified variable.

Error (Return Code=1)
          The input string was not padded due to some
          error, such as the input string is already
          longer than the length to pad to or one of
          the action parameters is incorrect.
 

System Variables:


pad_var_char
          The pad character used by the action can be
          changed by setting this variable to the
          desired character. If the length of the var-
          iable contents is longer than 1, the action
          will use the first character and ignore the
          rest.
 

Comments:


none

Return to top of page

Return to main page


Help for Log_Record

Use Log_Record to write a line of data to either a
file or print a line of data on a printer. If you are
writing to a file, the data is appended to the end of the
file, if it exists. If it does not exist, the action will
create the file and them write the line of data. You may,
optionally, overwrite the file.
 
 
Parameters:


Data to be written (Input, Required, Default= none)
          Either a literal or variable containing a
          string of data (numeric or alphanumeric) to be
          written to a file or printed on a printer.

Location for writing (Input, Required, Default= 'LPT1')
          Either the filename of the file where data is to
          be written or LPT port of printer where data
          should be printed. If file is located in a
          directory other than where DirectTalk is
          installed, specify the full path name, such as:
             C:\MYDATA\IMPORTNT.DAT
          The printer port should be specified as LPT1
          to LPT9. Do not specify a colon.

File Overwrite (Input, Optional, Default = 'No')
          Any existing log file will be overwritten with a
          new file containing the data logged by this
          invocation of the action if this parameter is set
          to 'Y' or 'Yes'. Otherwise, the log data is
          appended to the existing file.

          CAUTION: If you overwite the file, any data in
          the file will be lost!!!
 

Return Codes:


Data written okay (Return Code=0)
          The data string was successfully written to
          the file or printer.

Unable to open (Return Code=1)
          The action was unable to open the file or
          printer to write to. The file may already
          be open and in use by another process or
          phone line. Your application may want to
          pause and try to perform this action again.

Error (Return Code=2)
         The action was unable to write the data or
         there was an internal error in the action.
         Make sure the printer port is valid.
 

System Variables:


none
 

Comments:


This action opens the file or printer, writes the data
specified, and then closes the file or printer.

When the action is used to print data to a printer,
each time the action is performed will cause a separate
print job to be sent to the spooler. You should configure
yoru printer not to send form feeds, otherwise each line
will be printed on a separate page. This action was
developed for use with a standard dot-matrix printer,
such as a IBM Proprinter. Using the action with a laser
printer or other printer that must print a full page at
a time may have unpredictable results.

Return to top of page

Return to main page

Help for Set_Var_Indirect

Use the Set_Var_Indirect action to assign a new value to a
variable indirectly referenced by another variable. For
example:

Set_Variable TEST = Real_Var
Set_Var_Indirect TEST = '5'

will set the variable Real_Var to the value '5'.
 

Parameters:


Target Variable (Output, Required, Default=none)
              The name of the variable to assign a value
              to. You can specify another variable or
              literal.

Value (Input, Required, Default=none)
              The data to assign to the target variable. You
              can specify another variable or literal.
 

Return Codes:


Variable set  (Return Code=0)
              The action assigned the new value to the
              variable.

Error  (Return code=1)
              There was an internal error in the action.
              Make sure the input parameters are correct.
 

Comments:


You must enclose literal data in single quotes. This
includes both character and numeric values.

The target variable may be either a global or local
variable.

If the variable does not exist in the local variable pool,
the action creates the variable as a local variable.

Return to top of page

Return to main page


Help for Get_Var_Indirect

Use the Get_Var_Indirect action to get the value of a variable
whose name is saved in another variable. For example,

Set_Variable Real_Var = 'The Data We Want'
Set_Variable TEST = 'Real_Var'

Running Get_Var_Indirect with TEST and another output variable
will set the output variable to the value 'The Data We Want'.
 

Parameters:


Source (Input, Required, Default=none)
              A variable set to the name of the second variable
              whose contents we want. If a literal is used
              here, the action will assume it is a variable
              name and directly retrive its value.

Variable for result (Output, Required, Default=none)
              The name of the variable where the action is to
              save the data found.
 

Return Codes:


Variable set  (Return Code=0)
              The action assigned the new value to the
              variable.

Error  (Return code=1)
              There was an internal error in the action.
              Make sure the input parameters are correct.
 

Comments:


You must enclose literal data in single quotes. This
includes both character and numeric values.

If the output result variable does not exist, the action
will create it in the local pool.

Return to top of page

Return to main page

 

Help for Pause_Until_Time

Use the Pause_Until_Time action to have your application
pause until the time specified. The application will
resume processing when the time specified occurs. Since
only a time can be specified, the action will not pause
the application longer than 23 hours, 59 minutes, and
59 seconds.
 
Parameters:


Time to Wait Until (Input, Required, Default=none)
              Either a variable or literal string of the
              time to pause the application until. Format
              must be in HHMMSS format where:
              HH -- hours (00 to 23)
              MM -- minutes (00 to 59)
              SS -- seconds (00 to 59)
 

Return Codes:


Time Occurred (Return Code=0)
              The time to pause until has passed

Invalid time entered (Return code=1)
              The action could not pause because the time
              specified as the input parameter was not in
              the correct HHMMSS format or represented an
              incorrect time.
 

Comments:


You must inclose literal data in single quotes.

When the action is running (ie. actually pausing), you
will not be able to quiesce the application.

This action uses the system clock to determine the current
time when the action is invoked. For best results, the
system time must be accurately set.

Return to top of page

Return to main page

 

Help for Get_Alpha_String

Use the Get_Alpha_String action to allow a caller to enter
both numeric and alphabetic characters using the telephone
key pad. You can also enter space, comma, and period. Two
keys on the phone key pad must be pressed for each letter
and/or number you wish to enter. You can also 'backspace'
to delete one or more characters that have been entered.
To improve usability, you can have the action speak eack
character back to the caller as it is entered. You can
specify the minimum number and maximum number of characters
and whether to use a termination key sequence the
application can accept from a caller.

DirectTalk automatically places each of the keys the
caller presses into a buffer. The Get_Alpha_String action
retrieves the keys from the buffer, converts the keys into
characters and places the characters in the last_dtmf_data
variable. If the buffer is empty or does not contain at
least two keys, the action will wait for the additional
keys. The application receives the keys on a first in first
out (FIFO) basis.

Get_Alpha_String converts pairs of tones entered to charac-
ters as follows:

o The first tone identifys the set of three letters you are
  entering. For example, a 2 would mean either A, B, or C.
  The number 7 would mean either P, R, or S. The set of
  letters correspond to the letters printed on the phone
  keypad.

o The second tone is always * (star), 0 (zero), or # (pound
  or hash). It select the specific letter from the set of
  three keys. * selects the left or first letter. 0 selects
  the second or middle letter. # selects the rightmost or
  third letter. So, 2* is A, 20 is B, and 2# is C.

o The two letters not located on phone keypads, Q and Z,
  are 1* and 10, respectively.

o Numbers are entered by sending the desired number twice.
  To enter a 4, press the 4 key twice.

o Invalid key combinations cause an appropriate message to
  be spoken and the invalid combination is ignored.

o In addition to letters and numbers, the following charac-
  ters can be entered:

  comma  (,) - 0#
  period (.) - 0*
  space  ( ) - 1#

o Character data is placed in the system variable,
  last_dtmf_data, in lower case. Data can be placed in the
  variable in upper case by setting the variable
  alpha_to_upper to 'Y' prior to executing this action.

The caller can delete one or more characters entered by
entering the star key twice (**). This combination acts as
a 'backspace' key and deletes the last character. By
sucessively entering **, you can backspace and delete the
entire entry, if desired. Appropriate messages are
spoken during this process.
 

Parameters:


Minimum characters (Input, Required, Default='1')
          The minimum number of characters the caller
          can enter.

Maximum characters (Input, Required, Default='8')
          The maximum number of characters the caller can
          press. The maximum must be equal to or greater
          than the minimum characters parameter. If the
          maximum equals the minimum and you did not
          specify to use the termination string (##),
          the action returns after the caller enters this
          exact number of characters.

Use Termination character (Input, Required, Default='Y')
          Determines whether the action will accept and act
          on the termination key sequence (##). Pressing
          this sequence will signify the end of entry by
          the caller if used (set to 'Y'). If you specify
          to use the termination key sequence, the action
          does not return a return code until the caller
          presses the termination key sequence or a time out
          occurs, regardless of the maximum and minimum
          characters you specify. If you do not specify to
          use the termination key sequence, the action uses
          an implicit termination when the caller presses
          the maximum number of keys.

Speak each character as entered(Input, Required,
                                           Default='Y')
          Determines whether the action will speak each
          character as the caller enters each pair of
          tones. Setting this to 'Y' will cause the
          action to speak each letter or number as it is
          entered. This provides immediate feedback to
          the caller and allows them to correct any
          incorrect entries using the backspace function.

Return Codes:

Characters okay (Return Code=0)
          The caller entered a string of characters which
          satisfy the parameters you specified. The action
          assigns the characters the caller entered to
          the last_dtmf_data system variable.

Too few characters (Return Code=1)
          The caller entered less than the minimum number
          of characters and then pressed the termination
          key sequence. The action returns this return
          code only if the caller completes a selection
          with the termination key sequence. The action
          assigns the characters the caller entered (up to
          the point of pressing the termination key
          sequence) to the last_dtmf_data system variable.
          If you did not specify to use the termination key
          sequence or if the caller did not press the
          termination key sequence, the action returns the
          Time out return code.

Too many characters (Return Code=2)
          The caller pressed more than the maximum number of
          characters, followed by the termination key
          sequence. The action assigns the values to the
          system variables in the same way as return code 1,
          Too few characters.

Invalid Input (Return Code=3)
          One of the input parameters was incorrect. Either
          the minimum characters was greater than maximum
          characters or one of the other parameters was
          something other than 'Y' or 'N'.

Time out (Return Code=T1)
          The caller did not satisfy the parameters for the
          action within the time limit. A pair of tones
          corresponding to a single number, letter, or
          action must be entered within the time limit. The
          time limit is reset after each pair of tones is
          entered.

          The last voice logic module (Play_Module action)
          that ran defines the time limit. When the time
          limit expires, the action returns this return code
          and sets the timeout_flag system variable to '1'.
          The action places all the characters the caller
          has entered prior to the time out in the
          last_dtmf_data system variable. You can use step
          -1 to repeat the previous voice logic module that
          was played. When this action is rerun, it resets
          both these variables.

Last repeat (Return Code=T2)
          The action prompted (Play_Module action) the
          caller several times, but the caller did not
          respond completely. The voice logic module defines
          the number of times the caller can be prompted
          before the action returns this return code. The
          action places all the characters the caller
          entered prior to the point this action returned
          this return code in the last_dtmf_data system
          variable.

Caller hung up (Return Code=HUP)
          The caller hung up the telephone.
 

System Variables:


last_dtmf_data (Output)
          The character string as entered by the caller,
          except the termination or backspace key
          sequences, up to the point the action returned a
          return code. The action resets this variable to
          a null value each time the action runs.

timeout_flag (Output)
          The action sets this variable to '1' when the
          action returns the timeout return code. The action
          resets this variable to '0' when the action waits
          for input.

          You can use a special state number (-1) with the
          timeout return code. This state number takes the
          application to the last Play_Module action run
          before this action. The action can then replay a
          prompt to the caller when the caller does not
          respond completely.

alpha_to_upper (Input)
          If set to 'Y', data placed in the system variable
          last_dtmf_data will be in upper case. Otherwise,
          data is placed in last_dtmf_data as lower case.
 

Comments:


There may be an instance in the application where, before
this action, you want to clear the digits in the buffer
using the Clear_Tones action. This may be useful when the
caller makes an invalid selection and the action will
reprompt the caller to press the selection. In addition,
some DirectTalk actions, such as Play_Module, detect tones
but do not retrieve the keys. You may want to follow those
actions with this action once those actions detect keys the
caller pressed.

The following voice segments must be added to the SYSTM
voice segment file for each language running on the
system:

Segment Name      Text
-----------------------------------------------------------
 $$space          "space"
 $$comma          "comma"
 $$period         "period"
 $$no_data        "There are no characters to delete"
 $$char_del       "The last character has been deleted"
 $$invalid_keys   "That is not a valid key combination.
                   Please try again."

Return to top of page

Return to main page

 

Help for Play_Voice_Ext

Play_Voice_Ext is used to play a voice record. It provides
extended function, allowing the caller to pause the play-
back of the segment, rewind or fast forward within the
voice record, and resume the playback from any point.
Functions are done by pressing the following specified keys
on the telephone during the action:

Default
 DTMF
 Key        Operation Description
===========================================================
  2   Pause key - If the record is playing, stops playback.
      To resume playback, press this key again.

  1   Rewind key - If the playback is stopped, each time
      this key is pressed, the voice record starting point
      for resuming playback will be backed up by approxi-
      mately 1.5 seconds. This allows you to listen again to
      portions of the voice record that have already been
      played. If the key is pressed when playback is not
      stopped, playback is stopped and the voice record
      starting point is immediately backed up by 1.5
      seconds. The action will beep if you press the key and
      the beginning of the voice record has been reached.
      A larger increment for each key press can be speci-
      fied by using the PVEadjust system variable.

  3   Fast forward key - If the playback is stopped, each
      time this key is pressed, the voice record starting
      point for resuming playback will be advanced by
      approximately 1.5 seconds. This allows you to skip
      over portions of the voice record without listening to
      them. If the key is pressed when playback is not
      stopped, playback is stopped and the voice record
      starting point is immediately advanced by 1.5
      seconds. The action will beep if you press the key and
      the end of the voice record has been reached. A larger
      increment for each key press can be specified by using
      the PVEadjust system variable.

You may change the DTMF keys used for the operation via the
a special procedure. See Comments below.

Pressing any DTMF key which is not assigned to an operation
will immediately stop the action. The key pressed is
saved in last_dtmf_tone and "Key pressed" is returned to
the application.
 

Parameters:


Database server (Input, Required, Default= none)
          The network name of the database server.

File name (Input, Required, Default= none)
          Either a literal value or variable with the name
          of the voice database containing the voice record
          to be played. Use the same file name that was used
          when the database was created.

Record key (Input, Required, Default= none)
          Either a literal value or variable with the key
          used to retrieve the voice record. The length of
          the key can be up to 15 characters.

Wait for key time (Input, Required, Default= '10')
          Either a literal value or variable with the
          number of seconds to wait for each key once the
          playback of the record has been stopped. If
          no key is detected within that time, the Timeout
          code is returned. To have the action wait
          indefinitely, set this parameter to '0'.
 
 

Return Codes:


Play done (Return Code=0)
          The action played the complete voice record.

Key pressed (Return Code=1)
          The caller pressed a key other than those above
          and playback was interrupted. The key that was
          pressed is removed from the buffer and is placed
          in the system variable, last_dtmf_tone.

Error (Return Code=2)
         There was some type of problem during the play-
         back of the voice record. One of the input
         parameters may be incorrect. If you have speci-
         fied different keys via PLYVCEXT.KEY, the for-
         mat of the file may be incorrect or there is
         some other problem.
 
 

System Variables:


PVEadjust (input)
        Setting this variable to a integer between 1 and 99
        allows you to specify a larger increment for both
        the rewind and fast forward functions. This value is
        multiplied by the standard 1.5 second increment to
        derive the new increment. A PVEadjust value of 1
        would have no effect, a value of 99 would make the
        increment about 150 seconds. The calculated value is
        approximate and the actual value may differ
        slightly.
 
 

Comments:


o The action requires that the system variable,
  voice_language, be set to a language valid for the system.

o The action uses the voice segment, Edit_Tone, located in
  the SYSTM segment file for the current language to play
  the warning beep.

o Due to how DirectTalk stores voice records, the exact
  amount of time the voice record is backed up or advanced
  is only approximate but will be about 1.5 seconds. The
  margin of error may increase as larger increments are used
  be specifying values for PVEadjust.
 

Key Redefinition
You may change the DTMF keys used for the three operations
via the following procedure:

1) Create a file, PLYVCEXT.KEY, and place it in the same
directory as where DirectTalk/2 is installed.

2) Add a line for each operation whose DTMF key you wish to
change. Each line shall have the operation and the desired
DTMF key. Any valid DTMF key (0 to 9, *, #, A to D) can be
used. For example, to change the operation of the action to
use 4 for rewind, 5 for pause, and 6 for fast-forward, the
contents of PLYVCEXT.KEY would contain:
Pause 5
Rewind 4
Fastforward 6

The operation can be abbreviated as 'P', 'R', and 'F'.
There cannot be any other data in the file. There must be a
blank between the operation and the desired DTMF key. You
need only define those keys you wish to change from the
defaults. Make sure that each operation has a unique key
defined.

3) Stop and restart any DirectTalk applications using
the action to put the change into effect.

Return to top of page

Return to main page

 

Help for Load_Variables

Load_Variables is used to create and/or initialize one
or more DirectTalk variables. The action will read an
input file which is in the same format as an application
control (<appl>.CTL) or setup (<appl>.SU) file. Each
variable in the file will be set to the corresponding value
as shown in the file. If the variable does not exist, it
will be created.

The input file may contain comment lines. Comments lines
must contain an asterisk as the first character in the
line.

If the input file is located in another directory from
where DirectTalk is installed (x:\DTALK), the full
path name must be specified. (E:\DATA\APPL.VAR)

Long file names for the input file are not supported.
 
 

Parameters:
File name (Input, Required, Default = none)
          Either a literal value or variable with the name
          of the input file to be read by the action. This
          data in the format must be the same as an
          application control or setup file.

Local or Global (Input, Required, Default = 'G')
          Specifies which variable pool to use when creating
          new variables. This parameter must be either a
          a literal value or variable containing the word
          "Global" or "Local". This parameter may be
          abbreviated as 'G' or 'L'.

          Note: This parameter is only applicable to
          DirectTalk voice programs and has no effect on
          programs written using T-Rexx.
 
 

Return Codes:


Variables loaded (Return Code=0)
          The action loaded all variables in the input file.

Error (Return Code=1)
          The action was unable to load all variables in the
          input file. The file may not exist or its format
          may not be correct.
 
 

System Variables:


None.
 

Comments:


None

Return to top of page

Return to main page

 

Help for Get_Mailbox_Data

Note: This action is only available on OS/2.

Get_Mailbox_Data is used to check how many messages are stored in a DirectTalk voice messaging mailbox. The action returns information quantatively as action parameters (new messages, old messages, maximum allowed messages), and qualitatively as return codes (whether any new messages are stored, and whether the mailbox is full). If any output variable does not exist, the action will create it in the local pool.
Parameters:

Mailbox Number (Input, Required, Default = none)  Either a literal value or variable with the number f the mailbox to be checked. The default is the name of the local variable which is created by the application control or setup file.

Local or Global (Input, Required, Default = 'G')  Specifies which variable pool to use when creating   new variables. This parameter must be either a literal value or variable containing the word "Global" or "Local". This parameter may be abbreviated as 'G' or 'L'.

Note: This parameter is only applicable to DirectTalk voice programs and has no effect on programs written using T-Rexx.

Return Codes:


Variables loaded (Return Code=0)
          The action loaded all variables in the input file.

Error (Return Code=1)
          The action was unable to load all variables in the
          input file. The file may not exist or its format
          may not be correct.
 
 

System Variables:


None.
 

Comments:


None

Return to top of page

Return to main page