Digital PDFs

AA-LA71A-TE

December 1988

63 pages

Original

1.8MB

Document:	VMS 5.0 RTL DECtalk DTK$ Manual 198804
Order Number:	AA-LA71A-TE
Revision:
Pages:	63
Original Filename:	http://bitsavers.org/pdf/dec/vax/vms/5.0/AA-LA71A-TE_VMS_5.0_RTL_DECtalk_DTK$_Manual_198804.pdf

OCR Text

VMS

digit a I

VMS RTL DECtalk (DTK$) Manual

Order Number AA-LA71 A-TE

VMS RTL DECtalk
(DTK$) Manual
Order Number: AA-LA 7 1A-TE

April 1988
This manual documents the DECtalk support routines contained in the
DTK$ facility of the VMS Run-Time Library.

Revision/Update Information:

This document supersedes Section 11
and the DTK$ portion of Part II of the
VAX/VMS Run- Time Library Routines
Reference Manual, Version 4.4.

Software Version:

VMS Version 5.0

digital equipment corporation
maynard, massachusetts

April 1988
The information in this document is subject to change without notice and should
not be construed as a commitment by Digital Equipment Corporation. Digital
Equipment Corporation assumes no responsibility for any errors that may appear
in this document.
The software described in this document is furnished under a license and may be
used or copied only in accordance with the terms of such license.
No responsibility is assumed for the use or reliability of software on equipment
that is not supplied by Digital Equipment Corporation or its affiliated companies.
Copyright © 1988 by Digital Equipment Corporation
All Rights Reserved.
Printed in U.S.A.
The postpaid READER'S COMMENTS form on the last page of this document
requests the user's critical evaluation to assist in preparing future documentation.
The following are trademarks of Digital Equipment Corporation:
DEC
DEC/CMS
DEC/MMS
DECnet
DECsystem-10
DECSYSTEM-20
DECUS
DECwriter

DIBOL
EduSystem
IAS
MASSBUS
PDP
PDT
RSTS
RSX

UNIBUS
VAX
VAXcluster
VMS
VT

~U~UIJ~DTM
ZK4614

HOW TO ORDER ADDITIONAL DOCUMENTATION
DIRECT MAIL ORDERS
USA & PUERTO Rico*

CANADA

INTERNATIONAL

Digital Equipment Corporation
P.O. Box CS2008
Nashua, New Hampshire
03061

Digital Equipment
of Canada Ltd.
100 Herzberg Road
Kanata, Ontario K2K 2A6
Attn: Direct Order Desk

Digital Equipment Corporation
PSG Business Manager
c/o Digital~ local subsidiary
or approved distributor

In Continental USA and Puerto Rico call 800-258-1710.
In New Hampshire, Alaska, and Hawaii call 603-884-6660.
In Canada call 800-267-6215.
*Any prepaid order from Puerto Rico must be placed with the local Digital subsidiary (809-754-7575).
Internal orders should be placed through the Software Distribution Center (SOC), Digital Equipment
Corporation, Westminster, Massachusetts 01473.

Production Note
This book was produced with the VAX DOCUMENT electronic publishing
system, a software tool developed and sold by DIGITAL. In this system,
writers use an ASCII text editor to create source files containing text and
English-like code; this code labels the structural elements of the document,
such as chapters, paragraphs, and tables. The VAX DOCUMENT software,
which runs on the VMS operating system, interprets the code to format the
text, generate a table of contents and index, and paginate the entire document.
Writers can print the document on the terminal or line printer, or they can use
DIGITAL-supported devices, such as the LN03 laser printer and PostScript®
printers (PrintServer 40 or LN03R ScriptPrinter), to produce a typeset-quality
copy containing integrated graphics.

PostScript is a trademark of Adobe Systems, Inc.

Contents
vii

PREFACE

CHAPTER 1 DECTALK GUIDELINES

1-1

1.1

OVERVIEW OF THE DTK$ FACILITY

1-1

1.2
1.2.1
1.2.2
1.2.3
1.2.4
1.2.5
1.2.6

CONTROLLING THE DECTALK ENVIRONMENT
Initializing DECtalk
The DECtalk Device
The Terminal
The Index
The Dictionary
Terminating DECtalk

1-1
1-1
1-1
1-2
1-4
1-4
1-4

1.3

CONTROLLING DECTALK'S SPEECH

1-4

1.4
1.4.1
1.4.2
1.4.3

CONTROLLING DECTALK FOR TELEPHONE USE
The Telephone Keypad
Input Using the Telephone Keypad
Controlling the Telephone Functions

1-5
1-5
1-5
1-5

1.5

EXIT HANDLERS

1-6

DTK$ REFERENCE SECTION
DTK$ANSWER_PHONE
DTK$CHECK_HDWR_STATUS
DTK$DIAL_PHONE
DTK$HANGUP_PHONE
DTK$1NITIALIZE
DTK$LOAD_DICTIONARY
DTK$READ_KEYSTROKE
DTK$READ_STRING
DTK$RETURN_LAST_INDEX
DTK$SET_INDEX

DTK-3
DTK-5
DTK-7
DTK-9
DTK-10
DTK-12
DTK-14
DTK-16
DTK-18
DTK-19
v

Contents

DTK$SET_KEYPAO_MQDE
DTK$SET_LQGGING_MODE
DTK$SET_MQDE
DTK$SET_SPEECH_MQDE
DTK$SET_TERMINAL_MQDE
DTK$SET_VQICE
DTK$SPEAK_FILE
DTK$SPEAK_PHONEMIC_TEXT
DTK$SPEAK_TEXT
DTK$SPELL_TEXT
DTK$TERMINATE

INDEX

DTK-20
DTK-22
DTK-25
DTK-27
DTK-29
DTK-31
DTK-33
DTK-35
DTK-37
DTK-39
DTK-41

Preface
This manual provides users of the VMS operating system with detailed usage
and reference information on DECtalk support routines supplied in the DTK$
facility of the Run-Time Library.
Run-Time Library routines can only be used in programs written in languages
that produce native code for the VAX hardware. At present, these languages
include VAX MACRO and the following compiled high-level languages:
VAX Ada
VAX BASIC
VAX BLISS-32
VAXC
VAX COBOL
VAX COBOL-74
VAX CORAL
VAX DIBOL
VAX FORTRAN
VAX Pascal
VAX PL/I
VAX RPG
VAX SCAN
Interpreted languages which can also access Run-Time Library routines
include VAX DSM and DATATRIEVE.

Intended Audience
This manual is intended for system and applications programmers who want
to call Run-Time Library routines.

Document Structure
This manual is organized into two parts as follows:
•

Chapter 1 provides guidelines on using the DTK$ DECtalk routines.

•

The DTK$ Reference Section provides detailed reference information on
each DECtalk support routine contained in the DTK$ facility of the RunTime Library. This information is presented using the documentation
format described in the Introduction to the VMS Run-Time Library. Routine
descriptions appear in alphabetical order by routine name.

vii

Preface

Associated Documents
The Run-Time Library routines are documented in a series of reference
manuals. This manual provides an overview of the VMS Run-Time Library
DECtalk (DTK$) facility, along with detailed information on each DTK$
routine. A general overview of the VMS Run-Time Library is presented in
the Introduction to the VMS Run-Time Library. Descriptions of the other RTL
facilities and their corresponding routines and usages are discussed in the
following books:
•

The VMS RTL Library (LIB$) Manual

•

The VMS RTL Mathematics (MTH$) Manual

•

The VMS RTL General Purpose (OTS$) Manual

•

The VMS RTL Parallel Processing (PPL$) Manual

•

The VMS RTL Screen Management (SMG$) Manual

•

The VMS RTL String Manipulation (STR$) Manual

The VAX Procedure Calling and Condition Handling Standard, which is
documented in the Introduction to System Routines, contains useful information
for anyone who wants to call Run-Time Library routines.
Applications programmers of any language may refer to the Guide to Creating
VMS Modular Procedures for the Modular Programming Standard and other
guidelines.
High-level language programmers will find additional information about
calling Run-Time Library routines in their language reference manual.
Additional information may also be found in the language user's guide
provided with your VAX language.
The Guide to Using VMS Command Procedures may also be useful.
For a complete list and description of the manuals in the VMS documentation
set, see the Overview of VMS Documentation.

viii

Preface

Conventions
Convention

Meaning
In examples, a key name (usually abbreviated)
shown within a box indicates that you press
a key on the keyboard; in text, a key name is
not enclosed in a box. In this example, the key
is the RETURN key. (Note that the RETURN
key is not usually shown in syntax statements
or in all examples; however, assume that you
must press the RETURN key after entering a
command or responding to a prompt.)

CTRL/C

A key combination, shown in uppercase with a
slash separating two key names, indicates that
you hold down the first key while you press the
second key. For example, the key combination
CTRL/C indicates that you hold down the key
labeled CTRL while you press the key labeled C.
In examples, a key combination is enclosed in a
box.

$SHOW TIME
05-JUN-1988 11 :55:22

In examples, system output (what the system
displays) is shown in black. User input (what
you enter) is shown in red.

$TYPE MYFILE.DAT

In examples, a vertical series of periods, or
ellipsis, means either that not all the data that
the system would display in response to a
command is shown or that not all the data a
user would enter is shown.

input-file, ...

In examples, a horizontal ellipsis indicates
that additional parameters, values, or other
information can be entered, that preceding
items can be repeated one or more times, or
that optional arguments in a statement have
been omitted.

[logical-name]

Brackets indicate that the enclosed item is
optional. (Brackets are not, however, optional
in the syntax of a directory name in a file
specification or in the syntax of a substring
specification in an assignment statement.)

quotation marks
apostrophes

The term quotation marks is used to refer
to double quotation marks (" ). The term
apostrophe ( ' ) is used to refer to a single
quotation mark.

Other conventions used in the documentation of Run-Time Library routines
are described in the Introduction to the VMS Run-Time Library.

DECtalk Guidelines

This section discusses the Run-Time Library routines that control and perform
various functions on DIGITAL's DECtalk device. The DECtalk routines are
meant solely for use with DIGITAL's DECtalk device.

1 .1

Overview of the DTK$ Facility
The DECtalk device accepts alphanumeric text from a computer system and
converts it to human-quality speech. DECtalk speaks this data through its
internal speaker, an external audio system, or over the telephone.
The DTK$ Facility consists of routines that control the functions of the
DECtalk device. These routines not only control DECtalk's characteristics, but
they also provide functional controls such as reading keys entered on a phone
keypad or hanging up the phone. In general, the DTK$ routines supply a
simple interface between the user and the DECtalk device.

1 .2

Controlling the DECtalk Environment
The DTK$ facility supplies several routines that control the environment in
which the DECtalk device functions. These routines are grouped according to
function and described in the following subsections.

1.2.1

Initializing DECtalk
Before issuing any commands to the DECtalk device, you must first initialize
it. The routine DTK$INITIALIZE initializes a DECtalk device and returns
its associated voice identifier. This routine also specifies a file specification
or logical name to which the output associated with the DECtalk device is
written.

1.2.2

The DECtalk Device
Once a DECtalk device has been initialized, you can select various operating
modes for the device. One of these modes involves the specification of
phonemic text; a phoneme is one of the smallest possible units of speech that
can be used to distinguish one word from another.
DTK$SET_MODE enables you to select any operating mode for DECtalk. The
DTK$SET_MODE routine controls how DECtalk processes text, according to
the modes in the following list. Note that it is possible to perform a logical
OR operation to set more than one mode at a time, and any mode that is not
specified is reset.
•

DTK$M_SQUARE treats square brackets ( []) as phonemic text delimiters.
The DTK$M_SQUARE mode also lets the close parenthesis character")",
when it appears before a word, indicate an alternative pronunciation from
the built-in dictionary.
1-1

DECtalk Guidelines

•

DTK$M-ASCII uses single-character phonemic translation instead of a
multiletter translation. This is valid only for the DTCOl device.

•

DTK$M_MINUS pronounces a hyphen ( - ) as "minus."

•

DTK$M_EUROPE uses European number format (where a comma
separates the number from its decimal portion and periods mark off digits
into groups of 3). This is valid only for the DTC03 device.

•

DTK$M_SPELL spells out all text instead of interpreting the text as
words. This is valid only for the DTC03 device.

DTK$SET_MODE can be used to set new modes, to examine the current
mode settings, or to change the modes and later return them to their previous
state.
The DTK$SET_SPEECH_MODE routine toggles DECtalk's speech on and off.
In the case of turning the speech off, you can either cause DECtalk to stop
speaking immediately or to stop speaking when the current text is completed.
DTK$SET_VOICE controls the actual voice characteristics of the DECtalk
device. The following is a list of the available voice mode settings for
DECtalk, along with their characteristics.
Voice Mode

Characteristics

DTK$K_VOICE_MALE

Standard male voice

DTK$K_VOICE_FEMALE

Standard female voice

DTK$K_VOICE_CHILD

Standard child voice

DTK$K_VQICE_DEEP_MALE

Deep male voice

DTK$K_VOICE_DEEP_FEMALE

Deep female voice

DTK$K_VOICE_OLDER_MALE

Older male voice

DTK$K_VQICE_LIGHT_FEMALE

Light female voice

The DTK$SET_VOICE routine also enables you to control DECtalk's speech
rate, as well as the length of the pauses after commas and periods. The
speech rate of the DECtalk device is measured in words per minute, and
the valid range is 120 to 350 words per minute. The values that control the
comma and period pauses are measured in milliseconds.

1.2.3

The Terminal
The DECtalk device enables you to connect a local terminal to the DECtalk
device. The DTK$ facility supplies two routines that you can use to control
the local terminal.
The DTK$SET_LOGGING_MODE routine determines the information that
is displayed on the local terminal connected to the DECtalk device. The
following is a list of modes that can be set or reset using
DTK$SET_LOGGING_MODE. Note that you can perform a logical OR
operation to set more than one mode at a time, and any mode not specified is
reset.
•

1-2

DTK$M_TEXT causes all spoken text to be printed on the terminal.

DECtalk Guidelines

•

DTK$M_pHONEME causes all spoken text to be converted to its
phonemic equivalent and then printed on the terminal.

•

DTK$M_RAWHOST causes all data received from the host to be
transmitted, including escape sequences, to the terminal in exactly the
form in which it is received.

•

DTK$M-1NHOST causes all text received from the host to be printed,
including escape sequences, on the terminal. However, all control
characters are first translated to a readable form.

•

DTK$M_OUTHOST causes all characters sent to the host to be printed
at the terminal. Before printing, control characters are converted to
a readable form. This readable form is sometimes a mnemonic (for
example, ESC for escape) and sometimes a letter that has meaning when
used with the CTRL key (for example, C for CTRL/C).

•

DTK$M_ERROR causes all DECtalk error messages to be printed on the
terminal.

•

DTK$M_TRACE causes all text received from the host to be printed on
the terminal, including escape sequences. However, the escape sequences
are first converted into their symbolic meaning before being printed.

The routine DTK$SET_TERMINAL_MODE controls the attributes of the
local terminal. This routine can be used to set new modes, to examine the
current mode settings, or to change the modes and later return them to their
previous state. All of the following modes are valid.
DTK$M_HOST

·when set, any characters typed on the local terminal are
transmitted to the host computer.

DTK$M_SPEAK

When set, characters typed on the local terminal are
spoken by DECtalk. (Note that they will be interspersed
with characters sent from the host.)

DTK$M_EDITED

When set, text entered from the local terminal is processed
one line at a time.

DTK$M_HARD

When set, text is echoed on the local terminal in a manner
appropriate for hardcopy terminals. When this mode is not
set, echoing is performed in a manner appropriate for video
display terminals.

DTK$M_SETUP

When set, DECtalk speaks the set-up dialogue.

DTK$M_FILTER

When set, DECtalk does not transmit DECtalk-specific
escape sequences to the local terminal. DECtalk also
ignores most non-DECtalk escape sequences transmitted
from the host computer.

Once again, it is possible to perform a logical OR operation to set more than
one mode at a time. Any mode that is not specified is automatically reset.

1-3

DECtalk Guidelines
1 .2 Controlling the DECtalk Environment

1.2.4

The Index
When DECtalk speaks text, the speech rate for the device is much slower
than the rate of data transmission. This may create a problem if a certain
task in your program is contingent upon certain speech being complete. For
example, it is quite likely that the DECtalk device will still be speaking some
text while your program is already executing the next statement. The DTK$
facility therefore provides you with indexes. An index is a number that you
insert at an appropriate location in your text. Once DECtalk finishes speaking
all text up to that index, the index value is returned to your program. Using
this index, your program can then keep track of text that has already been
spoken.
An index could be inserted, for example, following some instructional text
regarding user input. Once DECtalk speaks the instructional text, it returns
the index to the program, and this triggers the program to wait for the user's
input. You can set an index using the DTK$SET-1NDEX routine. The index
value must be in the range of 1 to 32767. The DTK$RETURN _LAST_INDEX
routine returns the last index spoken.

1.2.5

The Dictionary
DECtalk comes equipped with two dictionaries. The first of these is stored
in ROM and therefore cannot be changed in any way. A certain amount of
dynamic storage is allocated for a supplemental dictionary to which you can
add your own words and pronunciations.
To load a word into this supplemental dictionary, you use the
DTK$LOAD_DICTIONARY routine. By specifying both the actual spelling
of the word and its phonemic definition, you create a new entry in the
supplemental dictionary.

1.2.6

Terminating DECtalk
To deassign the voice identifier that was assigned to the DECtalk device when
it was initialized, you must call DTK$TERMINATE. This routine terminates
all use of the specified DECtalk device by deallocating the voice control block
and all of its substructures.

1.3

Controlling DECtalk's Speech
The DTK$ facility provides three different methods for specifying the text that
DECtalk is to speak.
DTK$SPEAK_TEXT sends the specified text to the DECtalk device to be
spoken. You can optionally set one of the following modes:

1-4

•

DTK$K_IMMED returns control to the user immediately (this is the
default).

•

DTK$K_WAIT waits until the text is completely spoken before returning
control to the user.

•

DTK$K_STATUS waits until the text is completely spoken, and then
returns a phone status.

DECtalk Guidelines
1.3 Controlling DECtalk's Speech

These modes can be set for DTK$SPEAK_FILE, which speaks the text
contained in a specified file, and also for DTK$SPEAKJHONEMIC_TEXT.
This routine sends the specified phonemic text to the DECtalk device to be
spoken. Phonemic text contains the phonemic representations of the words
to be spoken; that is, the words are spelled as they are pronounced.

1 .4

Controlling DECtalk for Telephone Use
One of the most common applications for DECtalk is to serve as an access
to a remote database via the telephone. The DTK$ facility therefore supplies
several routines that improve the interface between DECtalk and the user.

1.4.1

The Telephone Keypad
The routine DTK$SET_KEYPAD_MODE enables and disables DECtalk's
recognition of the telephone keypad. If keypad recognition is enabled with
autostop, DECtalk stops speaking when a terminator is entered. Otherwise,
keypad recognition is disabled immediately.

1.4.2

Input Using the Telephone Keypad
The routine DTK$READ_KEYSTROKE reads a key entered on the telephone
keypad and returns that key's equivalent key code value. These key codes
are in the form DTK$K_TRM_xxxx, and they are defined in the DIGITAL
supplied library $DTKDEF. The optional prompt argument enables you to
specify some text that DECtalk speaks before waiting for input. The timeout
argument controls the number of seconds that DECtalk waits for input.
DTK$READ_STRING reads a series of keys entered on a telephone keypad
and returns the key series as a single string. Again, you can specify
an optional prompt and a timeout value for this routine. The optional
termination code argument returns the key code value of the terminating key
entered.

1.4.3

Controlling the Telephone Functions
In addition to accepting user input, the DTK$ facility also supplies routines
that control the actual operation of the telephone.
DTK$ANSWER_PHONE waits for the phone connected to the DECtalk
device to ring and then answers it. You can specify optional text that DECtalk
speaks after answering the phone. The DTK$ facility also supplies a routine
for hanging up the phone: DTK$HANGUP_PHONE. This routine speaks an
optional message (if specified) and then hangs up the phone.
DTK$DIAL_PHONE dials the specified number on the telephone. You can
select either pulse dialing or tone dialing with the mode argument for this
routine, and you can specify how many seconds DECtalk should wait for the
phone to be answered. The text argument enables you to specify optional text
that DECtalk speaks after the phone is answered.

1-5

DECtalk Guidelines
1 . 5 Exit Handlers

1 .5

Exit Handlers
The DTK$ facility supplies its own exit handler to terminate access to the
DECtalk device. This exit handler hangs up the phone and resets any
terminal characteristics changed by the DTK$ facility. Users must not call
any of the DTK$ routines from within their own exit handlers.

1-6

DTK$ Reference Section
This section provides detailed discussions of the routines provided by the
VMS RTL DECtalk (DTK$) Facility.

DTK$ANSWER_PHONE

DTK$ANSWER_PHONE Wait for Phone to Ring
and Answer
The Wait for Phone to Ring and Answer routine waits for the phone
connected to the DECtalk device to ring and then answers it.

FORMAT

DTK$ANSWER_PHONE

RETURNS

VMS usage:
type:
access:
mechanism:

ARGUMENTS

voice-id [,number-of-rings}
[,text]{, timeout]

cond_value
longword (unsigned)
write only
by value

voice-id
VMS usage:
type:
access:
mechanism:

identifier
longword (unsigned)
read only
by reference

Voice identifier of the DECtalk device. The voice-id argument is the address
of an unsigned longword containing this identifier. The voice identifier is
returned by the DTK$INITIALIZE routine.

number-of-rings
VMS usage:
type:
access:
mechanism:

longword_signed
longword (signed)
read only
by reference

Number of rings DECtalk waits for before answering the phone. The optional
number-of-rings argument is the address of a signed longword containing
this number. The default is 1 ring.

text
VMS usage:
type:
access:
mechanism:

char_string
character string
read only
by descriptor

Text that DECtalk speaks after answering the phone. The optional text
argument is the address of a descriptor pointing to the text.

timeout
VMS usage:
type:
access:
mechanism:

longword_signed
longword (signed)
read only
by reference

DTK-3

DTK$ANSWER_PHONE

Number of seconds that DECtalk allows the phone to ring before answering.
The optional timeout argument is the address of a signed longword
containing this timeout value. There is no default value.

DESCRIPTION

CONDITION
VALUES
RETURNED

DTK-4

DTK$ANSWER_pHQNE waits for the phone connected to the DECtalk
device to ring and then answers it. If the number-of-rings argument is not
specified, DECtalk answers the phone after 1 ring. If both the number-ofrings argument and the timeout argument are specified, DECtalk answers the
phone after the first argument occurs. For example, if you specify 2 rings and
30 seconds, DECtalk will answer after 2 rings. After the phone is answered,
DECtalk speaks any optional text that you specified.

SS$_NORMAL

Normal successful completion.

SS$_xxxx

Any condition value returned by $QIOW.

DTK$_1NVVOllD

Invalid voice-id.

DTK$_WRONUMARG

Wrong number of arguments.

DTK$CHECK_HDWR_STATUS

DTK$CHECK_HDWR_STATUS Check Hardware
Status
The Check Hardware Status routine checks the DECtalk hardware for
hardware malfunctions.

FORMAT

DTK$CHECK_HDWR_STATUS

RETURNS

VMS usage:
type:
access:
mechanism:

ARGUMENTS

voice-id ,hdwr-status

cond_value
longword (unsigned)
write only
by value

voice-id
VMS usage:
type:
access:
mechanism:

identifier
longword (unsigned)
read only
by reference

Voice identifier of the DECtalk device. The voice-id argument is the address
of an unsigned longword containing this identifier. The voice identifier is
returned by the DTK$INITIALIZE routine.

hdwr-status
VMS usage:
type:
access:
mechanism:

mask_longword
longword (unsigned)
write only
by reference

Receives the hardware status of the DECtalk machine. The hdwr-status
argument is the address of an unsigned longword bit mask that receives the
status.
Valid values for hdwr-status are:
DTK$_NOMALFUN 1

No malfunctions on first test

DTK$_NOMALFUN2

No malfunctions on second test

DTK$_COMFAIL

Communication failure

DTK$_1NPBUFOVR

Input buffer overflow

DTK$_NVROPRFAI

NVR operation failed

DTK$_ERRPHOTRA

Phonemic transmission error

DTK$_CONSEOERR

Control sequence error

DTK$_DECTSFAI

Self-test failed

DTK-5

DTK$CHECK_HDWR_STATUS

DESCRIPTION

The DTK$CHECK-8DWR_STATUS routine checks the DECtalk hardware
(described by the voice-id argument) for hardware malfunctions and returns
the status to the caller.
If more than one hardware malfunction occurs, you can invoke the
DTK$CHECK_HDWR_STATUS routine as many times as necessary to
retrieve all error status codes. A status of "no malfunctions" indicates that
there are no further error status codes to be retrieved.

CONDITION
VALUES
RETURNED

DTK-6

SS$_NORMAL

Normal successful completion.

SS$_xxxx

Any error from $QIOW.

DTK$_1NVVOllD

Invalid voice-id.

DTK$_WRONUMARG

Wrong number of arguments.

LIB$_xxxx

Any error from LIB$GET_VM or LIB$FREE_VM.

DTK$DIAL_PHONE

Dial the Telephone

The Dial the Telephone routine dials the specified number on the
telephone.

FORMAT

DTK$DIAL_PHONE

RETURNS

VMS usage:
type:
access:
mechanism:

ARGUMENTS

voice-id ,phone-number
[,dial-mode}[, text][, timeout]

cond_value
longword (unsigned)
write only
by value

voice-id
VMS usage:
type:
access:
mechanism:

identifier
longword (unsigned)
read only
by reference

Voice identifier of the DECtalk machine. The voice-id argument is the
address of an unsigned longword containing this identifier. The voice
identifier is returned by the DTK$INITIALIZE routine.

phone-number
VMS usage:
type:
access:
mechanism:

char_string
character string
read only
by descriptor

Phone number to dial. The phone-number argument is the address of a
descriptor pointing to the specified phone number.

dial-mode
VMS usage:
type:
access:
mechanism:

longword_unsigned
longword (unsigned)
read only
by reference

Mode to use when dialing the phone. The optional dial-mode argument is
the address of an unsigned longword containing this mode.
The valid modes are:
DTK$K_DIAL_PULSE

Use pulse dialing.

DTK$K_DIAL _TONE

Use tone dialing.

Pulse dialing is the default. Tone dialing requires a touch tone telephone;
there are, however, touch tone phones that have a pulse dialing mode.

DTK-7

DTK$DIAL_PHONE

text
VMS usage: char_string
character string
access:
read only
mechanism: by descriptor

type:

Text to be spoken after the phone is answered. The text argument is the
address of a descriptor pointing to the specified text.

timeout
VMS usage: longword_signed
type:
longword (signed)
access:
read only
mechanism: by reference

Number of seconds to wait for the phone to be answered. The optional
timeout argument is the address of a signed longword containing this timeout
value. If omitted, DECtalk dials the phone and immediately returns control
to the calling program.

DESCRIPTION

DTK$DIAL _PHONE dials the specified number on the telephone. If a call is
currently active, DECtalk does not hang up the phone.
Note that this routine does not ensure that the phone is answered; it simply
dials the specified telephone number. If the user specifies the optional text
argument, DECtalk speaks this text before returning control to the calling
program.
If the timeout argument is specified, the DTCOl device always waits for the
specified number of seconds before returning control, even if the phone is
answered before the specified number of seconds has elapsed. On the other
hand, the DTC03 device interprets the timeout argument as the maximum
number of seconds to wait before returning control to the calling program.
That is, the DTC03 device returns control either when the phone is answered
or when the timeout argument has expired, whichever occurs first.

CONDITION
VALUES
RETURNED

DTK-8

SS$_NORMAL

Normal successful completion.

SS$_xxxx

Any error from $OIOW.

DTK$_1NVVOllD

Invalid voice-id.

DTK$_WRONUMARG

Wrong number of arguments.

DTK$_TOOLONG

Phone number is too long.

DTK$_INVMODE

Invalid mode specified.

DTK$_0FFHOOK

Phone is off hook (phone is already active).

DTK$HANGUP_PHONE

Hang Up the Phone

The Hang Up the Phone routine speaks an optional message and then
hangs up the phone.

FORMAT

DTK$HANGUP_PHONE

RETURNS

VMS usage:
type:
access:
mechanism:

ARGUMENTS

voice-id [,text]

cond_value
longword (unsigned)
write only
by value

voice-id
VMS usage:
type:
access:
mechanism:

identifier
longword (unsigned)
read only
by reference

Voice identifier of the DECtalk device. The voice-id argument is the address
of an unsigned longword containing this identifier. The voice identifier is
returned by the DTK$INITIALIZE routine.

text
VMS usage:
type:
access:
mechanism:

char_string
character string
read only
by descriptor

Text to be spoken before hanging up the phone. The optional text argument
is the address of a descriptor pointing to the specified text.

DESCRIPTION

CONDITION
VALUES
RETURNED

DTK$HANGUP_PHONE hangs up the phone after speaking an optional
message.

SS$_NORMAL

Normal successful completion.

SS$_xxxx

Any error from $QIOW.

DTK$_1NVVOllD

Invalid voice-id.

DTK$_WRONUMARG

Wrong number of arguments.

DTK-9

DTK$1NITIALIZE

Initialize DECtalk

The Initialize DECtalk routine initializes a DECtalk device and returns the
device's assigned voice identifier.

FORMAT

DTK$1NITIALIZE

RETURNS

VMS usage:
type:
access:
mechanism:

ARGUMENTS

voice-id ,output-device [,device-type}

cond_value
longword (unsigned)
write only
by value

voice-id
VMS usage:
type:
access:
mechanism:

identifier
longword (unsigned)
write only
by reference

Voice identifier of the newly created DECtalk device. The voice-id argument
is the address of an unsigned longword that receives this identifier.

output-device
VMS usage:
type:
access:
mechanism:

device_name
character string
read only
by descriptor

File specification or logical name to which the output associated with the
DECtalk device is written. The output-device argument is the address of a
descriptor pointing to this logical name.

device-type
VMS usage:
type:
access:
mechanism:

longword_signed
longword (signed)
write only
by reference

Device type of the newly created DECtalk device. The optional device-type
argument is the address of a signed longword that receives the device-type
information. The two valid device types are:

DTK$K_DTC_01
DTK$K_DTC_03

For DECtalk I.
For DECtalk Ill.

If the device-type information is not received in time, the assigned device-

type is DTK$K_DTC_UNKNOWN.

DTK-10

DTK$1NITIALIZE

DESCRIPTION

DTK$INITIALIZE creates a DECtalk device and returns its assigned voice
identifier, voice-id. Output-device is the device to which the output
associated with this newly created DECtalk is written.
If DTK$1NITIALIZE is called to create a second DECtalk on a device that
already has a voice identifier associated with it, DTK$INITIALIZE simply
returns the identifier of the already existing DECtalk, along with the condition
code DTK$_VOIALREXI, which signifies that DECtalk already exists for this
device.

CONDITION
VALUES
RETURNED

SS$_NORMAL

Normal successful completion.

SS$_xxxx

Any error from $GETDVI.

RMS$_xxxx

Any error from $PARSE.

LIB$_xxxx

Any error from LIB$GET_ VM or LIB$GET_EF.

LIB$_1NSVIRMEM

Insufficient virtual memory to allocate needed
buffer.

DTK$_VOIALREXI

DECtalk already exists for this device.

DTK$_ WRONUMARG

Wrong number of arguments.

DTK-11

DTK$LOAD_DICTIONARY

Load a Word into the
DECtalk Dictionary

The Load a Word into the DECtalk Dictionary routine loads a phonemic
definition of a word into the DECtalk dictionary.

FORMAT

DTK$LOAD_DICTIONARY

RETURNS

VMS usage:
type:
access:
mechanism:

ARGUMENTS

voice-id ,text ,substitution

cond_value
longword (unsigned)
write only
by value

voice-id
VMS usage:
type:
access:
mechanism:

identifier
longword (unsigned)
read only
by reference

Voice identifier of the DECtalk device. The voice-id argument is the address
of an unsigned longword containing this identifier. The voice identifier is
returned by the DTK$INITIALIZE routine.

text
VMS usage:
type:
access:
mechanism:

char_string
character string
read only
by descriptor

Word to be loaded into the DECtalk dictionary. The text argument is the
address of a descriptor pointing to the specified word.

substitution
VMS usage:
type:
access:
mechanism:

char_string
character string
read only
by descriptor

Phonemic definition of the word specified by the text argument. The
substitution argument is the address of a descriptor pointing to the phonemic
representation of the specified word.

DESCRIPTION

DTK-12

DTK$LOAD_DICTIONARY loads the phonemic definition of a specified
word into the DECtalk dictionary.

DTK$LOAD_DICTIONARY

CONDITION
VALUES
RETURNED

SS$_NORMAL

Normal successful completion.

DTK$_WRONUMARG

Wrong number of arguments.

DTK$_1NVVOllD

Invalid voice-id.

DTK$_NQROOM

No room in the dictionary to add the specified
word.

DTK$_DEFTOOLONG

Word definition is too long.

DTK-13

DTK$READ_KEYSTROKE

Read a Key Entered on
the Keypad

The Read a Key Entered on the Keypad routine reads a key entered on the
phone keypad.

FORMAT

DTK$READ_KEVSTROKE

RETURNS

VMS usage:
type:
access:
mechanism:

ARGUMENTS

voice-id ,key-code
[,prompt-string][, timeout}

cond_value
longword (unsigned)
write only
by value

voice-id
VMS usage:
type:
access:
mechanism:

identifier
longword (unsigned)
read only
by reference

Voice identifier of the DECtalk device. The voice-id argument is the address
of an unsigned longword containing this identifier. The voice identifier is
returned by the DTK$INITIALIZE routine.

key-code
VMS usage:
type:
access:
mechanism:

longword_signed
longword (signed)
write only
by reference

The DTK$K_TRM__xxxx code for the key entered on the keypad. The keycode argument is the address of a signed longword that receives this code.
The valid codes are listed in DTKDEF.

prompt-string
VMS usage:
type:
access:
mechanism:

char_string
character string
read only
by descriptor

Text to be spoken before waiting for input. The optional prompt-string
argument is the address of a descriptor pointing to this text.

timeout
VMS usage:
type:
access:
mechanism:

DTK-14

longword_signed
longword (signed)
read only
by reference

DTK$READ_KEYSTROKE

Number of seconds to wait for input. The optional timeout argument is the
address of a signed longword containing the specified number of seconds
the DECtalk device waits for input. If the timeout argument is omitted,
DTK$READ-1<EYSTROKE waits for input indefinitely.

DESCRIPTION

CONDITION
VALUES
RETURNED

DTK$READ_KEYSTROKE reads a key entered on the phone keypad. If the
optional text argument is specified, DECtalk speaks this text before waiting
for input. If the keypad mode has not yet been set, this routine will set the
phone keypad to auto-stop mode.

SS$_NORMAL

Normal successful completion.

SS$_xxxx

Any error from $QIOW.

DTK$_1NVVOllD

Invalid voice-id.

DTK$_WRONUMARG

Wrong number of arguments.

DTK$_0NHOOK

Phone is on the hook (inactive).

DTK$_WINK

A wink has occurred.

DTK-15

DTK$READ_STRING

Read a Series of Keys
Entered on the Keypad

The Read a Series of Keys Entered on the Keypad routine reads a series of
keys entered on the phone keypad.

FORMAT

DTK$READ_STRING

RETURNS

VMS usage:
type:
access:
mechanism:

ARGUMENTS

voice-id ,resultant-string
[,prompt-string][, timeout]
[,longword-integer-term in-code]

cond_value
longword (unsigned)
write only
by value

voice-id
VMS usage:
type:
access:
mechanism:

identifier
longword (unsigned)
read only
by reference

Voice identifier of the DECtalk device. The voice-id argument is the address
of an unsigned longword containing this identifier. The voice identifier is
returned by the DTK$INITIALIZE routine.

resultant-string
VMS usage:
type:
access:
mechanism:

char_string
character string
write only
by descriptor

String into which the keys being read are written. The resultant-string
argument is the address of a descriptor pointing to this string.

prompt-string
VMS usage:
type:
access:
mechanism:

char_string
character string
read only
by descriptor

Text to be spoken before waiting for input. The optional prompt-string
argument is the address of a descriptor pointing to this text.

timeout
VMS usage:
type:
access:
mechanism:

DTK-16

longword_signed
longword (signed)
read only
by reference

DTK$READ_STRI NG

Number of seconds DECtalk waits for input. The optional timeout argument
is the address of a signed longword containing the number of seconds
DECtalk waits for input. If the timeout argument is omitted,
DTK$READ_STRING waits for input indefinitely.

longword-integer-term in-code
VMS usage: longword_signed
longword (signed)
access:
write only
mechanism: by reference

type:

The DTK$K_TRM_xxxx code for terminating key entered. The optional
longword-integer-termin-code argument is the address of a signed longword
that receives this code. The valid codes are located in DTKDEF.

DESCRIPTION

CONDITION
VALUES
RETURNED

DTK$READ_STRING reads a series of keys entered on the phone keypad
and stores them in resultant-string. If the optional prompt-string argument
is specified, DECtalk speaks the specified text before waiting for input. The
valid terminators are the number sign (#) and the asterisk(*). If the keypad
mode has not yet been set, this routine will set the phone keypad to auto-stop
mode.

SS$_NORMAL

Normal successful completion.

SS$_xxxx

Any error from $QIOW.

DTK$_1NVVOllD

Invalid voice-id.

DTK$_WRONUMARG

Wrong number of arguments.

DTK$_0NHOOK

Phone is on the hook (inactive).

DTK$_WINK

A wink has occurred.

DTK-17

DTK$RETURN _LAST_I N DEX

DTK$RETURN_LAST_INDEX

Return Last Index
Spoken

The Return Last Index Spoken routine returns the last index spoken.

FORMAT

DTK$RETURN_LAST_INDEX

RETURNS

VMS usage:
type:
access:
mechanism:

ARGUMENTS

voice-id ,p-index

cond_value
longword (unsigned)
write only
by value

voice-id
VMS usage:
type:
access:
mechanism:

identifier
longword (unsigned)
read only
by reference

Voice identifier of the DECtalk device. The voice-id argument is the address
of an unsigned longword containing this identifier. The voice identifier is
returned by the DTK$INITIALIZE routine.

p-index
VMS usage:
type:
access:
mechanism:

longword_signed
longword (signed)
write only
by reference

Index to be returned. The p-index argument is the address of a signed
longword that receives the index identifier.

DESCRIPTION

CONDITION
VALUES
RETURNED

DTK-18

DTK$RETURN _LAST-1NDEX returns the last index spoken. An index is
inserted into the output stream with the DTK$SET-1NDEX routine.

SS$_NORMAL

Normal successful completion.

SS$_xxxx

Any error from $QIOW.

DTK$_1NVVOllD

Invalid voice-id.

DTK$_WRONUMARG

Wrong number of arguments.

DTK$SET_INDEX

Insert an Index at the Current
Position

The Insert an Index at the Current Position routine inserts an index into the
current output stream.

FORMAT

DTK$SET_INDEX

RETURNS

VMS usage:
type:
access:
mechanism:

ARGUMENTS

voice-id ,p-index

cond_value
longword (unsigned)
write only
by value

voice-id
VMS usage:
type:
access:
mechanism:

identifier
longword (unsigned)
read only
by reference

Voice identifier of the DECtalk device. The voice-id argument is the address
of an unsigned longword containing this identifier. The voice identifier is
returned by the DTK$INITIALIZE routine.

p-index
VMS usage:
type:
access:
mechanism:

longword_signed
longword (signed)
read only
by reference

Index to be inserted. The p-index argument is the address of a signed
longword containing the index value. Valid values are in the range of 1 to
32767. An index of zero is reserved for use by DIGITAL.

DESCRIPTION

CONDITION
VALUES
RETURNED

DTK$SET_INDEX inserts an index into the current position in the output
stream. Allowable values for p-index are in the range of 1 to 32767. An
index of zero is reserved for use by DIGITAL.

SS$_NORMAL

Normal successful completion.

SS$_xxxx

Any error from $QIOW.

DTK$_1NVVOllD

Invalid voice-id.

DTK$_WRONUMARG

Wrong number of arguments.

DTK$_1NV ARG

Invalid argument.

DTK-19

DTK$SET_KEYPAD_MQDE

DTK$SET_KEYPAD_MODE Turn the Phone
Keypad On and Off
The Turn the Phone Keypad On and Off routine turns recognition of the
telephone keypad on or off.

FORMAT

DTK$SET_KEYPAD_MODE

RETURNS

VMS usage:
type:
access:
mechanism:

ARGUMENTS

voice-id ,keypad-mode

cond_value
longword (unsigned)
write only
by value

voice-id
VMS usage:
type:
access:
mechanism:

identifier
longword (unsigned)
read only
by reference

Voice identifier of the DECtalk device. The voice-id argument is the address
of an unsigned longword containing this identifier. The voice identifier is
returned by the DTK$INITIALIZE routine.

keypad-mode
VMS usage:
type:
access:
mechanism:

longword_unsigned
longword (unsigned)
read only
by reference

Mode that determines the status of the telephone keypad. The keypad-mode
argument is the address of an unsigned longword containing this mode. The
valid mode specifiers are:

DTK$K_KEYPAD_ON
DTK$K_KEYPAD_OFF
DTK$K_KEYPAD_AUTO

DESCRIPTION

DTK-20

Turns the keypad on.
Turns the keypad off.
Turns the keypad on with autostop.

DTK$SET_KEYPAD_MODE turns the recognition of the telephone keypad
on or off. Depending upon the keypad-mode specified, the keypad can be
turned on, off, or on with autostop. Autostop means that DECtalk stops
speaking when a terminator is entered.

DTK$SET_KEYPAD_MQDE

CONDITION
VALUES
RETURNED

SS$_NORMAL

Normal successful completion.

DTK$_WRONUMARG

Wrong number of arguments.

DTK$_1NVVOllD

Invalid voice-id.

DTK$_0NHOOK

Phone is on the hook (inactive).

DTK$_1NVMODE

Invalid mode specified.

DTK$_WINK

A wink has occurred.

DTK-21

DTK$SET_LQGGING_MODE

Set the Logging
Mode for the Video
Terminal Connected
to the DECtalk
Device

The Set the Logging Mode for the Video Terminal Connected to the
DECtalk Device routine controls the information that is displayed on the
video terminal while the DECtalk device is functioning.

FORMAT

DTK$SET_LQGGING_MODE

RETURNS

VMS usage:
type:
access:
mechanism:

ARGUMENTS

voice-id [,new-mode]
[,old-mode]

cond_value
longword (unsigned)
write only
by value

voice-id
VMS usage:
type:
access:
mechanism:

identifier
longword (unsigned)
read only
by reference

Voice identifier of the DECtalk device. The voice-id argument is the address
of an unsigned longword containing this identifier. The voice identifier is
returned by the DTK$INITIALIZE routine.

new-mode
VMS usage:
type:
access:
mechanism:

mask_longword
longword (unsigned)
read only
by reference

DECtalk mode to be set. The optional new-mode argument is the address
of a longword bit mask containing the specified mode. Valid values for
new-mode are:

•
•
•
•
•
•
DTK-22

DTK$M_TEXT
DTK$MJHONEME
DTK$M__RAWHOST
DTK$M_INHOST
DTK$M_OUTHOST
DTK$M_ERROR

DTK$SET_LOGGI NG _MODE

•

DTK$M_TRACE

•

DTK$M_DEBUG

It is possible to perform a logical OR operation on the bits in the bit mask

together to set more than one mode at a time. Any mode not specified is
reset.

old-mode
VMS usage: mask_longword
longword (unsigned)
access:
write only
mechanism: by reference

type:

Current mode settings of the DECtalk device. The optional old-mode
argument is the address of a longword bit mask that receives the current
DECtalk settings.

DESCRIPTION

DTK$SET_LOGGING_MODE sets or resets the specified modes on the
DECtalk device. It controls the information that is displayed on a video
terminal connected to the DECtalk device. Note that any modes not explicitly
set are reset by DTK$SET_LOGGING_MODE.
DTK$SET_LOGGING_MODE has two optional parameters, new-mode and
old-mode. By specifying different combinations of these arguments, you can
use DTK$SET_LOGGING_MQDE in various ways.
•

To use DTK$SET_LOGGING_MODE to determine the current mode
settings, use the following format:
DTK$SET_LOGGING_MODE (voice_id ,,old_mode)

•

To use DTK$SET_LQGGING_MODE to set the bits without regard to
their current setting, use the following format:
DTK$SET_LOGGING_MODE (voice_id ,new_mode)

•

To use DTK$SET_LQGGING_MODE to save the current settings, set
new modes, and later restore the original settings, use the following
format:
DTK$SET_LOGGING_MODE (voice_id ,new_mode ,save_old_settings)

This retrieves the current bit settings and then sets the mode according to
the new-mode argument.
Later, to restore the mode to its former state, specify the following
format:
DTK$SET_LOGGING _MODE (voice-id ,save_old_settings)

This sets the new mode settings according to those previously retrieved.

DTK-23

DTK$SET_LQGGING_MODE

CONDITION
VALUES
RETURNED

DTK-24

SS$_NORMAL

Normal successful completion.

DTK$_WRONUMARG

Wrong number of arguments.

DTK$_1NVVOID

Invalid voice-id.

DTK$_1NVMODE

Invalid mode specified.

DTK$SET_MODE

Set the Mode for the DECtalk
Terminal

The Set the Mode for the DECtalk Terminal routine sets or resets the
mode settings of the DECtalk terminal.

FORMAT

DTK$SET_MODE

RETURNS

VMS usage:
type:
access:
mechanism:

ARGUMENTS

voice-id [,new-mode} [,old-mode]

cond_value
longword (unsigned)
write only
by value

voice-id
VMS usage:
type:
access:
mechanism:

identifier
longword (unsigned)
read only
by reference

Voice identifier of the DECtalk device. The voice-id argument is the address
of an unsigned longword containing this identifier. The voice identifier is
returned by the DTK$INITIALIZE routine.

new-mode
VMS usage:
type:
access:
mechanism:

longword_unsigned
longword (unsigned)
read only
by reference

DECtalk mode to be set. The optional new-mode argument is the address
of a longword bit mask containing the specified mode. Valid values for
new-mode are:
•

DTK$M_SQUARE

•

DTK$M_ASCII (valid for the DTCOl device only)

•

DTK$M_MINUS

•

DTK$M_EUROPE (valid for the DTC03 device only)

•

DTK$M_SPELL (valid for the DTC03 device only)

It is possible to perform a logical OR operation on the bits in the bit mask

together to set more than one mode at a time. Any mode not specified is
reset. If the new-mode argument is omitted, the current mode is unchanged.

old-mode
VMS usage:
type:
access:
mechanism:

longword_unsigned
longword (unsigned)
write only
by reference

DTK-25

DTK$SET_MODE

Current mode settings of the DECtalk device. The optional old-mode
argument is the address of a longword bit mask that receives the current
DECtalk settings.

DESCRIPTION

DTK$SET_MODE controls the mode settings for the DECtalk device. Note
that any modes not explicitly set are reset by DTK$SET_MODE.
DTK$SET_MODE has two optional parameters, new-mode and old-mode.
By specifying different combinations of these arguments, DTK$SET_MQDE
can be used in various ways.
•

To use DTK$SET_MODE to determine the current mode settings, use the
following format:
DTK$SET_MODE (voice_id ,,old_mode)

•

To use DTK$SET_MODE to set the bits without regard to their current
setting, use the following format:
DTK$SET_MODE (voice_id ,new_mode)

•

To use DTK$SET_MODE to save the current settings, set new modes, and
later restore the original settings, use the following format:
DTK$SET_MODE (voice_id ,new_mode ,save_old_settings)

This sets the new mode setting according to those previously retrieved.

CONDITION
VALUES
RETURNED

DTK-26

SS$_NORMAL

Normal successful completion.

DTK$_WRONUMARG

Wrong number of arguments.

DTK$_1NVVOID

Invalid voice-id.

DTK$_1NVMODE

Invalid mode specified.

DTK$SET_SPEECH _MODE

Turn Speech Mode
On and Off

The Turn Speech Mode On and Off routine either starts or stops the
DECtalk device's speech.

FORMAT

DTK$SET_SPEECH_MODE

RETURNS

VMS usage:
type:
access:
mechanism:

ARGUMENTS

voice-id ,new-mode
[,old-mode]

cond_value
longword (unsigned)
write only
by value

voice-id
VMS usage:
type:
access:
mechanism:

identifier
longword (unsigned)
read only
by reference

Voice identifier of the DECtalk device. The voice-id argument is the address
of an unsigned longword containing this identifier. The voice identifier is
returned by the DTK$INITIALIZE routine.

new-mode
VMS usage:
type:
access:
mechanism:

longword_unsigned
longword (unsigned)
read only
by reference

Mode to be set. The new-mode argument is the address of an unsigned
longword containing the specified mode. Valid values are:
DTK$K_SPEAK

Start speaking.

DTK$K_STOP

Stop speaking when current text is completed.

DTK$K_HALT

Stop speaking immediately.

If the new-mode argument is omitted, the current mode is unchanged.

old-mode
VMS usage:
type:
access:
mechanism:

longword_unsigned
longword (unsigned)
write only
by reference

Current speech mode of the DECtalk device. The optional old-mode
argument is the address of an unsigned longword that receives the current
mode setting before enabling the new mode. The values returned in oldmode are the same as those valid for the new-mode argument.

DTK-27

DTK$SET_SPEECH_MODE

DESCRIPTION

CONDITION
VALUES
RETURNED

DTK-28

DTK$SET_SPEECH_MODE starts or stops the speech of the DEC talk device.
When stopping DECtalk's speech, the user can either stop the DECtalk device
immediately or stop it after it has finished speaking. Because
DTK$SET_SPEECH_MODE is used to set a new speech mode, the newmode argument is required.

SS$_NORMAL

Normal successful completion.

DTK$_INVVOllD

Invalid voice-id.

DTK$_WRONUMARG

Wrong number of arguments.

DTK$_1NVMODE

Invalid mode specified.

DTK$SET_TERMINAL_MQDE

DTK$SET_TERMINAL_MODE

Set the Mode for
the Video Terminal
Connected to the
DECtalk Device

The Set the Mode for the Video Terminal Connected to the DECtalk Device
routine controls the attributes of the video terminal connected to the
DECtalk device.

FORMAT

DTK$SET_TERMINAL_MODE

RETURNS

VMS usage:
type:
access:
mechanism:

ARGUMENTS

voice-id [,new-mode}
[,old-mode}

cond_value
longword (unsigned)
write only
by value

voice-id
VMS usage:
type:
access:
mechanism:

identifier
longword (unsigned)
read only
by reference

Voice identifier of the DECtalk device. The voice-id argument is the address
of an unsigned longword containing this identifier. The voice identifier is
returned by the DTK$INITIALIZE routine.

new-mode
VMS usage:
type:
access:
mechanism:

mask_longword
longword (unsigned)
read only
by reference

DECtalk mode to be set. The optional new-mode argument is the address
of a longword bit mask containing the specified mode. Valid values for
new-mode are:

•

DTK$M_HOST

•

DTK$M_SPEAK

•

DTK$M_:EDITED

•
•
•

DTK$M_HARD
DTK$M_SETUP
DTK$M_FILTER

DTK-29

DTK$SET_TERMINAL_MQDE

It is possible to perform a logical OR operation on these values to set more

than one mode at a time. Any mode not specified is reset. If the new-mode
argument is omitted, the current mode is unchanged.

old-mode
VMS usage: mask_longword
type:
longword (unsigned)
access:
write only
mechanism: by reference

Current mode settings of the DECtalk device. The optional old-mode
argument is the address of a longword bit mask that receives the current
DECtalk settings.

DESCRIPTION

DTK$SET_TERMINAL_MODE controls the mode settings for the video
terminal connected to the DECtalk device. Note that any modes not explicitly
set are reset by DTK$SET_TERMINAL_MODE.
DTK$SET_TERMINAL_MODE has two optional parameters, new-mode
and old-mode. By specifying different combinations of these arguments,
DTK$SET_TERMINAL_MODE can be used in various ways.
•

To use DTK$SET_TERMINAL_MODE to determine the current mode
settings, use the following format:
DTK$SET_TERMINAL _MODE (voice_id ,,old_mode)

•

To use DTK$SET_TERMINAL_MODE to set the bits without regard to
their current setting, use the following format:
DTK$SET_TERMINAL_MODE (voice_id ,new_mode)

•

To use DTK$SET_TERMINAL_MODE to save the current settings, set
new modes, and later restore the current settings, use the following
format:
DTK$SET_TERMINAL _MODE (voice_id ,new_mode ,save_old_settings)

This sets the new mode settings according to those previously retrieved.

CONDITION
VALUES
RETURNED

DTK-30

SS$_NORMAL

Normal successful completion.

DTK$_WRONUMARG

Wrong number of arguments.

DTK$_1NVVOID

Invalid voice-id.

DTK$_INVMODE

Invalid mode specified.

DTK$SET_VOICE

DTK$SET_VQICE

Set Voice Characteristics

The Set Voice Characteristics routine changes the DECtalk voice
characteristics to match those specified.

FORMAT

DTK$SET_VQICE

RETURNS

VMS usage:
type:
access:
mechanism:

ARGUMENTS

voice-id [,new-voice] [,speech-rate]
[,comma-pause] {,period-pause]

cond_value
longword (unsigned)
write only
by value

voice-id
VMS usage:
type:
access:
mechanism:

identifier
longword (unsigned)
read only
by reference

Voice identifier of the DECtalk device. The voice-id argument is the address
of an unsigned longword containing this identifier. The voice identifier is
returned by the DTK$INITIALIZE routine.

new-voice
VMS usage:
type:
access:
mechanism:

longword_signed
longword (signed)
read only
by reference

Type of voice. The optional new-voice argument is the address of a signed
longword containing any valid new-voice value. Valid values for new-voice
are:
DTK$K_VOICE_MALE

Standard male voice

DTK$K_VOICE_FEMALE

Standard female voice

DTK$K_VOICE_CHILD

Standard child voice

DTK$K_VOICE_DEEP_MALE

Deep male voice

DTK$K_VOICE_DEEP_FEMALE

Deep female voice

DTK$K_VOICE_OLDER_MALE

Older male voice

DTK$K_VOICE_LIGHT_FEMALE

Light female voice

DTK-31

DTK$SET_VQICE

speech-rate
VMS usage: longword_signed
type:
longword (signed)
access:
read only
mechanism: by reference

Rate at which DECtalk speaks, measured in words per minute. The optional
speech-rate argument is the address of a signed longword containing this
rate. The valid range of values for speech-rate is 120 to 350 words per
minute.

comma-pause
VMS usage:
type:
access:
mechanism:

longword_unsigned
longword (unsigned)
read only
by reference

Number of milliseconds by which to increase the time DECtalk pauses after
a comma. The optional comma-pause argument is the address of a signed
longword containing this number. A value of zero resets the pause time to
the hardware default value.

period-pause
VMS usage:
type:
access:
mechanism:

longword_unsigned
longword (unsigned)
read only
by reference

Number of milliseconds by which to increase the time DECtalk pauses after
a period. The optional period-pause argument is the address of a signed
longword containing this number. A value of zero resets the pause time to
the hardware default value.

DESCRIPTION

CONDITION
VALUES
RETURNED

DTK-32

DTK$SET_VOICE changes the DECtalk voice characteristics to match those
specified. DTK$SET_VOICE can change the voice type, the rate of speech,
and the number of milliseconds DECtalk pauses after commas and periods.

SS$_NORMAL

Normal successful completion.

SS$_xxxx

Any error from $010.

DTK$_1NVVOllD

Invalid voice-id.

DTK$_WRONUMARG

Wrong number of arguments.

DTK$_1NV ARG

Invalid argument.

OTS$_xxxx

Any error from OTS$CVT_L _TU.

DTK$SPEAK_FI LE

Speak the Text in a Specified
File

The Speak the Text in a Specified File routine speaks the text contained in
the specified file.

FORMAT

DTK$SPEAK_FILE

RETURNS

VMS usage:
type:
access:
mechanism:

ARGUMENTS

voice-id ,filespec
[,completion-mode]

cond_value
longword (unsigned)
write only
by value

voice-id
VMS usage:
type:
access:
mechanism:

identifier
longword (unsigned)
read only
by reference

Voice identifier of the DECtalk device. The.voice-id argument is the address
of an unsigned longword containing this identifier. The voice identifier is
returned by the DTK$INITIALIZE routine.

filespec
VMS usage:
type:
access:
mechanism:

char_string
character string
read only
by descriptor

File specification of the file containing the text to be spoken. The filespec
argument is the address of a descriptor pointing to this file.

completion-mode
VMS usage:
type:
access:
mechanism:

longword_unsigned
longword (unsigned)
read only
by reference

Mode characteristic. The optional completion-mode argument is the address
of an unsigned longword containing the specified mode. Valid values for the
completion-mode argument are:
DTK$K_IMMED

Return to the user immediately (default).

DTK$K_WAIT

Wait until the text is completely spoken.

DTK$K_STATUS

Wait until the text is completely spoken, and then
return a phone status.

DTK-33

DTK$SPEAK_f I LE

DESCRIPTION
CONDITION
VALUES
RETURNED

DTK-34

DTK$SPEAKJILE speaks the text contained in the specified file.

SS$_NORMAL

Normal successful completion.

SS$_xxxx

Any error from $010.

RMS$_xxxx

Any error generated by RMS.

DTK$_1NVVOllD

Invalid voice-id.

DTK$_WRONUMARG

Wrong number of arguments.

DTK$_1NVMODE

Invalid mode specified.

DTK$SPEAK_PHONEMIC_TEXT

DTK$SPEAK_PHONEMIC_TEXT Speak the
Specified
Phonemic Text
The Speak the Specified Phonemic Text routine sends the specified
phonemic text to the DECtalk device to be spoken.

FORMAT

DTK$SPEAK_PHONEMIC_TEXT

RETURNS

VMS usage:
type:
access:
mechanism:

ARGUMENTS

voice-id ,text
[,completion-mode]

cond_value
longword (unsigned)
write only
by value

voice-id
VMS usage:
type:
access:
mechanism:

identifier
longword (unsigned)
read only
by reference

Voice identifier of the DECtalk device. The voice-id argument is the address
of an unsigned longword containing this identifier. The voice identifier is
returned by the DTK$INITIALIZE routine.

text
VMS usage:
type:
access:
mechanism:

char_string
character string
read only
by descriptor

Phonemic text to be spoken. The text argument is the address of a descriptor
pointing to the specified phonemic representation of the text.

DTK-35

DTK$SPEAK_PHONEMIC_TEXT

completion-mode
VMS usage: longword_unsigned
type:
longword (unsigned)
access:
read only
mechanism: by reference

Mode characteristic. The optional completion-mode argument is the address
of an unsigned longword containing the specified mode. Valid values for the
completion-mode argument are:

DESCRIPTION

CONDITION
VALUES
RETURNED

DTK-36

DTK$K_IMMED

Return to the user immediately (default).

DTK$K_WAIT

Wait until the text is completely spoken.

DTK$K_STATUS

Wait until the text is completely spoken, and then
return a phone status.

DTK$SPEAKJHONEMIC_TEXT sends the specified phonemic
representation of some text to the DECtalk device. This text contains the
phonetic representations of the words to be spoken; that is, the words are
spelled as they are pronounced. The DECtalk device then speaks this text.

SS$_NORMAL

Normal successful completion.

SS$_xxxx

Any error from $010.

DTK$_1NVVOllD

Invalid voice-id.

DTK$_WRONUMARG

Wrong number of arguments.

DTK$_1NVMODE

Invalid mode specified.

DTK$_0NHOOK

Phone is on the hook (inactive).

DTK$SPEAK_TEXT

Speak the Specified Text

The Speak the Specified Text routine sends the specified text to the
DECtalk device to be spoken.

FORMAT

DTK$SPEAK_TEXT

RETURNS

VMS usage:
type:
access:
mechanism:

ARGUMENTS

voice-id ,text [,completion-mode}

cond_value
longword {unsigned)
write only
by value

voice-id
VMS usage:
type:
access:
mechanism:

identifier
longword (unsigned)
read only
by reference

Voice identifier of the DECtalk device. The voice-id argument is the address
of an unsigned longword containing this identifier. The voice identifier is
returned by the DTK$INITIALIZE routine.

text
VMS usage:
type:
access:
mechanism:

char_string
character string
read only
by descriptor

Text to be spoken. The text argument is the address of a descriptor pointing
to the specified text.

completion-mode
VMS usage:
type:
access:
mechanism:

longword_unsigned
longword (unsigned)
read only
by reference

Mode characteristic. The optional completion-mode argument is the address
of an unsigned longword containing the specified mode. Valid values for the
completion-mode argument are:
DTK$K_IMMED

Return to the user immediately (default).

DTK$K_WAIT

Wait until the text is completely spoken.

DTK$K_STATUS

Wait until the text is completely spoken, and then
return a phone status.

DTK-37

DTK$SPEAK_TEXT

DESCRIPTION

CONDITION
VALUES
RETURNED

DTK-38

DTK$SPEAK_TEXT sends the specified text to the DECtalk device. The
DECtalk device then speaks this text.

SS$_NQRMAL

Normal successful completion.

SS$_xxxx

Any error from $010.

DTK$_1NVVOllD

Invalid voice-id.

DTK$_WRONUMARG

Wrong number of arguments.

DTK$_1NVMODE

Invalid mode specified.

DTK$_0NHOOK

Phone is on the hook (inactive).

DTK$SPELL_TEXT

DTK$SPELL_TEXT Spell Text
The Spell Text routine causes DECtalk to pronounce each letter of the
specified text.

FORMAT

DTK$SPELL_TEXT

RETURNS

VMS usage:
type:
access:
mechanism:

ARGUMENTS

voice-id ,text {,completion-mode}

cond_value
longword (unsigned)
write only
by value

voice-id
VMS usage:
type:
access:
mechanism:

identifier
longword (unsigned)
read only
by reference

Voice identifier of the DECtalk device. The voice-id argument is the address
of an unsigned longword containing this identifier. The voice identifier is
returned by the DTK$INITIALIZE routine.

text
VMS usage:
type:
access:
mechanism:

char_string
character string
read only
by descriptor

Text to be spelled out by DECtalk. The text argument is the address of a
descriptor pointing to the specified string.

completion-mode
VMS usage:
type:
access:
mechanism:

mask_longword
longword (unsigned)
read only
by reference

The optional completion mode characteristic. The completion-mode
argument is the address of a longword bit mask containing the specified
mode. Valid values for the completion-mode argument are:
DTK$K_IMMED

Return to the user immediately (default).

DTK$K_WAIT

Wait until the text is completely spoken.

DTK$K_STATUS

Wait until the text is completely spoken, then return a
phone status.

DTK-39

DTK$SPELL_TEXT

DESCRIPTION

CONDITION
VALUES
RETURNED

DTK-40

DTK$SPELL _TEXT causes DECtalk to pronounce each letter of the specified
text individually, rather than treat the text as a word. For example, DECtalk
would normally pronounce USA as "oosa." Calling DTK$SPELL_TEXT
causes DECtalk to pronounce USA as "U, S, A."

SS$_NORMAL

Normal successful completion.

SS$_xxxx

Any error from $010W.

DTK$_1NVVOllD

Invalid voice-id.

DTK$_WRONUMARG

Wrong number of arguments.

DTK$_1NVMODE

Invalid completion-mode specified.

DTK$_0NHOOK

Phone is on the hook (inactive).

DTK$TERMINATE

Terminate DECtalk

The Terminate DECtalk routine terminates the use of an initialized DECtalk
device.

FORMAT

DTK$TERMINATE

RETURNS

VMS usage:
type:
access:
mechanism:

ARGUMENTS

voice-id

cond_value
longword (unsigned)
write only
by value

voice-id
VMS usage:
type:
access:
mechanism:

identifier
longword (unsigned)
read only
by reference

Voice identifier of the DECtalk device. The voice-id argument is the address
of an unsigned longword containing this identifier. The voice identifier is
returned by the DTK$INITIALIZE routine.

DESCRIPTION
CONDITION
VALUES
RETURNED

DTK$TERMINATE terminates the use of the specified DECtalk device.

SS$_NORMAL

Normal successful completion.

SS$_xxxx

Any error from $DASSGN.

LIB$_xxxx

Any error from LIB$FREE_VM or LIB$FREE_EF.

DTK$_WRONUMARG

Wrong number of arguments.

DTK-41

Index

D
DECtalk device
checking hardware status• DTK-5
connecting a terminal to• 1-2 to 1-3
controlling the terminal• 1-2 to 1-3
initializing• 1-1, DTK-10
mode of operation • 1-1 to 1-2
setting terminal attributes• 1-3, DTK-25,
DTK-29
setting terminal logging• 1-2 to 1-3,
DTK-22
specifying an output destination• 1-1
voice characteristics• 1-2, DTK-31
voice identifier• 1-1
DECtalk dictionary• 1-4
loading• DTK-12
DECtalk index• 1-4
returning last spoken• 1-4, DTK-18
setting• 1-4, DTK-19
DECtalk routine• 1-1
controlling the speech• 1-4 to 1-5, DTK-27
speaking phonemic text• DTK-35
speaking text• DTK-37
speaking text in a file• DTK-33
spelling text• DTK-39
initializing DECtalk • 1-1, DTK-10
overview of• 1-1
terminating DECtalk • 1-4, DTK-41
using the telephone• 1-5
answering the phone• 1-5, DTK-3
dialing the phone• 1-5, DTK-7
hanging up the phone• 1-5, DTK-9
recognizing the keypad• 1-5, DTK-20
using keypad for input• 1-5, DTK-14,
DTK-16
writing an exit handler• 1-6
DTK$ANSVVER_PHONE•1-5,DTK-3
DTK$CHECK_HDVVR_STATUS•DTK-5
DTK$DIAL_PHONE • 1-5, DTK-7
DTK$HANGUP_PHONE•1-5,DTK-9
DTK$1NITIALIZE • 1-1, DTK-10
DTK$LOAD_DICTIONARY • 1-4, DTK-12
DTK$READ_KEYSTROKE•1-5,DTK-14
DTK$READ_STRING• 1-5, DTK-16
DTK$RETURN_LAST_INDEX• 1-4, DTK-18

DTK$SET_INDEX• 1-4, DTK-19
DTK$SET_KEYPAD_MQDE•1-5,DTK-20
DTK$SET_LQGGING_MQDE• 1-2 to 1-3,
DTK-22
DTK$SET_MQDE•DTK-25
DTK$SET_SPEECH_MQDE • DTK-27
DTK$SET_TERMINAL_MODE• 1-3, DTK-29
DTK$SET_VQICE • DTK-31
DTK$SPEAK_FILE • DTK-33
DTK$SPEAK_PHONEMIC_TEXT• DTK-35
DTK$SPEAK_TEXT•1-4,DTK-37
DTK$SPELL_TEXT•DTK-39
DTK$TERMINATE • 1-4, DTK-41
$DTKDEF library• 1-5

p
Phonemic text
defined • 1-1
speaking• DTK-35

R
Routine
See also DECtalk routine
Run-Time Library routine
DECtalk • 1-1

v
Voice characteristics• 1-2
comma pause• 1-2, DTK-32
period pause• 1-2, DTK-32
speech rate• 1-2, DTK-32
Voice identifier
See DECtalk device

lndex-1

Reader's Comments

VMS RTL DECtalk
(DTK$) Manual
AA-LA 71 A-TE

Please use this postage-paid form to comment on this manual. If you require a written reply to a software
problem and are eligible to receive one under Software Performance Report (SPR) service, submit your
comments on an SPR form.
Thank you for your assistance.

I rate this manual's:
Accuracy (software works as manual says)
Completeness (enough information)
Clarity (easy to understand)
Organization (structure of subject matter)
Figures (useful)
Examples (useful)
Index (ability to find topic)
Page layout (easy to find information)

Excellent

Good

Fair

Poor

0
0
0
0
D
0
0
0

0
0
0
0
0
0
0
0

I would like to see more /less

What I like best about this manual is

What I like least about this manual is

I found the following errors in this manual:
Page

Description

Additional comments or suggestions to improve this manual:

I am using Version _ _ _ of the software this manual describes.

Name/Title

Dept.
Date

Company
Mailing Address
Phone

-- Do Not Tear - Fold Here and Tape

-------------------[lllr--------------No Postage

~nmnoma™

~;~=~=~y
in the
United States

BUSINESS REPLY MAIL
FIRST CLASS PERMIT NO. 33 MAYNARD MASS.
POSTAGE WILL BE PAID BY ADDRESSEE

DIGIT AL EQUIPMENT CORPORATION
Corporate User Publications-Spit Brook
ZKO 1-3 / J35 110 SPIT BROOK ROAD
NASHUA, NH 03062-9987

111 ..... 11.11 .... 11 .... 1.11.1 .. 1.1 .. 1•• 1.1 ••• 1.11 .. 1
-- Do Not Tear - Fold Here - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -