Digital PDFs

EK-DTC01-RM-003

December 1985

244 pages

Original

58MB

view download

OCR Version

80MB

view download

Document:	DECtalk DTC01 Programmer Reference Manual
Order Number:	EK-DTC01-RM
Revision:	003
Pages:	244
Original Filename:

OCR Text

EK-DTC01-RM-003

DECtalk DTCO04
Programmer Reference Manual

Prepared by Educational Services
of
Digital Equipment Corporation

—
P

1st Edition, December 1983
2nd Edition, June 1984
3rd Edition, March 1985
.

Printed in U.S.A.

The reproduction of this material, in part or whole, is strictly prohibited. For copy

information, contact the Educational Services Department, Digital Equipment

Corporation, Maynard, Massachusetts 01754.
The informationinthisdocumentis subjecttochange without notice. Digital Equipment

Corporation assumes no responsibility for any errors that may appearin this document.
This equipment generates and uses radio frequency energy and if not installed and

used properly, that is, in strict accordance with the manufacturer's instructions, may

cause interference to radio and television reception. It has been type tested and found
to comply with the limits for a Class B computing device in accordance with the
specifications in Subpart J of Part 15 of FCC Rules, which are designed to provide
reasonable protection against such interference in a residential installation.

Compliance with the FCC Class B technical requirementsis dependent upon the use of
interconnecting cables specified in the User/Installation manual. However, there is no

guarantee that interference will not occur in a particular installation. If this equipment
does cause interference to radio or television reception, which can be determined by
turning the equipment off and on, the user is encouraged to try to correct the
interference by one or more of the following methods.
®

Reorient the receiving antenna.
Relocate the computer with respect to the receiver.

Move the computer away from the receiver.

Plug the computer into a different outlet, so that computer and receiver

are on different branch circuits.
Ry,

If necessary, the user should consult the dealer or an experienced radio/television

technician foradditional suggestions. The user may find the booklet How to Identify and
Resolve Radio/TV Interference Problems, prepared by the Federal Communications

AT,

Commission, helpful. This booklet is available from the U.S. Government Printing Office,
Washington, D.C. 20402, Stock No. 004-000-00345-00345-4.
B

—,

UNIX and System V are trademarks of AT&T Bell Laboratories.
Touch-Tone and AT&T are trademarks of American Telephone and Telegraph Company.
Zeus is a trademark of Zilog, Inc.
-

The following are trademarks of Digital Equipment Corporation, Maynard,
Massachusetts.

dlilg]ijtlal |

DECwriter

RSTS

DEC

DIBOL

RSX

DECmate

ULTRIX-32

DECnet

MASSBUS

UNIBUS

VAX

DECsystem-10

PDP

DECSYSTEM-20

P/OS

VMS

DECtalk

Professional

DECUS

Rainbow

Work Processor

RIS,

TELEPHONE COMPANY AND FCC REQUIREMENTS

AND RESPONSIBILITIES
FCC regulations require that you provide your local telephone company business office with the following information before you connect DECtalk to the
telephone network.
e The particular lines(s) to which terminal equipment will be connected
(by telephone number)
e The make, model number, and FCC registration number (label on bottom

of unit)
e The ringer equivalence for the registered terminal equipment (label on

bottom of unit)
e The type of jack needed (if not already installed)

Make: DECtalk
Model: DTCO01-AA

FCC Registration: AO994Q-12463-OT-E
Ringer equivalence: 0.3B

Type of jack: USOC RJ11C or USOC RJXA1 for telephone line interference

(See the DECtalk DTCO1 Installation Manual.)
You must also notify the telephone company when you permanently disconnect

terminal equipment from telephone line(s).

You may not connect terminal equipment to a party line or coin-operated
telephone equipment.

If the telephone or telephone line is already equipped with a jack you should be
able to plug in DECtalk without any additional telephone company charge.
Otherwise, the telephone company will install a jack, which usually results in a

one-time installation charge.
If terminal equipment damages the telephone network, the telephone company

can, after notifying the customer, temporarily discontinue service. However,
when prior notice is not practical, the telephone company can temporarily

discontinue service immediately. In such cases, the telephone company shall:
e

Promptly notify customers that service has been discontinued

e Give customers the opportunity to correct the situation
e

Inform customers of their right to bring a complaint to the FCC according

to Subpart E of Part 68 of FCC Telephone Equipment Rules.
The DECtalk DTCO1 unit is classified as terminal equipment.

CANADIAN APPLICATION NOTICE
The Canadian Department of Communications label identifies certified equipment. This certification means that the equipment meets certain telecommunications network protective, operational, and safety requirements. The department does not guarantee the equipment will operate to the user’s satisfaction.

Before you install this equipment, make sure it is permissible to be connected
to the local telecommunications company’s facilities. You must also install the
equipment by using an approved connection method. In some cases, the company’s inside wiring associated with single line individual service can be

extended by a certified jack/plug/cord ensemble (telephone extension cord).
Be aware that complying with the above conditions may not prevent degrada-

tion of service in some situations. Telecommunications company requirements
do not allow you to connect their equipment to customer-provided jacks,

except where specified by individual telecommunications company tariffs.

Only authorized Canadian maintenance facilities, designated by the supplier,
should repair certified equipment. If you repair or alter certified equipment

yourself, or if the equipment malfunctions, the telecommunications company
has cause to ask you to disconnect the equipment.
You should ensure (for your own protection) that the electrical ground connec-

tions for the power utility, telephone lines, and internal metallic water pipe

system, if present, are connected together. This precaution may be particularly
important in rural areas.
i,

CAUTION:

Do not try to make such connections yourself, but contact the

appropriate electric inspection authority or electrician.

CONTENTS

INTRODUCTION

CHAPTER1

HOW DECtalk PROGRAMMING WORKS

Communicatingwith DECtalk .............. i, e
2
Typesof Data ...
i
it
2
Operating
Modes .......cooiiiiiiiiii
it
iiaaneaan.S
4
Using Escape Sequences and Control Characters ....................
4
Escape Sequences ...........ccoiiiiiininnnnnn. -|
Escape Sequence Format .................. e e
6
Control Characters ...................... e e
7
Control Character Logging .......ccouiiiiiiiriiiniiieieeennnn.
9
Effect
of the Backspace (BS) Character.........fi......_.........,
DECtalk- Computer Communication ............
. ciiiiiiiiinienn.n.
DECtalk SetUpS ..o oottt
et e e e it
Program Control .........coiiiiiiiiiiiiiiii
i
eieeeneeee..
Data Synchronization ...t
i
DECtalk — Host Program Sequence ............ e e
Developing Your Application .............
o
i.
Names, Part Numbers, and Alphanumeric Text ..................
Direct NumericEncoding ..o, e
Two-Character Encoding ................... e
e aeaeaeaeeaaaa
Ending CommandsandData .................cciiiiiiiiia.
Application Development Tips ...t

9
10
12
13
13
15
15
16
16
17
17
18

CONTENTS

CHAPTER 2

e
—

SETUP ESCAPE SEQUENCES

Selecting ASCIll Character Sets ...
i
Coding Standards ............ e
e ettt .
CodeTable .......ciiiiiiii
i e e e .
7-Bit ASClHl Code Table ...
ittt eeaann. .
8-Bit Code Table...... e e e e e
ee et
e,
Character Sets ...
e et et e
Selecting Alternate Character Sets (GO-G3) ....................
DEC Multinational CharacterSet ...........cciiiviviiin.. ....
Working with 7-Bit and 8-Bit Environments .............
... .. ... ......
Conventions for Codes Transmitted to the Terminal .............
Mode Selection (DT_MODE) ...ttt
ii e

CHAPTER3

20
22
23
23
25
27
27
30
32
32
32

[

VOICE COMMANDS, PHONEMIC TEXT,
AND THE USER DICTIONARY

Speech Control ...ooiiii
i
i i i i ittt ittt
e e
Speech Timeout .........c.coiiiiiiiiii
it e e
English Text ...
i
i
i eaeen e
Speak Phonemic Text (DT_PHOTEXT) .....ociiiiiiiiiii it
Stop Speaking (DT __STOP) ..o
i
i ittt
eeaaeens
Data Synchronization (DT_SYNC) ...
it ieenn
Enable or Disable Speaking (DT_SPEAK) ...,
Lo 1= T
PR
Index Text (DT__INDEX) ....oviiiiiiii ittt eeeeeeennn,
Index Reply (DT__INDEX_REPLY) ..o
i
Index Query (DT__INDEX_QUERY) ...
Load Dictionary (DT __DICT) ..ot
it e ittt raeeeaens

CHAPTER4

36
36
37
38
38
39
39
40
40
41
43

P
—

TELEPHONE COMMUNICATIONS

Telephone Management (DT_PHONE)

..., ....

PH_ANSWER ...t iiiienns, e eeaaeeas e

PH_HANGUP ...t
i it i e e e ....
PH __ KEY PAD .ottt
e ettt et e et et

48
48

PH _NOKEYPAD ...ttt
i it et tte s et
tnnsnennnanns

PH_TIMEOUT ............ eet ....
PH_TONE_DIAL and PH_PULSE_DIAL .....................

48
49

—

CONTENTS

CHAPTERS5

vii

MAINTENANCE AND DEBUGGING COMMANDS

Device Attribute Request ...
i i
e
Device Attribute Request (DA Primary)...... e P,
Identify Terminal (DECID) ......... ..., e
Device Test and Status ........... e et aeaeaeaeaa e
DECtalk Power-Up Status ..., e
Device Self-Test (DECTST) .....ccvviiiiiaa... e,
Device Status Request (DSR) (Brief Report) ........ e e
Device Status Request (DSR) (Extended Report) ................
Reset to Initial State (RIS) ...
e n
Soft Terminal Reset (DECSTR) ..ottt
NVR Feature Settings (DECNVR) ...
i,
Tracing and DebuggingCommands .............ccoiiiiiiiiiiiiinn,
Local Log Control (DT_LOG) ........cciiiiiiiiiiiiiiiineeeeen...
0 1€ T 1 =,
1e
LOG_PHONEME .......... e, e et
LOG _RAWHOST ...t
i e e ei.

51
51
52
52
52
54
55
55
56
57
58
58
O8
61
61
61

LOG _OUTHOST .ttt
c i icee e e ....
LOG_ERROR ...t e et
LOG _TRACE .. it
i et et ettt e iaaeaanans .
Local Terminal Command (DT_TERMINAL) ............... e
Keypad Mask Command (DT_MASK) ...............ccoet. e
Determining Firmware Revision Level ............
... ..o
it
Phonemic Alphabet ..................... e e teeaeaaeaeaas

61
61
61
62
64
67
67

CHAPTER6

C PROGRAM EXAMPLE

Program Language and Structure........ et eaieaaeaaaeaan veeeeen..
How the Program Works ..............e
et e e e eeeaaia
s
Variable Names and Definitions ..........coi
=
T
1<
Error COdeS ..ottt ittt ettt e,
DECtalk-Specific Parameters ......... ..ot
DECtalk Commands .............. e e e e et
Telephone Control Parameters ..................
... ... ... e
DECtalk Replies ...........ccooiiiiiia.. et
Self-Test Parameters ........... e e e e eaeaeeieeeeaae
e,
Logging Command Parameters ...,
The Sequence Data Structure ...........e et eteeetiaeaeaaeaaa,

10
71
72
24
(2
73
73
74
75
76
77
78

P
—

CONTENTS

Application Programs ...ttt
i it it
e
DECTLKH .................. et

e e,

DEM
.C e
et et i,

DTANSW.C ..., e,
DTCLOS.C......... e
ettt ettt
ettt
e
DTCMD.C ...
i, e reeaeeaaeae, e
DTDCHAC ........... et
e e
ettt ettt
DTDCS.C ... e et ettt
eaae
e,
DT D AL
C ..
i e
e et i e ..
D D1=7 Y X
DT DUMP.C .
e e ettt e e e
DT EOL . C . s
ettt i ittt
e,
DTGESC.C........ e
et e teteeeaaa
e it
D €] = I O e

98
100
101
103
105
106
108
111
113
115
116
123

D i 12 Y 1

125

DTINIT.C .

e e ittt e 126

DTINKE.C ..o
e
e e et eeaeaaeeaaan 128
DTIOGE.C .............cooiat... e

et aeeaaeeaaa
e 130
DTIOPU.C ..
i et it e e e, 140
) 15T 20 3
143
DTISTILC ....ciiieieie e

a et e . 144

D 151
7 N
O 145
D 3
146
DTMS
G. .
it e et et et 147
DTOFFH.C ...

i e e ereaeeaeaan 149

DT ONHO.C .
e e et ettt 150
DTOPEN.C ...t
ciieen ee, 151
D = = O
167
DTPESC.C ..........ccvvnn.... e, e, 163
DTPHON.C ................... i e, 167
DTPTES.C ........... e ettt 168
DTPUT.C..... e

e ettt

eeeae ettt 169

DT READ.C ..t
et ettt et
e
DTRESE.C ...t eet .
DTSAVE.C ...... e ettt ittt
eee ettt
e
e,
DTSPLICEC ................. e e et aiaeaaeeaaeaa
i,
1D 8 15 12
DTSYNC.C .
it et et
DT TALK G i
e e e
e e,

170
172
173
175
177
178
179

) I8 8
1O 180
DT IME. C .o
e et ettt et ittt i i ena e, 181
[ 110 1 5
DT TRAP.C

183
.

it e

ettt

e 185

DTVISLC ..
i
i ee, 188

———

190

D),

CONTENTS

CHAPTER 7

BASIC-PLUS PROGRAM EXAMPLE

RSTS/E SYStemMS . ..o oot iiiiiiiaine

i e 191

APPENDIX A

DECtalk ESCAPE SEQUENCES

APPENDIX B

PHONEMIC ALPHABET

APPENDIXC

DOCUMENTATION

FIGURES

1-1 DECtalk, Terminal, and Host Communications .................. :

1-4 DECtalk-Computer Program Interaction ...................vnenn

1-2 Typical Escape Sequence Format ..........eS
1-3 Escape Sequence Representations.................covviiennn
1-5 Synchronizing DECtalk and Host Communications ..............

5
6

—

2-1 Mapping 7-Bit and 8-Bit Tables .........ie 21

2-5 8-Bit Code ........ e e 26

2-2 7-Bit ASCll Code Table ..................e e
R RL
2RT N = T 070 Vo | - TP
e
eaaeeae
2-4 8-Bit ASCIl Code Table ............ et e

23
24
25

2-6 Loading 8-BitCharacters ...............ooiiiiiiiiiiiiainen,
2-7 Selecting Active CharacterSets ...
2.8 DEC Multinational CharacterSet ...t

28
28
30

3-1

Using DT_SYNC and DT__ INDEX_QUERY to Coordmate
ittt ciaae i
COMMUNICAtIONS .« ottt ittt

i
e
4-1 Telephone COmMMUNICAtIONS .....oveueirniriii
e
......
.........
ng
Debuggi
5-1 Data Paths for Logging and
5-2 Data Paths for Local Terminal Operations ........ e

50
60
62

6-1 Calling Tree of DECtalk Application Program .................... 70
TABLES

o
W

1-1 Control Characters and Host Communications ..................
2-1 Selecting 7-Bit or 8-BitMode ............... e
2-2 Selecting the Active Character Set ..................coociienen,
2.3 Selecting the CharacterSet ....................co.0n..
2.4 DT_MODE Parameters ..........cooiiiiiiiiiininennnnnn. e
4-1 DT_PHONE Parameters ..........c.ceeeimiueeennnneeeinnnaeannne.
4-2 Phone Status ReplyCodes ...........coiiiiiie e

5-2 DECtalk Actions Performed at Resets ........ e 53

'i
=
S

5-1 Restoring DECtalk Operating Features ...................ccoeeee

5-3 Self-Test Parameters ........coceveeieeiiiieieneeneciecnsenseese.
5-4 DT__LOG Parameters ............ e e e

29
29

47
47

04
59

5-5

5-6

6-1
A-1
A-2

A-3
A-4

A-5
A-6

A-7
A-8

B-1
B-2

CONTENTS

DT_TERMINAL Parameters ..........oouuuue oo
DT_MASK Parameters ...... e e
e e
Application Program Modules ...................co...
ooii ..

80
Escape Commands ..............ouuiiui
210
DECtalk Status Replies ...........c.oovueeur
213
DT_MODE Parameters .............o.ouueuuinone
215
DT_TERMINAL Parameters ........ e e, e
215
DT_PHONE Parameters ..............coueuuoon 216
DECTST Parameters .............. e
e e, 217
DT_LOG Parameters .............coouuueiuinii
217
DT_MASK Parameters ............couuuuei
i
ni 218
Phonemic Inventory ......
.. o
........ 220
Phonemic Emphasis Markers ...............coooueeinn
221

ARG

————"
g,

INTRODUCTION

This manual describes how to use DECtalk with a host computer. The text
explains the escape sequences you can use with DECtalk.

Terminals display information from a computer on a screen or paper; they
provide communication with computers through the sense of sight. DECtalk
speaks information from a computer in an English-language voice; it provides
communication with computers through the sense of hearing.
The DECtalk DTC01 Owner’s Manual (EK-DTC01-OM) describes how to use
DECtalk connected to a terminal. This manual describes how to use DECtalk
connected to a host computer.

Chapter 1 describes how DECtalk can communicate with a host computer
through computer application programs. The chapter also describes some
guidelines for writing applications.

Chapter 2 describes the setup escape sequences that initialize and control the
DECtalk environment.

Chapter 3 describes how to use voice commands, send phonemic text to
DECtalk, and load the user dictionary.

Chapter 4 describes how DECtalk works when connected to a telephone
network.

xii

INTRODUCTION

Chapter 5 describes the maintenance and debugging commands used to test
DECtalk.

Chapter 6 provides a detailed application program written in C programming
language. You can copy this program.

Chapter 7 provides a sample program written in BASIC-PLUS programming
language. You can copy this program.

The appendices summarize the DECtalk escape sequences, the
phonemic
alphabet used, and the other available DECtalk documentation.

AL,

HOW DECtalk
PROGRAMMING WORKS

This chapter gives you an overview of DECtalk programming. The chapter has
four major sections.

e ‘‘Communicating with DECtalk” describes the types of data DECtalk can
receive and the operating modes DECtalk uses.

e ‘‘Escape Sequences and Control Characters’ explains the basic format
for entering commands with escape sequences. This section includes a
table of the control characters that DECtalk recognizes.
e ‘DECtalk-Computer Communication’ lists some special rules DECtalk

follows when processing text. This section describes how escape

nal, and a computer. The section also describes data synchronization.

)

e “‘Developing Your Application’’ provides some guidelines for writing application dialog and encoding your program.

sequences affect the flow of information between DECtalk, a local termi-

HOW DECtalk PROGRAMMING WORKS

COMMUNICATING WITH DECtalk
DECtalk is an intelligent peripheral device, so the following guidelines apply.
e You cannot program DECtalk directly. After the initial power-up opera-

tions, DECtalk is controlled through a terminal or host computer.
e DECtalk is easy to control, because the internal DECtalk processor is

sophisticated enough to process complex operations with simple
commands.

SISAG

e You can select DECtalk’s operating characteristics and have DECtalk
answer questions (from the host computer) about its status. DECtalk can

also inform the host computer of status changes. For example, DECtalk
can tell the host computer if a connected telephone has rung.

e DECtalk memory can store some information. For example, DECtalk has

an extensive built-in pronunciation dictionary. You can load a user-

defined dictionary under computer control.
The following paragraphs describe how DECtalk sends and receives informa-

tion from the host computer.
Types Of Data

DECtalk can receive two types of data through its communications connector,
text and commands.
T

Text is data that DECtalk will speak. Text consists of English-language
sentences, phonemically spelled text, or a combination of both.

Commands are instructions to perform an action. Commands are not spoken
by DECtalk.
There are two ways to send commands - with escape sequences or with
square brackets []. Some commands you can only send with escape
sequences, and some commands you can send both ways.

Escape sequences start with an ESC character, followed by a string of ASCI
characters. DECtalk interprets the string as a special command. This manual
describes the escape sequence method of sending commands.
i

Square bracket [] commands let you include speech commands and phonemic
text with text information, if MODE SQUARE is on.

HOW DECtalk PROGRAMMING WORKS

The ‘““Mode Selection’’ section in Chapter 2 describes MODE SQUARE. The
DECtalk DTC01 Owner’s Manual describes square bracket commands and
syntax.

Appendix B summarizes both command methods. Figure 1-1 shows the rela-

tionship between terminal commands and host commands. This chapter provides more information on escape sequence conventions and format.

| SETUP>SET LOG PHONEME ON

DECtalk

ON-LINE
MODE

HOST

Figure 1-1

DECtalk, Terminal, and Host Communications

MA-7590-83

HOW DECtalk PROGRAMMING WORKS

Operating Modes
DECtalk has three operating modes: setup, off-line, and on-line.
You use setup mode to select the operating parameters of DECtalk, such as
communication line characteristics and phonemic representation.
You use off-line mode when DECtalk is connected to a terminal. The DECtalk
DTCO1 Owner’s Manual describes off-line mode.
)

You use on-line mode when DECtalk is connected to a host computer. Commands must be sent as escape sequences from the host computer.

DECtalk powers up in on-line mode. When you connect DECtalk to a terminal
for local use, you must switch DECtalk to off-line mode; press the BREAK key
to enter setup mode, then select the off-line setting.

USING ESCAPE SEQUENCES AND CONTROL CHARACTERS
This section describes the general syntax of escape sequences, and how to

use them with DECtalk.
AR

Escape Sequences
In setup mode, you can enter commands directly to DECtalk through the
terminal.

When DECtalk is on-line, you can enter most setup commands plus other on-

line commands; however the commands come from the computer instead of

the terminal. For example, you can only load the user-defined dictionary while
on-line.

On-line and setup commands act the same, but they have different formats.
For example, the user command
SETUP>SET

LOG

PHONEME

is sent from a computer as an escape sequence

ESCPO0;81;2zESC\
You can omit parameters with a value of 0 (ASCIl). For example, you could
send the above sequence as ESC P ;8 1 ;2 z ESC \. DECtalk does not send
parameters with a value of 0 in its reply sequences.

NOTE:

Escape sequences in this manual are spaced for clarity only. Spaces

are not part of the actual escape sequences.

HOW DECtalk PROGRAMMING WORKS

DECtalk escape sequences have the following characteristics.
1. They begin with an ESC character.

2. The ESC character is followed by ASCIlI characters that define the
command.

3. Every character in the command is important. You must enter the exact
characters shown. For example, in the command above, the semicolons

are part of the command. The letter z is lowercase; an uppercase Z has
no meaning to DECtalk.

Programming standards require that you end some commands with a

sequence terminator - ESC \. This manual includes ESC \ with all commands that require it.

5. Escape sequences only work on the DECtalk host line. This is different
from most terminals, which can interpret typed escape sequences.

The ESC character plus the ASCII characters are like a compressed version of
the off-line commands. Figure 1-2 shows the meaning of each part of a typical
escape sequence.

DECtalk ignores invalid sequences and commands.

BEGINNING OF ESCAPE SEQUENCE
DECtalk COMMAND
SET LOG

ESC

PHONEME ON

DECtalk COMMAND TERMINATOR

: END OF ESCAPE SEQUENCE

PO : 81 : 2z ESC\
DELIMITER
MA- 1891 A-83

Figure 1-2

Typical Escape Sequence Format

HOW DECtalk PROGRAMMING WORKS

Escape Sequence Format

The following chapters describe the specific escape sequences used with

DECtalk. This manual includes the following information with all escape
sequences (Figure 1-3).
Mnemonic

ASCII characters
Parameters

Decimal value

NOTE: Since DECtalk suppresses parameters with a value of 0, DECtalk
would send ESC P ; 31 ; P3 Z ESC \ for the sequence in Figure 1-3 (assuming
P3 is not 0). If P3 is 0, DECtalk would send ESC P ; 31 ; z ESC \.
oy

The mnemonic is a unique name (such as DT_INDEX) used to identify the
escape sequence. Mnemonics do not have any direct programming significance; that is, DECtalk does not recognize a mnemonic name as a valid escape
sequence. However, when you refer to escape sequences by mnemonic in
program documentation and program variables, it simplifies editing and
debugging.

The program examples in Chapter 6 use mnemonics for the appropriate
escape sequences. The header file DECTLK.H in Chapter 6 defines all DECtalk

command mnemonics.
e

DT_QUERY__REPLY

——

(ESCAPE SEQUENCE MNEMONIC)
RSy

ESCAPE CHARACTER
ASCIl CHARACTER P

ASClI CHARACTER ZERO
ASCII CHARACTER ;

ASCII CHARACTER 3

ASCII CHARACTER 1 (NOT LOWERCASE L)
DELIMITER

ESC

;

027 080 048 059

051

PARAMETER

|
DECtalk COMMAND TERMINATOR
l : END OF ESCAPE SEQUENCE

049 079 *"Ti—mz

ESC

TM\

(ASCIlI REPRESENTATION)

027 092 (DECIMAL VALUE)

' INDICATES VARIABLE VALUE

Figure 1-3

Escape Sequence Representations

MA-7592A-83

HOW DECtalk PROGRAMMING WORKS

The ASCII characters are the actual characters to use. The ‘‘Escape
Sequences’’ section in this chapter gives an example of an escape sequence in
ASCII format. The escape character is represented by ESC in all sequences.
The numbers that appear are actual ASCII characters, not numeric values.
Parameters appear in escape sequences that can cause several DECtalk

actions. These different actions depend on parameter values.
Parameters
are represented in this manual by a capital P followed by a number
or letter. Parameters are always sent to DECtalk as a decimal number, in ASCII
format.
An empty parameter is treated like a parameter with a value of 0. The

sequences ESC P ; z and ESC P 0 ; 0 z are identical. DECtalk always sends a 0
parameter as an empty string. However, the 0 parameters are always shown

as explicit zeros in examples.
This manual lists possible parameter values in tables. There are two methods

used to show parameter values.
1.

Usually the ASCII character(s) appears (with the decimal value under-

neath as a check). Use the ASCII character(s) in the escape sequence.

2. Sometimes only a numeric value appears. You must convert the numeric
value to a sequence of ASCII characters for the escape sequence.

The decimal value of each escape sequence character appears directly under
the character, so you can verify the sequence characters. Parameters are
marked with asterisks (***), indicating that the value is variable.

Chapter 2 provides complete tables of all ASCII characters and their decimal,
octal, and hexidecimal equivalents.
Figure 1-3 shows all the parts of an escape sequence.

Control Characters

Some control characters (such as carriage return and backspace) have special
meanings. Table 1-1
-

lists the control characters that DECtalk recognizes.

DECtalk ignores any other control characters.

HOW DECtalk PROGRAMMING WORKS

Sy,

HOW DECtalk PROGRAMMING WORKS

Control Character Logging
Version 2.0 of DECtalk firmware improves control character logging. Before
version 2.0, some control characters were not correctly logged. In particular,
the CTRL-K (clause flush) control character sequence (generated internally by
DECtalk), was not logged unless DECtalk received text from the host in 5

seconds. If a heavily loaded system was slow to respond, DECtalk might not
log the current event.

For example, suppose the host system stopped sending data in the middle of a
phonemic text string or an escape sequence. DECtalk would execute a time-

out, exit phonemic text mode (or ignore the escape sequence), and fail to log

the event. The result was problems for the application developer in tracking
control character logs.

NOTE:
You should enable LOG_INHOST or LOG_RAWHOST to ensure the
proper logging of all characters. See “Local Log Control (DT_LOG)" in Chapter 5 for more information on control character logging.

Effect of the Backspace (BS) Character

If DECtalk finds the backspace character in a word, DECtalk modifies the word
according to the hierarchy of the characters involved, as follows.
1. letters and digits

2. punctuation

3. underline character
The BS character allows DECtalk to process text containing overstrikes and
underlining.
Here are several examples of DECtalk’s processing (spaced for clarity).

Input

Pronounced as

a BS b

ab BS BS de

HOW DECtalk PROGRAMMING WORKS

DECtalk-COMPUTER COMMUNICATION

Programming DECtalk is similar to programming a smart terminal (such as a
VT220). That is, DECtalk and the host computer must exchange information

according to fixed rules.
DECtalk does not process text until reaching a valid clause boundary. Clause

ARSI

boundaries mark the end of phrases or sentences. DECtalk recognizes the
following clause boundaries.
e A period, comma, exclamation point, or question mark is a valid bounda-

ry. If a period is used, DECtalk checks the characters after the period

(because periods do not always mean the end of a sentence).

e A full buffer also acts as a boundary. If DECtalk’s temporary buffer begins

to approach its fill limit (at about 12 words), DECtalk begins speaking
what is in the buffer and treats the last word as a clause boundary.
[

e A timeout is another boundary. If nothing is sent to DECtalk within 5
seconds and there is text in the buffer, then DECtalk speaks all text in the

buffer as though a comma had been sent with the text.

Escape sequences represent (1) commands sent from the host to DECtalk, and

(2) status replies sent from DECtalk to the host. All escape sequences begin
with the ESC character; a sequence ends when the last character required for
that sequence is sent. Do not use a carriage return or any other normal

terminating character to terminate an escape sequence.
Figure 1-4 shows the data paths in DECtalk, as follows.

1. The DECtalk unit is in the center of the figure. The speech processor is

part of the DECtalk unit, but is shown as a separate module.
2. Arrows show the direction of information flow. Notice that information
flows from the terminal (or telephone) to the host, and from the host to the

terminal (or telephone). However, information only goes to the speech
processor from the host or terminal. Information from the speech proces-

sor is sent to the telephone or speaker.

3. Each DECtalk escape sequence affects the flow of information within
particular data paths. The switches within the data paths represent the
points at which the escape sequences act. For example, the DT_STOP
escape sequence affects the data flow from the host to the speech
processor.

—

HOW DECtalk PROGRAMMING WORKS

SPEAKER

SPEECH
PROCESSOR

HOST SPEAK
-0

LOCAL SPEAK

LOCAL HOST

pom—

‘

LOGGING

TERMINAL

—0” O— =SWITCH OFF

SPEECH PROCESSOR SEQUENCES

LOGGING SEQUENCES

DT _MODE:MODE __SQUARE

| DT __LOG:LOG __RAWHOST

DT _MODE:MODE __MINUS

DT _LOG:LOG_TEXT

DT WMOD‘E:MODE _.._.ASKY

DT L LOG: LOG . TRACE

| DT _PHOTEXT

DT _LOG:LOG__PHONEME

DT _ LOG:LOG
__ INHOST
-

DT _LOG:LOG__ERROR

LOCAL HOST SEQUENCE

DT _LOG:LOG

__ OUTHOST

DT__TERMINAL:TERM __ HOST
DT__.TERMINAL:TERM _FILTER

LOCAL SPEAK SEQUENCES

HOST SPEAK SEQUENCES

' DT__TERMINAL:TERM __SPEAK

DT __STOP

DT__TERMINAL:TERM _EDITED
|

DT_TERMINAL:TERM __SETUP

DT __SPEAK
|

DT __TERMINAL:TERM_HARD
MA-7593-83

Figure 1-4

DECtalk-Computer Program Interaction

4. Since there are a large number of commands and parameters, they are
grouped in boxes under the diagram.

Some commands have parameters (sometimes called arguments). Figure
1-4 shows commands and their parameters. The parameters (if any)

appear after a colon (:) mark.
There are many ways to control and use DECtalk when connected to a host
computer. The rest of this chapter and the sample program in Chapter 6

describe a general programming method for DECtalk. If you are writing a
control program for DECtalk, remember that your application and needs may

—

not match the descriptions that follow exactly.

HOW DECtalk PROGRAMMING WORKS

DECtalk Setups
The controlling program first configures DECtalk to ensure that all parameters

are set correctly. Use these steps in your program.
1. Programs may wish to send a ‘“What are you?’’ sequence to make sure

DECtalk is available. DECtalk replies with a code correctly identifying
DECtalk.
The “‘Device Attribute Request’’ section in Chapter 5 describes ‘‘What are

you?'’ sequences.
2. Send setup commands to configure DECtalk for host-DECtalk communication. The required setup commands vary from computer to computer
and from application to application; however, here are some commands
[

to consider.
a. Include any required communication command (such as 7-bit or 8-bit

codes, and code interpretation. See ‘‘Selecting ASCIlI Character Sets”
in Chapter 2.
[,

b. Set MODE SQUARE on (if desired). This command ensures that phonemic code values are accepted. See ‘“Mode Selection” in Chapter 2.

c. If you connect DECtalk to the public telephone network, select the
correct telephone handling parameters. See Chapter 4 for these
parameters.

3. You may have to set up the host computer (or DECtalk communication
line) for DECtalk commands. You must set up the computer for singlecharacter,

unsolicited

input,

and

operating

system

XON/XOFF

processing.

Setting up computers is beyond the scope of this manual; however, Chapter 6 has examples of setting up certain Digital EqQuipment Corporation

computers for DECtalk.
If your host computer cannot support single-character processing, you
can

use the

DT_MASK escape

sequence to permit line-at-a-time

processing. See ‘‘Keypad Mask Command (DT_MASK)"’ in Chapter 5.
A

4. Other commands depend on the DECtalk environment, such as debugging commands or special text-to-speech commands.

HOW DECtalk PROGRAMMING WORKS

Program Control

DECtalk is primarily a speech device; its internal code is directed towards
producing artificial speech. DECtalk assumes the host computer will handle
most of the necessary control operations (such as waiting for task completion
and requests for status).

The host is responsible for control and coordination, but this is not a major
task. The rest of this chapter describes areas you should consider when
designing the DECtalk program application.
Data Synchronization

DECtalk’s speech rate is much lower than the (potential) data transfer rate on
the host communication line. DECtalk sends an XOFF character (CTRL-S) to
the host when its input buffer is almost full, to signal that any more input will be
discarded. When DECtalk’s input buffer is almost empty, it sends an XON
character (CTRL-Q); XON tells the host to start sending data again.

The DECtalk input buffer is large enough so that the host can continue sending
data at the highest speed (9600 baud) for up to 250 milliseconds after it
receives the XOFF, without losing data.

Figure 1-5 shows how DECtalk synchronizes data transfer with the host

through XON/XOFF signals.

If the host does not stop sending data in time, the input buffer may overflow
and characters may be lost. DECtalk does not give an audible warning of this
overflow, except for the obvious garbling of partial words. The host can issue a
device status request (DSR) command to determine if an input buffer overflow
occurred.

Most operating systems have a HOSTSYNC option (or its equivalent) in the
terminal setup characteristics. If this characteristic is set on the DECtalk communications line, the host computer handles XON and XOFF signals. If
XON/XOFF coordination is not available, the application program may be able
to avoid buffer overflow by using the DT_SYNC command and controlling the
program’s output rate; however, Digital does not recommend this method
because it causes errors. The ‘‘Data Synchronization” section in Chapter 3
discusses DT_SYNC.

HOW DECtalk PROGRAMMING WORKS

Ry,

[

HELLO. | AM DECtalk. WHEN IN THE
COURSE OF HUMAN EVENTS....

—

MUMBLE . . . MUMBLE...
DECtalk
L

—

...OF HUMAN

EVENTS...

..WHEREFORE HE HATH CAUSED...
..MUMBLE . . . MUMBLE...
[

XOFF

________.//

DECtalk

—.

L.-WHEREFORE...)

HOST PAUSES WHILE DECtalk EMPTIES ITS BUFFER.
DECtalk

...HE HATH CAUSED...

XON

DECtalk

DECtalk’'s BUFFER IS NEARLY EMPTY, SO IT SENDS XON.

B—

... THANK YOU FOR... )

...MUMBLE . . . MUMBLE...
2

I THANK YOU FOR

LISTENING TO ME.
DECtalk

HOST RECEIVES XON AND RESUMES TRANSMISSION.

Figure 1-5

Synchronizing DECtalk and Host Communications

MA-7596.83

oy,

HOW DECtalk PROGRAMMING WORKS

DECtalk-Host Program Sequence

After you set up a parsing method so data can pass between the host computer and DECtalk, you should set up the host for the kinds of data to receive.
How you set up information handling depends on the needs of the user. The
following section provides some guidelines for developing your application’s
dialog.

DEVELOPING YOUR APPLICATION

DECtalk lets people use your computer-based applications from any keypad
telephone. DECtalk speaks your messages in an understandable voice. When

the user presses keypad keys, DECtalk sends those characters to your program. The following guidelines should help you adapt your application to your
unique needs.

General Guidelines

e Keep the user’s point of view, not the programmer’s. Use commands that
are logically related to the way users see the task.
e Most people will not carry a large user guide around with them.
e Frequent users become experts quickly.
Writing Dialog

e Keep dialog simple, but meaningful.

e Organize each message as follows.

1. Put the hardest element to remember first.

2. Put the easiest elements to remember in the middle.
3. Put information for immediate recall at the end.
e Tell users only what they need to know in order to continue a task.

e Do not use humor or threats. Keep dialog strictly factual and informative.

HOW DECtalk PROGRAMMING WORKS

Help Messages and Replies
e Make help messages optional. Let users decide when they want more

information.

e Repeat significant phrases in help messages.
e Let users know that DECtalk is acting on their specific commands. For
example, say “Sending reply to Ms. Jones,” rather than ‘‘Sending reply.”

Entering Keypad Commands
e

Remember, there are only 12 keys on the telephone keypad.

e Keep the same function on the same key.
e

Refer to keypad numbers, not letters. People do not remember
which

letter is on which key. Use “Press 1 for next, 2 for previous, 3 to exit,”
rather than “‘Press N for next, P for previous, E for exit.”

e Create a standard method for users to exit from a subtask to the main

dialog.

Names, Part Numbers, and Alphanumeric Text
In many DECtalk applications, you use the 12 keypad keys to enter a person’s

name or an alphanumeric part number. Since the application program
only

receives a string of digits (and the # and * characters), the program must
use
the digits as an index to the actual data item.

If you are designing a new system, you could specify numeric part numbers

only. However, in the real world, a company is not going to change its existing
warehouse methods to match DECtalk. So the user will have to enter some-

thing that your application can translate into the current system.
Direct Numeric Encoding

Using this method, the user simply presses the key labeled with the desired
letter. For example, to select “DIGITAL" the user would press 3444825.
You
could assign the letters Q and Z to the 7 (PQRS) and 9 (WXYZ) keys,
respectively.

HOW DECtalk PROGRAMMING WORKS

Numeric encoding is a simple method to describe and implement. Since users
can recall more than one item for a given digit string, your application must
provide a way to select alternatives. You could have users select alternatives
by number. Or you could have them step through a list, using next and previous
commands.

Numeric encoding is probably the best method for lists of names and for many
part number applications. You can even use this method for ID or password
entry.

Two-Character Encoding

Some applications use specific letters in their codes (for example, three-character airport codes). You cannot use direct numeric encoding to select specific
letters on the keypad.

One possible solution is two-character encoding. This method matches the
three letters on each key to the three columns of keys on the keypad. The user

presses two keys to select a letter.

”

1. The key with the desired letter

2. The 1, 2 or 3 key (to select the specific letter)

For example, to select “DEC” the user would press 313223. You could have
users enter numbers together with the 0 (OPER) key. And you could assign the
missing Q and Z (plus the space character) to the 1 key.

The United States Federal Aviation Administration used the above method to
provide a voice response weather system. (The USFAA used stored segments
of speech - DECtalk was not available at the time.)
Ending Commands and Data

You can use single-character commands and fixed-length data fields for many
applications. But for complex applications or variable-length data you may find
it simpler to ask the user to end all commands and data by pressing a special
key (such as #). Pressing # lets the program know that the right number of
characters have been entered.

You could also use DECtalk’s flexible keypad timeout facility. If the user is
entering a variable-length numeric field, use a long timeout for the first digit and
(possibly) a shorter timeout for successive digits.

HOW DECtalk PROGRAMMING WORKS

Application Development Tips
Here are some tips for encoding the application itself.
e

Use timeouts for everything. Assume
that the user may hang up the

phone at any time. Also assume that data entry will

be quite slow. This is
important when planning data base entry and recordlocking strategies.

The DECtalk applications support library may return
an error code due to
transient problems (such as a system overload).
The simplest recovery is
to hang up the call and reinitialize DECtalk. Log the
problem for future

action.

People can recall about 5 seconds of text without difficulty

. You can use
entries such as ‘1 for yes, 2 for no, 3 for maybe,
” but do not ask an
untrained user to remember anything more complex
.
DECtalk tends to spell out text that may be ambigu
ous (for example, part
numbers). You can write a small filter subroutine
that recognizes certain
strings and pronounces them in a form more
suitable for your specific

———

application.

I your application accepts data from the telepho

ne keypad, make sure
the operating system can buffer type-ahead charact
ers. Also, make sure
the operating system responds to DECtalk’s XOFFs.
DECtalk speaks pending text if the host system stops

seconds. This feature may be a problem on an

delivering text for 5

overloaded system. You

may need help from the system manager
to obtain more resources or

adjust program priorities.

When you have DECtalk speak information from
a data base, remember
that the listener hears the information only once.
You should offer a
repeat function for complex subject matter. If you
have DECtalk read mail

or other unstructured text, you should offer
a back up one sentence

function, using the Index Test command (Chapt
been heard.

er 3) to signal what has

AR,

SETUP ESCAPE SEQUENCES

DECtalk has several features you can change to control the operating environ-

ment. These parameters include the following.
e line characteristics (such as line speed)

e character sets (to send and receive information)

e modes (to control DECtalk’s interpretation of special characters and phonemic text)

There are also several testing and inquiry commands, described in Chapter 5.

SETUP ESCAPE SEQUENCES

SELECTING ASCIl CHARACTER SETS

oy,

DECtalk is a computer terminal device, and conforms to the standards
for

computer terminals.

RO,

DECtalk speech does not include much of the visual information of character
sets. For example, DECtalk uses the following rules for all character sets.
1. Uppercase and lowercase letters are considered the same. For example,
DECtalk speaks the letter G as ‘‘gee,”” not “‘uppercase gee.”

2. Foreign letters (as found in the multinational character set) are spoken

as
English. For example, DECtalk speaks the letter 4 as “‘a,”’ not “‘a umlaut.”

3. You can translate or map 7-bit codes into 8-bit codes, and 8-bit codes into
7-bit codes (Figure 2-1). This mapping has no effect on spoken text.

Table
2-1 gives the escape sequences that change DECtalk to 7-bit
or 8-bit
modes.

The following paragraphs describe how DECtalk interprets certain
keyboard
(or host computer) generated codes.
O

g 35,

A5,

SETUP ESCAPE SEQUENCES

\\ [V

‘P MAPS INTO ITS
8-BIT EQUIVALENT (208)

v 4 000

vT | 68C

‘ESC’ MAPS INTO ITS

8-BIT EQUIVALENT "CSI’
MA-7594-83

Mapping 7-Bit and 8-Bit Tables

Figure 2-1

g e
i

e
o

SETUP ESCAPE SEQUENCES

CODING STANDARDS

AR
i,

The DTCO1 uses an 8-bit character encoding scheme and a 7-bit code exten-

sion technique that are compatible with the following ANSI and ISO standards.

ANSI (American National Standards Institute) and ISO (International Organiza-

tion for Standardization) specify the current standards for character encoding
used in the communications industry.

Standard

Description

ANSI X3.4 - 1977

American Code for Information
Interchange (ASCII)
ORIy

ISO 646 - 1977

7-Bit Coded Character Set for
Information Processing Interchange

ANSI X3.41 - 1974

Code Extension Techniques for Use
with the 7-Bit Coded Character Set

of American National Code Information
Interchange
L.

ISO Draft

7-Bit and 8-Bit Coded Character

International

Sets - Code Extension Techniques

Standard 2022.2
ANSI X3.32 - 1973

pms———

Graphic Representation of the

Control Characters of American
National Code for Information

Interchange
ANSI X3.64 - 1979

Additional Controls for Use with

American National Standard for
Information Interchange

ISO Draft

International

Additional Control Functions for

Character Imaging Devices

Standard 6429.2

SETUP ESCAPE SEQUENCES

CODE TABLE
A code table is a convenient way to represent 7-bit and 8-bit characters,

because you can see groupings of characters and their relative codes clearly.
7-Bit ASCII Code Table
Figure 2-2 is the 7-bit ASCII code table. There are 128 positions corresponding

to 128 character codes arranged in a matrix of 8 columns and 16 rows.

COLUMN
b7

ROW]

BITS

b4 b3 b2 b1

|[NUL|

|SOH|

0010

0011

Oloooo
o001

|STX|
|ETX]|

o
0
1

|DC2]|

gmcm

o1 o1

|ENQ|

|NAK

o110

|ACK|6c
6

0111

|BEL|7

11]
12]

13]
|

1o 1 0o

1 o 1 1
+

14|
15

50
32

% | 3
&
)

)

|]CR

|SUB|

|13 | GS | 20|
D

’

56
70

40
28
51

ssl

74
o]

3c
75

61]

|12 | RS | 2

62]

|s|

US|

| ESC | ,,

2€

47
2F

so ] K

|42

56
38
71

54
44

54
36

+ | a3

3€

s3]
3F

M
N
O

101

|es]
a1

102

||
42

103

67]

104

106

| o]
46

107

110

| 4]

114
6]
4c

122

142

123

143

8|
62
9|

124

144

54
125

64
145

147

[
\

130

150

131

151

88
58

132

133

{
|

135

155

136

74
165

|7
75

166

|18
76

170

120
78
171

121

172

107
68

116

154
we]|

164

167

115

w | 119

05|

153

163

we|

104]
68

152

|13

r | na
72

134
92

161

162

160

|12
70

w2
66

3 1

127

wo]

146

117
9]
4F

6|
60

141

116

121

W
X

140

V | s
56

|
48

11|

120

82
52

S
T

80
50

44
105

| 122

173

123
78

174
124
7C

109

}

156

175

125

mo|

T | 126

137

157

177 |

| %
5F

|
6F

DEL | 127
7F

| ocTAL

DECIMAL

18 _J HEX

Figure 2-2

|38
26

@ | 64
40

34
65

100

24
a5

27|

| =

14
34
|12 | FS | 28

|ESC|

26|

HT | 9 | EM | 25
|10

14
25

CHARACTER

(

34
22

2
18

| LF

18
12

|CAN|

8]
30

|8
8

|ETB | 23

SP | 32
20
!

|SYN|22|
16

1 10 | SO
+

1o o0 | FF

11 01

4
5

|DC4|

10|

®]|
10

1 o011

|55 | 7

|EOT|

o100

o000 ] BS

|DLE|

7-Bit ASCIl Code Table

MA-0893A-83

e iy,

SETUP ESCAPE SEQUENCES

BIT

l_‘

BIT

J‘

4 LEAST

-vlw

3 MOST
SIGNIFICANT BITS

SIGNIFICANT BITS

(DECIMAL VALUE IS

(DECIMAL VALUE

COLUMN IN

IS ROW IN

CODE TABLE)

MA-0890-83

Figure 2-3

7-Bit Code

Each row represents a possible value of the four least significant bits of a 7-bit
code (Figure 2-3). Each column represents a possible value of the three most
significant bits.

Figure 2-2 shows the octal, decimal, and hexadecimal code for each ASCII
character. You can also represent any character by its position in the table. For

example, the character H (column 4, row 8) can be represented as 4/8.
DECtalk processes received characters based on two character types defined
by ANSI, graphic characters and control characters.

Graphic characters are characters you can display on a video screen. The
ASCII graphic characters are in positions 2/1 through 7/14 of Figure 2-2. They
include alphanumeric characters plus punctuation marks and various text sym-

bols. Examples are C, n, ““, !, +, $.
Control characters are not displayed. They are single-byte codes that perform

specific functions in data communications and text processing. The ASCII
control characters are in positions 0/0 through 1/15 (columns 0 and 1) of Figure
2-2. The SP character (space, 2/0) can be considered either a graphic charac-

ter or a control character depending on the context. DEL (7/15) is always used

as a control character.

Control character codes and functions are standardized by ANSI. Examples of
ASCII control characters with their ANSI-standard mnemonics are CR (carriage

return), FF (form feed), and CAN (cancel).

SETUP ESCAPE SEQUENCES

8-Bit Code Table

The above conventions can be generalized to the 8-bit character encoding
used on DECtalk. Figure 2-4 shows the 8-bit code table. It has twice as many
columns as the 7-bit table, because it contains 256 versus 128 code values.
|

[COLUMN

\ o0l ot]o2|l03|04]05]|06|07 08|09 10|11 ]12 | 13| 14} 15
ROW

NUL | DLE | sP

pDcs

SOH | DC1

PU1

STX | DC2

PU2

| ETX | DC3

STS

EOT | DC4

IND | CCH

| ENQ | NAK

NEL | MW

| ACK | SYN

SSA | SPA

BEL | ETB

ESA’ EPA

BS | CAN

HTS

HT | EM

HTJ

LF | suB

VTS

vT | ESC

PLD | CSI

FF | FS

PLU | ST

CR | GS

RI | OSC

so | RS

ss2 | PM

<5 copesTMTM
}4

|/l

DEL | SS3 | APC

GL CODES

7-BIT CODE TABLE

~{~sTcopes

GR CODES———————>|

MA-0892-83

Figure 2-4

8-Bit ASCIl Code Table

SETUP ESCAPE SEQUENCES

BIT

—

4 MOST

SIGNIFICANT BITS

(DECIMAL VALUE IS
COLUMN IN
CODE TABLE)

4 LEAST

SIGNIFICANT BITS

(DECIMAL VALUE
ISROW IN
CODE TABLE)
MA-0BD1-B3

Figure 2-5

8-Bit Code

As with the 7-bit table, each row represents a possible value of the four least

significant bits of an 8-bit code (Figure 2-5). Each column represents a possible

value of the four most significant bits.

All codes on the left half of the 8-bit table (columns 0 through 7) are 7-bit
compatible: their eighth bit is not set and can be ignored or assumed to be 0.

You can use these codes in either a 7-bit or an 8-bit environment. All codes on
the right half of the table (columns 8 through 15) have their eighth bit set. You

[

[EC
-,

can use these codes only in an 8-bit compatible environment.

The 8-bit code table (Figure 2-4) has two sets of control characters, CO (control
zero) and C1 (control one). The table also has two sets of graphic characters,
GL (graphic left) and GR (graphic right).

On DECtalk, the basic functions of the CO and C1 codes are as defined by
ANSI. CO codes represent the ASCII control characters described earlier. The

—

CO codes are 7-bit compatible. The C1 codes represent 8-bit control characters
that let you perform more functions than those possible with the CO codes. C1

codes can be used directly only in an 8-bit environment. Some C1 code positions are left blank because their functions are not yet standardized.

NOTE:

DECtalk only recognizes the SS2, SS3, DCS, CSI, and ST control
codes. The others are ignored.

e —

The GL and GR sets of codes are reserved for graphic characters. There are

94 GL codes in positions 2/1 through 7/14 and 94 GR codes in positions 10/1
through 15/14. By ANSI standards, positions 10/0 and 15/15 are not used. You

can use GL codes in 7-bit or 8-bit environments. You can use GR codes only in

an 8-bit environment.

e—

SETUP ESCAPE SEQUENCES

CHARACTER SETS
You cannot change the functions of the CO or C1 codes. However, you can

map different sets of graphic characters into the GL and/or GR codes. The sets
are stored in the terminal. But they are not available for use until mapped into
the GL or GR codes.

Selecting Alternate Character Sets (GO - G3)
DECtalk has four alternate character set areas: GO, G1, G2, and G3. When
DECtalk powers up, it loads the ASCII_G (7-bit) character set in alternate
buffers GO and G1. The DEC multinational (8-bit) character set is loaded in
alternate buffers G2 and G3.

DECtalk does not call the alternate character sets directly from GO, G1, G2, or
G3. The selected set is first mapped into the GL or GR areas, then used to
interpret the next received (or transmitted) character. So, three factors determine the active character set.
e Which character area is active: GL or GR

¢ Which alternate set is mapped into the active area: G0, G1, G2, or G3
e Which character set is loaded in the alternate (GO or G1) set: ASCII_G or
multinational

Figure 2-6 shows how you can map the ASCII_G and multinational sets into the
alternate character set buffers. Figure 2-7 shows how you can select active
character sets.

Table 2-2 gives the escape sequences and control characters that load and
select alternate character sets. Table 2-3 gives the escape sequences to load
active character sets into GO through G3.

SETUP ESCAPE SEQUENCES

I co

—
1

3Y(4)(s5)

8 - BIT FORMAT IN USE

@ S1 OR LSO

@ SO OR LS1

@ SS2 OR LS2
LS1R

GO
ESCI..IF

ESCI..IF ESCI. IF ESCT.. IF

SS3 OR LS3

@ LS3R
DESIGNATION OF GRAPHIC SETS
O

GRAPHIC
REPERTORY
e,

MA-0279A-82

Figure 2-6

Loading 8-Bit Characters

AORsoy

7-BIT FORMAT IN USE
A

S1 OR LSO

@ S0 OR LS1
RS,

582 OR LS2

@ SS3 OR LS3
ESC | ..IF

ESC | IF

ESC | ...IF

—

ESC | ..IF

GRAPHIC
REPERTORY
A,

MA-O2B0A-B2

Figure 2-7

Selecting Active Character Sets

SETUP ESCAPE SEQUENCES

DEC Multinational Character Set

By factory default, when you power up or reset DECtalk, the DEC multinational

character set is mapped into the 8-bit code matrix (columns 0 through 15).
Figure 2-8 shows the DEC multinational character set.

COLUMN

b8 b.['Bl'l"S

proom
|

ROW]

0 0

b4 b3 b2 b1

Ojoooo

|[NUL|
_

o001

|SOH|

o010

|STX|

o011

ETX!|

o100

|EOT|

o
1

|DLE|

40
20

]| SP

QON]

|DC2|w]
12

3
3

4«

PXL%F

19
M

|DC4|

5|
6]

o101
0110

0111

1000

1001

11
121

1+
1+

13]

o 1
1

1
o

151

|32

|aa]

35
23

1
60

||
61

|s]|]

3
4

102

|e|

51
33

103

67
43

104

106

|BEL|;
| BS

|[SYN

|ETB | =3

26
a7

|s4

36
67

| ss

| 2]

107

122

22|

123

83
53

124

125

ss|

127

87|

162

|na

143

99
63

144

|woo]

164

¢t

116
74

145

|10

166

[102]

147

| 103

|ns

130

150

170

(

111

131

| EM | 25

19
32

|10

|SUB | 26|

|+
B

|12
c

|ESC|

27|

| FS | 28

C
35

»)

|13 | GS | 2

US | a

+——co~OMES
cooes
KEY

"l
|

9
.

)

28
54

’

20
56

£
:

=
>

26
57

| 42

+ | a3

1E
37

| 5]

a1
29

)

58 |

sa |
38

3c
75

611

113

K
L

a4l

133

58
134

5C|

135

]

B3l

120

E—

.78

171

05|

153

154

108

109
186

137

125
70

110

176

126

157

177

m | DEL | 127

GL CODES

‘

a—

175

}

(ASCI GRAPHICS)
|

174

124
7C

155

136

123

173

{

116

|2
7A

k | 107

172

121
79

152

[

04|

151

]

59
132

|19

S—

167

110

|CAN|

E—

165

146

"1
-

OCTAL

DECIMAL

18§

HEX
SN

MA-0893-83

Figure 2-8

115
73

;

163

E S(:

142

|13

161

| CR

|12

160

141

| LF

[8]|

140

126

HT [ ¢

22|

105

s1l

121

|NAK | 2

|]ACK|

% | 3

120

P | so

|es|

|e|
101

0
100

|ENQ| 5

0o | SO | 14 | RS

CHARACTEH

9
,

2
3

0
0

0 0

DEC Multinational Character Set (Left Half)
Fl

SETUP ESCAPE SEQUENCES

J——

0 0

200

128

p—

160

144

A AO

129 | PU1 | 145

30 | PU2|146]
203

223

201

221

202

222

241

o
o

161

€

242

|12

243

Al
A2

|63

227

|16

210
HTS | 136

230
152

250
|1e8

211
HTJ | 137

231
53]

251
|60

212

232

|22

154

VTS | 138

213

214

PLU |[150|

CSI

A8
A9

170

|15

253

|m]

234

254

|16

Figure 2-8

74|

|ies|

§
|

277

257

wa|
AD

73|

ws|AF &

150oF
1438F | APC | 237
SS3 || 217
P

|32

216
|42

[ g

4
|

2
PM | 158

C1 CODES

||
8D
BE

|22

|313]

03|

|314

|2a|

315

|2
cD

§
A

|38
206

D8
D9

227

344

|28]

0100

|29
£S5
2
|[2|

0101

]85

Es |

347

&
D
R
©

|28]

[333

|29

334
|220]

&
€

335

e
222

|,
i

||DD
DE

352

|=za|

354

[226]

355

||
ED
[3%6
238

|24]

365

|2as]
F5
E
|us]

011016

367

370
|[248]

1000

3n
||

1001

|20]

351
||

332

364

€9

350
|22

0111

361

|27

331
(27|

we|

[|2>]|

|22

330
|26]

|
|2

,
g

||
ws|

276 |
190

255

[328]

|2s5]

§ | 310
|20]
g

‘

327

22|

307

270
wa|

324

|213]
D6
|326
|24]

o
|w|
cs
306 | .o
o
[98]

[1wo]

256
174

235

35|

275

215

|1180 | OSC | 157
9D

€

]13

|196

o011

|343

233

267

363

225

2431

323

205

247

’

211

|303

195

o010

|1B1]
85
266
|w|

|22]

342

|263]

265

362

|20

304

M
[ws]
AB
246
es | §

322

245

o000 1|1

264

|241]

e | @

b5 =

b4 b3 b2 bl JROW
o o oo | O

341

o7 BITS
b6

302

178

240

|32

;

360

|30

225

|262

180 | *a

301 | o

164

|20

193

208

|'co

224

179

20|

COLUMN

14
1

192

261

|300

244

EPA |1 | §

SS2

176

187

|260]

224

207

ESA ||

PLD

204

NEL |133| MW |1ao|
95
85
226
206
SSA | 134 | SPA | 150

f—

220 % /A220]

IND | 132| CCH | 148

—

20 | PCS | "o

131 | STS | 147

8
1

F8
Fo

372

101 0|10

BINBEE

100

|11

[»2]

100

|12

375

|13

376
a4l

111 0

114

374

FC
FD
FE

w)FF 1111 |15 |
|2EF U/Z /) 377
23]DF % 357
|2}CF B 337
[w]BF F° 317
GR CODES

(DEC SUPPLEMENTAL GRAPHICS)

DEC Multinational Character Set (Right Half)

MA-0894-83

SETUP ESCAPE SEQUENCES

The 7-bit compatible left half of the DEC multinational character set is the ASCI|
graphics set; the CO codes are the ASCII control characters and the GL codes

are the ASCII graphics set.

The 8-bit compatible right half of the DEC multinational character set includes
the C1 8-bit control characters in columns 8 and 9. The GR codes are the DEC
supplemental graphics character set. The DEC supplemental graphics character set has alphabetic characters with accents and diacritical marks that appear
in the major Western European alphabets. It also has other symbols not includ-

ed in the ASCII graphics character set.

DECtalk removes the accent from characters in the supplemental graphics
character set, which are accented versions of characters in the ASCII graphics
set. (Naive is the same as naive.) Other supplemental graphic characters are

ignored.

WORKING WITH 7-BIT AND 8-BIT ENVIRONMENTS
To take advantage of DECtalk’s 8-bit character set, your program and communication environment must be 8-bit compatible.
R

Conventions for Codes Transmitted to the Terminal
DECtalk expects to receive character codes in a form consistent with 8-bit
coding. Your application can freely use the 8-bit codes as well as the 7-bit code
extensions if it has enabled 8-bit controls.

When your program sends GL or GR codes, DECtalk interprets these accord-

gy,

ing to the graphic character mapping currently being used. The factory default

mapping, which is set when you power up or reset DECtalk, is the DEC mul-

tinational character set.

B—

Mode Selection (DT_MODE)
This sequence acts like the SET MODE command in setup mode. DT_MODE

e—

controls how DECtalk handles particular characters in spoken text. The general DT_MODE escape sequence is as follows.

ESC

;

ESC

027

080

048

059

056

048

059

***

122

027

092

Use the following method to obtain the P3 value.

——

T—

SETUP ESCAPE SEQUENCES

1. Add up the values of the MODE flags in Table 2-4 that you want to use.
2. Convert the sum to ASCII digits. Use these digits in place of P3 in the
escape sequence.

For example, assume you want to set MODE_SQUARE and MODE_MINUS,
and clear MODE_ASKY.
MODE_SQUARE

MODE_MINUS

Desired P3 value

027

080

048

059

056

048

ESC

;

ESC

059

053

122

027

092

—

P
——,

TG,

VOICE COMMANDS,
PHONEMIC TEXT,
AND THE USER DICTIONARY

pe—

The DECtalk DTC01 Owner’s Manual describes how to modify the DECtalk

voice (using phonemic commands and the phonemic alphabet) from a terminal.

This chapter describes a special series of escape sequences that gives a host

computer slightly greater control over DECtalk. For example, escape
sequences can turn the DECtalk voice on or off and load the user dictionary.
SPEECH CONTROL
There are three ways to control DECtalk speech.
1.

Through English text (sentences in standard English format and spelling).
DECtalk speaks this text as written.

Through phonemic spelling (sentences or phrases written in phonemic

symbols). Phonemic spelling is closer to the actual pronunciation of the
M

text.

3. Through phonemic commands. Phonemic commands control features of
speech that are not obvious from the visible text, such as rate of speech,
sex of the speaker, and excitement level.

VOICE COMMANDS, PHONEMIC TEXT, AND THE USER DICTIONARY

SPEECH TIMEOUT

Usually, DECtalk does not begin speaking until the host computer sends a
clause terminator (period, comma, exclamation point, or question mark); however, there is a 5-second timeout limit. If the host does not send data within 5

ARy

seconds, DECtalk speaks the pending text in its input buffer, as if a comma had

been sent.
Programs with long interruptions (such as pauses to search a database) should

collect complete sentences before sending anything to DECtalk. Otherwise,
this timeout may cause unnatural breaks in sentences and jerky-sounding
speech.

ENGLISH TEXT

DECtalk speaks sentences written in standard English, if the text follows three
rules.

1. Sentences end with a period, exclamation point, or question mark.

TTT—

2. All commas, periods, exclamation points, and question marks are followed by a space (or an equivalent character from Table 1-1).

3. A period must be followed by enough text to distinguish between abbreviations and the end of a sentence.
The host computer can send

English text in paragraph format; that is,

sentences can be broken in the middle by carriage returns.

If a sentence is too long to store in DECtalk’s buffers, the sentence is spoken in
sections. DECtalk breaks up the sentence and speaks it as if clause boundaries were present; the effect is similar to a person trying to speak a long
sentence and running out of breath. Keep sentences down to a reasonable
length to avoid this effect.

See the DECtalk DTCO1 Owner’s Manual for more information on speech
phrasing and emphasis. The ““Data Synchronization” section in this chapter
also describes how to coordinate speech and interaction commands to prevent
loss of information.

VOICE COMMANDS, PHONEMIC TEXT, AND THE USER DICTIONARY

SPEAK PHONEMIC TEXT (DT_PHOTEXT)
When MODE SQUARE is on, you can embed phonemic text in normal text with

square brackets. When sending data from the host computer, you can use the
DT_PHOTEXT escape sequence as well as the square brackets; MODE

SQUARE does not have to be on. The DT_PHOTEXT escape sequence is as
follows.

ESC

text

027

080

048

059

048

122

........... 027

ESC

092

ESC P 0; 0 zis the same as a left bracket ([), and ESC \ is the same as a right
bracket (]). DECtalk uses phonetic speech for all text between the command

terminator z and sequence terminator ESC \.
Appendix C lists the phonemic alphabet used by DECtalk. The DECtalk DTCO1
Owner’s Manual describes the alphabet in detail.
Within the phonemic text string, the host computer can transmit comments (for

program maintenance) enclosed in /* and */ sequences. (An ESC \ can also
terminate any comment.)

For example, in the following sequence the word Hello is a comment.

ESC P 0; 0 z hx’ehlow /* Hello */ ESC \
DECtalk processes a phonemic text escape sequence as though the introducer

and terminator were spaces. This means phonemic text cannot replace part of
a word.

In addition to transmitting the proper pronunciation, the phonemic text escape
sequence can send control phonemes. This example changes the speech rate
to 250 words per minute.
ESC P 0; 0z :ra250 /* Rate = 250 wpm */ ESC \

NOTE:

You cannotuse STX (CTRL-B) and ETX (CTRL-C) to delimit phonemic

text. Use the DT_PHOTEXT escape sequence instead.

VOICE COMMANDS, PHONEMIC TEXT, AND THE USER DICTIONARY

STOP SPEAKING (DT_STOP)
This escape sequence immediately stops speech, even if DECtalk is in the

middle of a sentence. DT_STOP is useful for stopping speech to perform other

actions. For example, the user may press a key to get more instructions,
warnings, or shortened versions of explanations (such as lengthy HELP
information).

The DT_STOP escape sequence is as follows.

ESC

;

ESC

027

080

048

059

049

048

122

027

092

Speech stops immediately and all internal buffers are reinitialized.
P

DATA SYNCHRONIZATION (DT_SYNC)
The application program can send data to DECtalk faster than DECtalk can

speak it. If the user must carry on a dialogue with the application program
(through the telephone keypad), the application program should know whether

or not DECtalk has finished speaking the text sent to it. DT_SYNC provides

this coordination between the application program and DECtalk speech.

cqpr—————y

When the host sends DT_SYNC, DECtalk finishes speaking any pending text

before processing the next command from the host. This ensures that the user

hears a message before any other action starts, such as hanging up the phone

or starting the phone timeout clock. Note that DT_SYNC acts as a clause
boundary, the same as a comma, period, exclamation point, or question mark.

DECtalk considers a section of text to be spoken as soon as the parameters
.

for that section are successfully sent to its signal processing section. Audio

output runs approximately 6 milliseconds behind the transmission of the
parameters. Applications that switch the audio output of a single DECtalk to a

number of sites may need to take this delay into account.

The DT_SYNC escape sequence is as follows.

ESC

;

ESC

027

080

048

059

049

122

027

092

B
——

DT_SYNC does not reply to the host when processing is complete. However,
you

can

this

following

DT_INDEX_QUERY command.

the

DT_SYNC

command

with

VOICE COMMANDS, PHONEMIC TEXT, AND THE USER DICTIONARY

ENABLE OR DISABLE SPEAKING (DT_SPEAK)
The DT_STOP sequence stops speech in progress. The DT_SPEAK sequence
turns speech processing off or on, so received text is either spoken or discarded. DT_SPEAK is useful if the host computer can recognize such things as
electronic mail letterheads and discard them as unnecessary. The host can act
as a filter, removing extraneous speech.
The DT_SPEAK escape sequence is as follows.

ESC

;

ESC

027

080

048

059

049

050

059

122

027

092

If P3 is 0, DECtalk stops speaking text; that is, it stops passing characters

received from the host to the text-to-speech processing section. If P3 is not 0,
DECtalk resumes speaking.

DECtalk also resumes speaking if the host sends DT_SYNC, DT_STOP, RIS,
DECSTR, or DT_PHONE:ph_answer.
INDEXING

Text sent to DECtalk can contain index marks. DECtalk remembers these
marks when they are spoken. The host application can listen to the spoken text
(by reading the value of the last index) to determine how much transmitted text
was actually spoken.

Index markers affect the way numbers and abbreviations are spoken. For

example, DECtalk says $ 12.45 as ‘‘twelve dollars and forty-five cents.” (The
space after the $ is optional.) If an index marker separates the $ and 1, then
DECtalk says ‘“‘dollar twelve point four five.”
The following paragraphs describe how to mark text and return their values to
the application program.

VOICE COMMANDS, PHONEMIC TEXT, AND THE USER DICTIONARY

Index Text (DT_INDEX)
This sequence inserts an index marker (flag) in the text stream sent to DECtalk.
The DT_INDEX escape sequence is as follows.

ESC

;

ESC

027

080

048

059

050

048

059

122

027

092

The P3 parameter may range from 0 to 32767, sent as the ASCII characters for

ORI,

the number. Numbers outside the range are brought into range by masking off
the overflow bits.
For example, the host computer sends the following data stream to DECtalk

and marks the second word with the index 15.

Hello ESCP0;20;15zESC\

there.
Ry,

After speaking the text before DT_INDEX, DECtalk remembers the value 15.
The host may use DT_INDEX_QUERY (described later in this chapter) to get
this stored value.

Index Reply (DT_INDEX_REPLY)
DT_INDEX simply marks a position in the text. DT_INDEX_REPLY marks a

position, but also has DECtalk inform the host when the index is spoken.
R

The DT_INDEX_REPLY escape sequence is as follows.
ESC

;

ESC

027

080

048

059

050

049

059

122

027

092

—

The P3 parameter is in the range 0 to 32767, using ASCII characters for the
selected number.

When DECtalk speaks the DT_INDEX_REPLY sequence, it sends a reply

—.

(containing the P3 parameter of the index) to the host. The escape sequence

reply format is as follows.
PG,

ESC

;

ESC

027

080

048

059

051

049

059

122

027

092
.

P3 has the original value specified in DT_INDEX_REPLY.

VOICE COMMANDS, PHONEMIC TEXT, AND THE USER DICTIONARY

Index Query (DT_INDEX_QUERY)
DT_INDEX_QUERY requests DECtalk to reply to the host with the last index
marker spoken (that is, the last portion of spoken text that had an index
marker). The DT_INDEX_QUERY escape sequence is as follows.

P
ESC
027 080

0
048

;
059

2
050

z
122

ESC \
027 092

DECtalk immediately returns a DECtalk reply escape sequence to the host in
the following format.

ESC
P
027 080

0
048

;
059

3
051

2
050

:
059

***

z
122

ESC
\
027 092

P3 contains the last index spoken. The P3 value is ASCIlI 0 under any of the
following conditions.
e The last index passed was ASCII 0.
e No index has been passed yet.

e No index has been marked in the text; that is, the host has not sent a

DT_INDEX or DT_INDEX_REPLY sequence.

Figure 3-1 shows how DT_SYNC and DT_INDEX_QUERY can coordinate
host-DECtalk communications.

VOICE COMMANDS, PHONEMIC TEXT, AND THE USER DICTIONARY

DECtalk

HOST SENDS TEXT AND DECtalk BEGINS SPEAKING.
... AM DECtalk. | AM

A SPECIAL...

DECtalk

HOST SENDS DT__SYNC ESCAPE SEQUENCE.

AN,

DECtalk WILL NOT PROCESS ANY FURTHER COMMANDS
UNTIL IT FINISHES SPEAKING THE CURRENT TEXT.
¢

...COMPUTER DEVICE
THAT IMITATES HUMAN..,

[

DECtalk

HOST

HOST SENDS DT__INDEX__QUERY ESCAPE SEQUENCE.
DECtalk STORES THE SEQUENCE BUT DOES NOT PROCESS IT.

DECtalk FINISHES SPEAKING.

DECtalk

DT__INDEX__QUERY IS PROCESSED AND
DT_QUERY__REPLY IS SENT TO HOST.

HOST PROGRAM NOW KNOWS DECtalk HAS FINISHED SPEAKING.

MA.7595-83
e

Figure 3-1

—

Using DT_SYNC and DT_INDEX_QUERY to Coordinate

Communications

—

VOICE COMMANDS, PHONEMIC TEXT, AND THE USER DICTIONARY

LOAD DICTIONARY (DT_DICT)

The user dictionary is used for processing abbreviations, and for providing
phonemic equivalents of unusual words. The DT_DICT escape sequence is as
follows.

O
ESC P
027 080 048

z name substitution ESC \
0
4
:
059 052 048 122 ........ ceeeeriiirnnnnneens 027 092

Whenever the word represented by ‘‘name’ appears in the input text, the
phonemic pronunciation given by ‘‘substitution”TM is used.

Any uppercase characters in the name only match uppercase characters in the
input text. Lowercase characters in the name match both uppercase and
lowercase characters in the input text. DECtalk always searches dictionary
entries in the order entered.

If a name ends with a period (.), a period must follow the word in running input
text. This period is included as part of the word, and is not recognized as a
sentence terminator.

Here are some examples of dictionary entries.
\
mihz ESC
ESCPO0:40;zms
\
ESC
ESCPO0:40;zms. mihz
ESCPO0;40;zDEC dehk ESC \
ESCPO0;40; zdec diysehmber ESC \

iy ESC \
ESC P 0: 40 ;z Goethe g'owth

ESCPO0:40;zGOSLOW :ra 120 ESC \

DECtalk does not recognize an error in phonemic spelling until the word is
used. You can use comments in the substitution, but they are not recommended. Note the use of capitalization in the previous examples to distinguish
between abbreviations with the same spelling.

If you do not enter a substitution, DECtalk removes the word from the user text
dictionary. You cannot remove words from the built-in dictionary.

VOICE COMMANDS, PHONEMIC TEXT, AND THE USER DICTIONARY

After loading the word and its definition, DECtalk replies with a dictionary
status report.

ESC

;

ESC

027

080

048

059

053

048

059

***

122

027

092

P3 may have one of the following values.

Word entered correctly.

L
—

OSSO,

RIS

048
1

No room in dictionary.

04
2

Entry too long (256 characters maximum).

050
gy

P—

BRI i,

TELEPHONE COMMUNICATIONS

You can connect DECtalk to the public telephone system to provide a dial-up
link between remote users on telephones and a computer application program.
DECtalk sends and receives information as a link between a remote user and
the host computer.

DECtalk communicates with the phone through the voice circuits, passing on
spoken data to the listener. DECtalk passes information back to the host both
as ordinary ASCII characters, and as escape sequences. The user can communicate with the host (through DECtalk) by using the Touch-Tone keypad, if
available.

The DT_PHONE escape sequence is the controlling sequence for all telephone
operations.

TELEPHONE COMMUNICATIONS

TELEPHONE MANAGEMENT (DT_PHONE)
This escape sequence takes one or more parameters and
controls the
attached telephone and Touch-Tone keypad interface. The DT_PHON
E

escape sequence is as follows.

ESC
P

027

0
;
6
0
;
Pn
080 048 059 054 048 059 ***

;

059 ***

122

text

—

ESC
\

... ....027

092

The Pn parameters act as a list of telephone management commands
and
execute in sequence. Table 4-1 lists the valid Pn parameters.
A single DT_PHONE sequence can perform several commands. Some
commands can take additional parameters.

All DT_PHONE commands return a status report to the host in the following
escape sequence. Table 4-2 lists the valid P3 values.

ESC

;

027

ESC

080

048

059

055

048

059

***

122

027

(092

All telephone management commands return a reply sequence back to
the
host upon command execution. PH_STATUS is only needed to check
the

telephone status when a DT_PHONE command is not pending. Note
that
PH_ANSWER generates an additional status report when the
phone is

answered.

Telephone keypad characters are sent as text, not escape sequences.

Note that the R3_PH_TIMEOUT reply sequence is sent when
a timeout

occurs; that is, the reply sequence may arrive as unrequested input,
and the
application program must be ready to receive it.

OB,

B
—

P—

—

TELEPHONE COMMUNICATIONS

APy

PH_ANSWER

DECtalk is set up to answer incoming phone calls. The parameter that follows
the PH_ANSWER parameters indicates the number of rings to wait before
answering the telephone. A parameter of 0 or 1 means answer the telephone

—

after the first ring; 2 means answer after 2 rings, and so on.

If the telephone is off-hook when the host sends a PH_ANSWER parameter,
DECtalk hangs up the telephone (disconnects any active call) before executing

the PH_ANSWER command.

DECtalk sends two status replies to a PH_ANSWER request. The first status
reply informs the host that the DT_PHONE command was correctly received.

The second reply informs the host that the telephone has actually been
answered.

DECtalk stops waiting for incoming calls whenever the host
PH_HANGUP, PH_TONE_DIAL, PH_PULSE_DIAL, RIS, or DECSTR.

sends

PH_HANGUP

|
This command hangs up the telephone. The status reply is delayed until the

telephone is back on-hook (disconnected). The host should wait for the
R3_PH_ONHOOK reply before sending other commands to DECtalk.

PH_KEYPAD
This command enables the telephone keypad. The request is ignored if the
phone is inactive (on-hook); however, DECtalk returns an R3_PH_ONHOOK

status reply.

B—

PH_NOKEYPAD

This command disables the telephone keypad, but maintains the phone connection. This request is ignored if the phone is inactive (on-hook); however,
DECtalk returns an R3_PH_ONHOOK status reply.

PH_TIMEOUT

P ——

This command starts (or restarts) an internal DECtalk timer. If the user does
not

press

telephone

keypad

button

within

R3_PH_TIMEOUT status is returned (Table 4-2).

the

timeout

interval,

The application program should set PH_KEYPAD on before sending a
PH_TIMEOUT command; otherwise, the user cannot respond to DECtalk
requests for input.

i Ay,

TELEPHONE COMMUNICATIONS

The parameter following PH_TIMEOUT is the number of seconds to wait for a
response from the caller. A parameter of 0 cancels any active timeouts. After a
timeout, the timer is stopped. The application program must send a new
PH_TIMEOUT command to restart the timer.

Timeouts are the only way to detect that the caller has hung up the telephone.

The public telephone system in your country may have another timeout requirement, independent of DECtalk. If this is true, a phone call may be automatically
terminated (hung up) if a response is not given in a certain length of time. Your
application program should accept unsolicited R3_PH_ONHOOK replies.
PH_TONE_DIAL and PH_PULSE_DIAL

DECtalk can dial an outgoing call by using these two commands. If DECtalk is
connected to a Touch-Tone public telephone network, then use the
PH_TONE_DIAL parameter; otherwise, use PH_PULSE_DIAL.
PH_PULSE_DIAL works like an old rotary phone dial.

If the telephone is on-hook when the host sends a dialing command, DECtalk

picks up the telephone and inserts a 2-second delay.

The text between the command terminator z and the ESC \ sequence is the

number to dial. For the Touch-Tone dialing system, the characters
0123456789*#ABCD!” are recognized. For the pulse dialing system, the characters 0123456789!" are recognized.

The ! character inserts a 1-second delay into the dialing stream. DECtalk
pauses during the dialing sequence every time it finds a ! character.

On some telephone systems, a user can press the switch hook to transfer calls
or otherwise interrupt a phone call. This signal is called a switch-hook flash.
The TM character inserts a 250-millisecond switch-hook flash signal into the
dialing stream. You can use successive ® characters to generate longer
flashes.

With Touch-Tone dialing, the characters ABCD generate the extra four tones of
the military handset. A is the character to the right of the 3, B is the character
below it, and so on.

Figure 4-1 shows a complete phone call session, including a timeout sequence

initiated because a user disconnected.

TELEPHONE COMMUNICATIONS

T
—

DECtalk

X ESC PO

;

0z ESC\ 7

HOST ENABLES COMMUNICATION WITH DT__PHONE/PH__ANSWER SEQUENCE.
DECtalk SENDS R3_PH__ONHOOK REPLY.

[

DECtalk
,
30 ; 20z ESC\}))

POy,

CALLER DIALS IN.

DECtalk SENDS R3__PH__OFFHOOK SEQUENCE.

HOST ENABLES 20 SECOND TIMOUT AND BEGINS COMMUNICATION CONTROL.

Ending Call

CASE 1.

USER HANGS UP. AFTER NO SIGNAL IS RECEIVED FOR 20 SECONDS,

DECtalk SENDS R3_PH__TIMEOUT TO HOST.
N,

DECtalk

ESC

CASE 2.

ROy

ESC\Z/

HOST TERMINATES SESSION AND SENDS PH__HANGUP.

DECtalk HANGS UP PHONE AND REPLIES WITH R3_PH__ONHOOK.
MA-7597-83

Figure 4-1

Telephone Communications

—

MAINTENANCE

AND DEBUGGING COMMANDS

DECtalk has a set of commands that set DECtalk operating features, test
DECtalk, and help debug application programs. Most of these commands have
an inquiry-response format. DECtalk returns an answer to the host computer
after the action is complete (or in response to a pure inquiry).
DEVICE ATTRIBUTE REQUEST

DECtalk responds to device identity requests from the host computer. For
compatibility with an older escape sequence, DECtalk recognizes two different
request sequences, described in the following paragraphs.
Device Attribute Request (DA Primary)

The preferred device attribute request escape sequence is as follows.
ESC

[

027

091

048

099

DECtalk identifies itself by sending the following sequence.
ESC
027

[
091

?
063

1
049

9
057

C
099

DECtalk does not respond to secondary device attribute requests, since its

product identification code is less than 50.

MAINTENANCE AND DEBUGGING COMMANDS

Identify Terminal (DECID)
DECtalk responds to the old identify terminal sequence (DECID) exactly as it
responds to the DA Primary request.

Oy,

The old identify sequence is as follows.

ESC

027

090
[

DECtalk identifies itself by sending the following sequence.
ESC

[

027

091

063

049

057

099

This is the same sequence as the DA Primary answer.

DEVICE TEST AND STATUS

A special set of escape sequences run DECtalk hardware self-tests. Another

set of escape sequences forces DECtalk to return status reports. The following
- paragraphs describe these sequences.

DECtalk Power-Up Status
You can reset DECtalk to its power-up state. The method you use to reset
DECtalk may affect the operating features (such as baud rate). You can reset

DECtalk with any of the following methods. This chapter describes methods 2

through 4.
1.

Power-up (PUP) is the state that DECtalk is in when first turned on.

——

2. Return to initial state (RIS) is a hard reset you can set with an escape
sequence.

PSS

3. Soft reset (DECSTR) partially restores DECtalk to its power-up state.
.

Nonvolatile memory reset (DECNVR) lets you reset the operating features
in permanent memory. At power-up, DECtalk restores the feature settings

that you reset in this memory.
Table 5-1 lists the DECtalk operating features and their factory default settings;
the reset methods in column three restore the feature to its power-up setting.

MAINTENANCE AND DEBUGGING COMMANDS

The power-up setting is the factory default, unless you changed the setting and

stored it with a DECNVR sequence. See the section on DECNVR in this
chapter.

Table 5-2 lists some other DECtalk actions performed by certain reset
methods.

MAINTENANCE AND DEBUGGING COMMANDS

Device Self-Test (DECTST)
This sequence initiates local self-tests. The escape sequence is as follows.

ESC

[

;

027

091

053

059

121
SN

The Pn parameter specifies the test to perform (Table 5-3).

The TEST_POWER parameter (Pn = 1) causes DECtalk to rerun its power-up
initialization and test sequences. ALL DECtalk operating features return to the
power-up state; the telephone is hung up, the user dictionary is deleted, and all

features are reset to their power-up values.

The loopback tests require the appropriate loopback connectors.
T S

The built-in message provides a quick check of the DECtalk system. The
message includes the version number of the DECtalk firmware.

MAINTENANCE AND DEBUGGING COMMANDS

Device Status Request (DSR) (Brief Report)
The brief DSR escape sequence is as follows.
ESC

[

027

091

053

110

If no malfunctions are detected, DECtalk replies with the following sequence.
ESC

[

027

091

048

110

If a malfunction is detected, DECtalk replies with the following sequence.
ESC

[

027

091

051

110

Applications can use this brief DSR format in most cases, because a brief

request does not reset any of DECtalk’'s internal error flags. The following
extended DSR format is useful when a malfunction is detected.
Device Status Request (DSR) (Extended Report)
The extended DSR escape sequence lets an application program determine
when DECtalk was first powered on. The application sends the extended DSR

escape sequence as follows.
ESC

[

027

091

110

If no malfunctions are detected, DECtalk replies with one of two sequences. If

this is the first extended DSR since DECtalk was powered on, DECtalk replies
with the following sequence.

ESC

[

027

091

048 110

ESC

[

027

091

063

050

049

110

For later requests, DECtalk replies with the following sequence.

ESC

[

ESC

[

027

091

048 110

027

091

063

050

049

110

MAINTENANCE AND DEBUGGING COMMANDS

If a malfunction is detected, DECtalk sends the following sequence.

ESC[

027

091 051

ESC
[

110 027

091 063 ***

;

059 ...

***

110

Each Pn parameter specifies an error as follows. The extended status request
sequence resets the error flags.

050

051

050

052

050

053

050

054

Communication failure.

Input buffer overflow.

R
[

Last NVR operation failed.

Error in phonemic transcription.

Error in DECtalk private control sequence.
s

050

055

Last DECTST failed.

Reset to Initial State (RIS)
Table 5-1 shows how the reset to initial state affects DECtalk. The RIS escape

sequence is as follows.

ESC

027

099

This sequence resets DECtalk to its power-up state, without changing the

YT,

speeds or data formats used on the host and local communication lines. All

pending, unspoken text is lost. All user-defined dictionary entries are deleted.

The telephone is returned to the on-hook state. Some operating features are
restored from nonvolatile 'memory (NVR).
g

MAINTENANCE AND DEBUGGING COMMANDS

The RIS sequence always turns host speech on, even if host speech is turned
off by the setup commands.

This NVR recall is almost identical to a DECNVR recall from user memory. (See
“NVR Parameters’’ in this chapter.) RIS does not change the line characteristics, and RIS updates the ‘‘status of the last NVR operation” flag reported by
device status reply sequences.

Digital recommends always using the DT_PHONE:ph_hangup sequence to
hang up the telephone. If DECtalk receives an RIS sequence when the telephone is off-hook, and reads the telephone status during the hangup, DECtalk
may report an off-hook status (instead of the expected on-hook status).
Soft Terminal Reset (DECSTR)

Table 5-2 shows how the soft terminal reset affects DECtalk. The DECSTR
escape sequence is as follows.
ESC

[

027

091

033

112

This sequence resets DECtalk to its power-up state, without changing the
speeds or data formats used on the host and local communication lines, or
resetting user convenience features on the local terminal. Pending, unspoken
text is not lost. The telephone returns to the on-hook state.

Digital recommends always using the DT_PHONE:ph_hangup sequence to
hang up the telephone. If DECtalk receives a DECSTR sequence when the
telephone is off-hook, and reads the telephone status during the hangup,
DECtalk may report an off-hook status (instead of the expected on-hook
status).

The DECSTR sequence always turns host speech on, even if host speech is
turned off by the setup commands.

Gy,

MAINTENANCE AND DEBUGGING COMMANDS

P
.

NVR Feature Settings (DECNVR)
You can store operating feature settings permanently in nonvolatile memory
(NVR). DECtalk restores these settings at the next power-up. To save or
restore the current settings in NVR,

use the following DECNVR escape

sequence.

ESC

[

;

027

091

059

***

033

114

If Pnis 0, this sequence restores all feature settings from NVR. This action may
change the speeds or data format of the serial lines, so communication with the
host or local terminal may be lost. The user dictionary is not deleted. The

telephone is not hung up.
If Pn is 1, this sequence stores all current feature settings in NVR. DECtalk
stops processing host line commands until the feature settings are safely

stored.

APIBNG

The Pm parameter specifies which NVR memory to use. Memory 0 is a
read/write memory you can use to store feature settings. DECtalk normally

uses memory 0 at power-up. Memory 1 is a read-only memory, and always
contains the factory-default DECtalk feature settings. DECtalk uses memory 1
at power-up if memory 0 cannot be used. Diagnostics may use memory 1 to

force DECtalk back to its factory settings.
i TS

DECtalk remembers the success or failure status of the last NVR operation
command. A device status request (DSR) sequence can check this status.
E

—

TRACING AND DEBUGGING COMMANDS
You can set DECtalk to log its actions and reactions to various commands on
the local terminal. These commands are useful for testing and debugging

during application program development.

Local Log Control (DT_LOG)

This sequence controls the logging of trace and debugging information on the
local terminal. DT_LOG works like the SET LOG command in setup mode. (See

the DECtalk DTCO1 Owner’s Manual.) The DT_LOG escape sequence is as
follows.

ESC

027

080 048

;

059

056

;

049 059

ESC

122

027

092

—

pre—

MAINTENANCE AND DEBUGGING COMMANDS

Use the following method to obtain the P3 value.
1. Add up the values of the DT_LOG parameters in Table 5-4 that you want
to use.

2. Convert the sum to ASCII digits. Use these digits in place of P3 in the
escape sequence.

MAINTENANCE AND DEBUGGING COMMANDS

—

For example, assume you want to set LOG_TEXT and LOG_RAWHOST.

LOG_TEXT

= 1

LOG_RAWHOST

= 4

Desired P3 value

ESC

;

027

080

048

059

056

049

;

059 053 122

ESC

027

092

Table 5-4 lists the P3 parameters. Figure 5-1 shows the data paths for logging
and debugging.

P—

1
FPEECH

{ LOG__ERROR

ROCESSOR| ) LOG—TEXT

LOG__PHONEME

TERM__SPEAK

LOG__OUTHOST

| -

o~O

LOG_RAWHOST

LOG__TEXT

TERMINAL

LOG__TRACE

‘olo}

LOG__PHONEME

LOG__INHOST

gtllo®
Yo
-~

—O—C——= SWITCH ON
O— = SWITCH OFF
A,

ALL SWITCHES SHOWN ARE OFF.
MA-7598-83

Figure 5-1

Data Paths for Logging and Debugging

MAINTENANCE AND DEBUGGING COMMANDS

LOG_TEXT

This command logs all spoken text. The text source does not matter; text is
logged from both the host and the terminal.
LOG_PHONEME

This command logs all spoken text in its phonemic transcription.
LOG_PHONEME is useful for testing the phonemic form of words and
phrases.

LOG_RAWHOST

This command logs all control and text characters as received, except NUL
characters (which are always deleted) and XON/XOFF characters (which still
perform flow control functions).
LOG_INHOST

This command logs all characters received from the host. Control characters
also print.

LOG_OUTHOST

This command logs all characters sent to the host. Control characters also
print.

LOG_ERROR

This command logs all error messages. Usually DECtalk error messages are
returned as escape sequences. Setting the LOG_ERROR flag causes error
messages to be logged also.

LOG_ERROR ’is useful during the early stages of application program

development.

LOG_TRACE

This command displays all escape sequences symbolically rather than as
escape sequences. If you use LOG_TRACE in debugging, you do not have to
look up the meaning of escape sequences.

MAINTENANCE AND DEBUGGING COMMANDS

LOCAL TERMINAL COMMAND (DT_TERMINAL)

This escape sequence controls the destination of characters typed on the local

terminal when the terminal is not in setup mode. (The TERM_FILTER parame-

ter affects characters sent to the local terminal when the terminal is not in
setup mode.) Figure 5-2 shows the data paths in local terminal operations.

The format of the DT_TERMINAL escape sequence is as follows.

ESC

;

027

ESC

080

048

059

056

050

059

***

122

027

092

Use the following method to obtain the P3 value.

1. Add up the values of the DT_TERMINAL parameters in Table 5-5
that
want to use.

you
A

2. Convert the sum to ASCII digits. Use those digits in place of P3
in the
escape sequence.

[

—

SPEECH

PROCESSOR
f

—

TERM__sPeak|

0‘]
LOG__OUTHOST

[ TERM_EDITED

TERM_HARD

TERM_SETUP

O—~—-|

TERM_HOST

MODE___SQUARE

TERM_FILTER
I,

——O—0—
= SWITCH ON

—0" O—= SWITCH OFF

——

ALL SWITCHES SHOWN ARE OFF.
MA.-7599A.-83

Figure 5-2

Data Paths for Local Terminal Operations

—

e
—
2

MAINTENANCE AND DEBUGGING COMMANDS

For example, assume you want to set TERM_HOST and TERM_EDITED.
TERM_HOST
TERM_EDITED

=1
=4
AT

Desired P3 value

—
|
e

ESC P
027 080

0
048

:
059

8
056

2
050

;
059

5
053

z
122

ESC \
027 092

Table 5-5 lists the possible P3 values.

NOTE:

If LOG_RAW and TERM_HOST are in effect and the host sends a

device attribute request, both DECtalk and the terminal will respond. The application program sample in Chapter 6 turns off TERM_HOST for this reason.

MAINTENANCE AND DEBUGGING COMMANDS

TERM_FILTER is useful when you use DECtalk as a link between a general-

R—

purpose operating system and an applications terminal. TERM_FILTER modi-

fies the operation of LOG_RAWHOST to prevent sending DECtalk-specific

escape sequences to the local terminal.

When you set TERM_FILTER, the following escape sequences usually
processed by DECtalk are now only processed by the local terminal.

Device self-test (ESC[ 5 ; Ps y)
Brief device status request (ESC ] 5 n)
Extended device status request (ESC [ n)

Reset to initial state (ESC c)
Soft terminal reset (ESC [ ! p)
NVR parameters (ESC [ Pn; Pn ! r)
Device attributes inquiry (ESC [ 0 ¢)
Identify terminal (ESC 2)
The following escape sequences are acted on by both DECtalk and the local

terminal.

e Select active character set (several sequences)
o Select graphics repertory (ESC i B and ESC i <)

Select 7-bit C1 transmission (ESC SP F)
Select 8-bit C1 transmission (ESC SP G)

Truncate high-order bit in C1 (ESC SP 6)

e Accept high-order bit in C1 (ESC SP 7)
Because TERM_FILTER must parse and understand escape sequences, you
can only use TERM_FILTER when the local terminal supports ANSI escape
sequences. Digital’s VT100 and VT200 series terminals and the terminals com-

munications programs available for Digital's personal computers support ANSI

escape sequences.

KEYPAD MASK COMMAND (DT_MASK)

This command controls how DECtalk sends escape sequences and keypad
characters to the host. DT_MASK simplifies application development when
DECtalk is connected to a host via a packet-switched network or a network
using the SNA (systems network architecture) protocol. These networks
have a

significant overhead associated with each message, so sending a line of text

(several characters) is more economical than sending a single character.

T —

MAINTENANCE AND DEBUGGING COMMANDS

DT_MASK is also useful when DECtalk is connected to an operating system
that prefers to communicate line-by-line, rather than character-by-character.
For example, when DT_MASK is on, you can use BASIC's INPUT LINE command to read text from DECtalk.

The command takes one parameter, which is interpreted as a 16-bit value. If a
bit is set, DECtalk sends a carriage return after sending the associated keypad

character. If any bit is set, DECtalk sends a carriage return after its escape

sequence replies. (The carriage return follows the ESC \ string terminator.) The
DT_MASK escape sequence is as follows.

ESC

027

080

;

048 059 056 051 059 ***

ESC

122

027

092

The P3 parameter is bit-encoded. Specified values have associated characters

(Table 5-6). If you specify a value, DECtalk sends a carriage return after the
associated character (when a user presses that key).

MAINTENANCE AND DEBUGGING COMMANDS

OO,

For example, to have DECtalk treat the # and * characters as response terminators (but not the digits), a program would send the following sequence.

ESC

027

;

080 059 056 057

059 051 048 055 050 122

ESC

027

092

(3072 = 1024 + 2048)
If the person calling the application presses 123# followed by a keypad time-

[

out, DECtalk would send the following.
12 3 # <carriage return>

ESC
027

;

080059

055

048

059

L——

ESC

050

122

027

092

<carriage return>
SN,

This allows the application program to use standard line-oriented input rou-

tines, rather than character-oriented routines. If you specify a P3 parameter of

0 with DT_MASK, DECtalk will not send a carriage return after keypad characters or escape sequences.

NOTE:

DECtalk will a send carriage return after all sequences, including

responses to non-DECtalk-specific sequences such as device status request.

Only responses generated within DECtalk are affected. Characters and escape
sequences generated by a local terminal are sent without interpretation.
PPy

The DECtalk support library does not interpret carriage return characters. You
have to process carriage returns with an application program. (Usually, an

application will ignore them.)

MAINTENANCE AND DEBUGGING COMMANDS

DETERMINING FIRMWARE REVISION LEVEL
If your application environment has DECtalk units with different versions of
firmware (1.8 and 2.0) you may need to determine the revision level of a
particular unit. You can use the following steps to determine the firmware
revision level.

1. Use the extended DSR escape sequence in this chapter to clear all
DECtalk errors. (Remember to note the DECtalk reply.)
2. Use the following escape sequence to send a [+] phoneme.
ESC

027

;

z
+ ESC\
027 092
043
122
080 059

This is silent and new to revision level 2.0 only.

3. Send another extended DSR escape sequence. |f DECtalk is a firmware
revision level 1.8, it will report an error in the phonemic transcription. If
DECtalk is revision level 2.0, it will not report any errors.

ESC

027

[

ESC[

091 048 110 027 091 063 050 048 110

(firmware 2.0 report)

ESC
[ 3

027

ESC[

091 051 110 027 091 063 050 053 110

(firmware 1.8 report)
Phonemic Alphabet

Appendix A lists all phonemes you can use in the DECtalk phonemic alphabet.

—

SR,

O ——

-y

—

C PROGRAM EXAMPLE

This chapter provides the source listings of a sample DECtalk application
written in C programming language. The program uses DECtalk, a host
computer, and a telephone connection to the United States public telephone
network

You can copy and use this application program; however, the program is only a
model, and cannot cover all possible DECtalk applications. You will find many
algorithms and sections within the application that you can use in your own
program; however, you will probably have to modify large sections of this
program for your own needs. Also, there is no guarantee that this application
program will run in the same way on your computer or on your public telephone
system (especially if you do not live in the United States).

The source programs are available from the DECUS Library (Digital Equipment
Corporation User’s Society) as 11-SP-58 (for PDP-11s) or V-SP-20 (for
VAX/VMS). RSX and RSTS operating systems need a system services library
distributed with DECUS C (DECUS 11-SP-18). All operating systems require a
C compiler to compile the programs. The DECUS library also has versions of
the library written in BASIC-PLUS and COBOL.

To order the latest version of source programs from the DECUS Library, malil
your request to:

DECUS Order Processing
MR02-1/C11

One Iron Way

Marlboro, MA 01752

For general information before placing an order, call (617) 480-3422.
69

C PROGRAM EXAMPLE

PROGRAM LANGUAGE AND STRUCTURE
This application program is written in C, a language originally written for the

UNIX operating system. C is a highly structured language, similar to Pascal,
ALGOL, and COBOL in form and syntax. C is also reasonably transportable:
the application program shown here can run on RSTS/E, RSX, UNIX, or
VAX/VMS operating systems (if the correct compilers are on those systems).

The application is written in many small modules, which are called according to
a tree structure (Figure 6-1). There are many modules, because each module

has only one or two functions within the program. The small, tight structure of
each module means that their function is easy to read and grasp.

All variables, constants, and other special values are listed in one module:

DECTLK.H. You must include DECTLK.H with the compilation of all other
|
|

modules.

APPLICATION PROGRAM
]

DT_INKEY

|} DT__INIT

“DEMOQ”

]

DT_ANSWER

DT_HANGUP

DT_TALK

DT_OPEN

DT_CLOSE

l DT__PHONE l
LDTMMSGI
]

l DT__..__,HEADI

[E)T___Gesc]

DT__GET

l DTWDCS]
by

]

I DT__PESC ,

t—

I DT__SAVE I

I DT_,__,F'UT]
]

[DT__,,IOPUT l

l DT,.._IOGET]
MA-7600-83

Figure 6-1

Calling Tree of DECtalk Application Program

C PROGRAM EXAMPLE

HOW THE PROGRAM WORKS

The application program waits for a caller to dial the DECtalk phone number.
DECtalk then acts as a link between the host computer and the caller, passing
a canned message to the caller and informing the host when the caller presses
any keypad buttons. DECtalk releases the phone line (1) when the caller hangs
up, or (2) if no response is received after a certain length of time.
The program works as follows.
1.

When started, the program establishes the DECtalk- telephone-host operating environment. DECtalk is set to wait for an incoming call.
- When a phone call is received, DECtalk answers the call and informs the
host that a call is active.

The host then sends a message for DECtalk to speak to the caller. This
message informs the caller that the keypad can be used.
. At the end of the host message, the telephone keypad is enabled and the
caller can send responses back to the host.

. The host responds with a ‘“‘you pressed button ...” message when the
caller presses a keypad button. If the caller doesn’t press a button for 15
seconds, the host tells DECtalk to hang up the phone.

C PROGRAM EXAMPLE

VARIABLE NAMES AND DEFINITIONS

All global variables and constants are definedin the module DECTLK.H. The
function of an escape sequence or coded reply from DECtalk is not clear when

embedded within a program; therefore, all escape sequences and status codes
are given their mnemonic names in DECTLK.H. The program then refers to
these names rather than the escape codes themselves.
What follows is a list of the global variables, mnemonics, and codes used in the
application program.

Flags
Two flags are used throughout the application program. The flags control

certain critical actions, as follows.

dt_abort

This flag is normally FALSE. If dt_trap() is called, the
library will trap a CTRL-C (or INTERRUPT on UNIX).
If the user types CTRL-C, the flag is set to TRUE and

LB G

all library modules exit as quickly as possible.

dt_debug

This flag can be set nonzero by an application pro-

gram to enable debug printouts. Note that the library

must have been compiled with dt_debug defined in

order to compilein the necessary print calls.
Error Codes

The library may return the following error codes. The error codes are all less

than zero, so they cannot be defined as part of the ASCII character set.
DT_ERROR

DT_TIMEOUT

An operating system error occurred.

An input operation did not complete in the required
(operating system) time.

IO_ERROR

This is an error exit code for the exit() library routine.

The value selected depends on the particular operating system.
s,

C PROGRAM EXAMPLE

DECtalk-Specific Parameters

Certain codes apply only to DECtalk (and not other devices, such as terminals).

These codes are as follows.

CSI_DA_PRODUCT

The DECtalk product identification code.

DCS_F_DECTALK

The DECtalk specific device control sequence (DCS)
final character.

P1_DECTALK

All DTCO01-AA DCS sequences send this for their first
(P1) parameter.

R1_DECTALK

All DTCO01-AA DCS replies send this for the first (R1)
reply parameter.

DECtalk Commands

The DECtalk commands that do not require specific parameters are coded as
follows.

P2_PHOTEXT

Speak phonemic text.

P2_STOP

Stop speaking.

P2_SYNC

Synchronize.

P2_SPEAK

Enable/disable speaking.

P2_INDEX

Index text.

P2_IX_REPLY

Index with reply.

P2_IX_QUERY

Return last spoken index.

P2_DICT

Load user dictionary.

P2_PHONE

Telephone control

—

(See ‘‘Telephone Control Parameters.”)

C PROGRAM EXAMPLE

P2_MODE

Synthesis mode control.

P2_LOG

Local terminal log control.

P2_TERMINAL

Local terminal control.

Telephone Control Parameters

The telephone control command P2_PHONE takes an additional parameter to
specify the specific telephone action.

S—

|
s

P3_PH_STATUS

Send a status report.

P3_PH_ANSWER

Answer on P4 rings.

P3_PH_HANGUP

Hang up the phone.

P3_PH_KEYPAD

Enable keypad data entry.

P3_PH_NOKEYPAD

Disable keypad data entry.

P3_PH_TIMEOUT

Send a timeout report if no data entered in P4
seconds if P4 is greater than zero; disable time-

outs if P4 is zero.

P3_PH_TONE

Dial out using Touch-Tones.

P3_PH_PULSE

Dial out using pulses.

|
—

C PROGRAM EXAMPLE

DECtalk Replies

Several P2_ commands return messages to the host.

R2_IX_REPLY
R2_IX_QUERY
R2_DICT
R2_PHONE

Reply to P2_IX_REPLY. R3 contains the last index
processed.

Reply to P2_IX_QUERY. R3 contains the last index
processed.

Reply to P2_DICT. R3 contains the dictionary entry
status code.

Reply to P2_PHONE. R3 contains the telephone
status.

DECtalk returns the following R3 parameters after a P2_PHONE command.
R3_PH_ONHOOK

Telephone is hung up (inactive).

R3_PH_OFFHOOK

Telephone is answered (active).

R3_PH_TIMEOUT

No data was entered by the telephone user within the

R3_PH_TOOLONG

required number of seconds.

A telephone number to dial is too long.

DECtalk returns the following R3 parameters after a P2_DICT command.
R3_DI_LOADED

Dictionary entry was loaded.

R3_DI_NOROOM

The user dictionary is full.

R3_DI_TOOLONG

The dictionary entry is too long.

C PROGRAM EXAMPLE

Self-Test Parameters
The following parameters control the DECtalk self-test (DECTST).
TEST_POWER

Rerun power-up test.

TEST_HDATA

Run host data link loopback test.

TEST_HCONTROL

Run host line control test.

TEST_LDATA

Run local line data test.

TEST_SPEAK

Speak a canned message.

The following status codes are returned by the extended DSR

sequence.

DSR_OK

No errors detected.

DSR_COMFAIL

Communication failure.

DSR_INBUFOVER

Input buffer overflow.

DSR_DECNVRFAIL

Last restore from nonvolatile memory failed.

DSR_PHONEME

Incorrect phoneme entered.

DSR_PRIVATE

DECtalk DCS parameter error.

DSR_DECTSTFAIL

Last DECTST self-test failed.

—

C PROGRAM EXAMPLE

Logging Command Parameters

The following parameters configure the P2_LOG command.
LOG_TEXT

Log spoken text.

LOG_PHONEME

Log generated phonemes.

LOG_RAWHOST

Log all characters received from host without
change.

LOG_INHOST

Log all characters received from host in visible
format.

LOG_OUTHOST

Log all output to host in visible format.

LOG_ERROR

Log error messages.

LOG_TRACE

Log commands in mnemonic form.

The following parameters are for the P2_TERMINAL command.
TERM_HOST

Send text entered from the local terminal to the
host.

TERM_SPEAK

Speak text entered from the local terminal.

TERM_EDITED

Line-edit text entered from the local terminal.

TERM_HARD

Use hardcopy edit conventions.

TERM_SETUP

Speak setup dialog.

TERM_FILTER

Filter sequences sent to the local terminal.

The following parameters are for the P2_MODE command.
MODE_SQUARE

Accept [ ] bracket phonemic text.

MODE_ASKY

Use single-letter phonemic alphabet.

MODE_MINUS

Pronounce a hyphen (-) as “‘minus.”

C PROGRAM EXAMPLE

THE SEQUENCE DATA STRUCTURE

The C language uses a powerful form of information control called a data
structure. Data structures closely resemble Pascal records and can pass and

RS,

e
—

hold multiple pieces of information.

All information needed to generate and parse escape sequences is in the
SEQUENCE data structure. SEQUENCE is configured by the following size

constants.

SEQ_INTMAX

Maximum number of intermediate characters.

SEQ_PARMAX

Maximum number of parameters.

—

The SEQUENCE data structure contains the following components.
short state

Processing state or introducer character to send.

char final

Final character in sequence.

char private

Private introducer character (or X to indicate an
error).

short param(]

Private parameters (unsigned); param[0] con-

tains the number of parameters.

char inter|]

Intermediate characters; inter[0] contains the
number of intermediates.

All information needed by the application program is in the DECTALK data
structure which is created by dt_open() and freed by dt_close(). The DECtalk

data structure is configured by the following parameters.
PEND_SIZE

—

Maximum number of keypad characters that may
be typed ahead. Additional characters are
discarded.

IN_BUFLEN

Size of the operating system input buffer.

OUT_BUFLEN

Size of the operating system output buffer.

—

C PROGRAM EXAMPLE

The data buffer contains the following information.
DECTALK *link

Chains together all active units.

int unit

Operating system 1/O channel.

short timeout

TRUE if timeouts enabled.

short pend_fc

Bytes in pending buffer.

short pend_fp

Index to free byte in pending buffer.

short pend_ep

Index to next byte to return from pending buffer.

char *in_ptr

Input buffer pointer.

char *in_end

Input buffer end.

char *out_ptr

Output buffer free pointer.

SEQUENCE send

Last DCS sequence sent.

SEQUENCE reply

Last DECtalk reply received.

SEQUENCE seq

Look-ahead for string terminator processing.

char *device

Remember dt_open() device name for debug
printouts.

char pend[]

Type-ahead buffer.

char in_buff[]

Input buffer.

char out_buff[]

Output buffer.

struct sgtty stty_save

Terminal characteristics block (UNIX only).

FILE *fildes

File descriptor (RSX only).

struct iosb iosb

/O stétus block (RSX only).

struct gioparm parm

QIO parameter block (RSX only).

C PROGRAM EXAMPLE

SISO,

APPLICATION PROGRAMS
The rest of this chapter lists the modules used to build the complete application

program. All modules with the indicator comment

/*)LIBRARY
SR

should be compiled and loaded into an object library. The main program,
DEMO.C, is compiled and linked with the DECtalk library and the C standard

——

library.
The modules appear in the following order (Table 6-1).

—

AR,

C PROGRAM EXAMPLE

<oo

TR sO A

C PROGRAM EXAMPLE

——

L —

ARy

—

C PROGRAM EXAMPLE

DECTLK.H

DECTLK.H must be included in all modules that use the DECtalk applications
library. This file also defines common ASCII characters, DECtalk escape

sequence parameters, library globals, and the DECtalk buffer structure. You
can edit this file to enable debugging code defined by the DTDEBUG flag.

and

Globals

This file contains symbolic definitions of the structures
and characters used by DECtalk application programs,
including all DECtalk escape sequence parameters.

Note:

on RSX-11M,

your

program must

first

#include

«stdio.h>

Definitions

* Galect a UNIX "flavor'"

(bizarre code as DECUS C

lacks "defined()")

#ifdef

wunix

#ifndef

BSD_42

#ifndef

UNIX_V

fdefine

UNIX_V

fendif
fendif
fendif

#ifdef

DOCUMENTATION

title
index

dectlk.h

DECtalk
DECtalk

Library Header
library header

File
file

synupsis

#include

*"dectlk.h"

description

This file is included in the compilation of all
modules that use the DECtalk applications library.
It defines common ASCII characters, DECtalk
escape sequence parameters, library globals,
and the DECTALK buffer structure.
canfigurutian

You can edit dectlk.h to enable debugging
by defining the DT_DEBUG flag as follow.
#define

DT_DEBUG

This changes the primary input
so that they become capable of
transmitted

and

code

from

and output routines
logging all charactlers

the DECtalk

device.

—,
T

C PROGRAM EXAMPLE

globals
The

library

follows.

provides

two

global

flags

which

are

used
s,

dt.abort

This

set

non-zero

intercepted

CTRL-C

have

dt_trap()).

called

[/0

will

trap

(if

performed,

library

subroutines

quickly

you

When

will

set,

and

exit

possible.
s

di_.debug

This

may

set

applications

debug

program

printouts.

library
with

nonzero

must

DT_DEBUG

compile

Note

have

enable

that

been

defined

the

compiled
in

order

necessary

calls.
error

OGRS

codes

The

library

may

return

These

are

all

less

cannot

part

the

than
the

following

zero,

ASCII

and

error

character

set.

DT_ERROR

operating-system

DT.TIMEOUT

input

operation

complete

I0O_ERROR

codes.

consequently

the

error.

did

not

required

(operating-system)

time.

for

error

exit()

value
for

exit

code

library

the

routine.

selected

particular

The

appropriate

operating

system.

Routines

implemented
Certain
macros

macros

frequently
(if

particular

macro
C

routines

expansion

compiler).

dt_iskey(dt)

may
is

These

TRUE

stored

be
are

data
in

implemented

supported
as

the

—

the

follows.

currently

keypad

[

type-ahead

buffer.
dt_.isvalid(c)

TRUE

valid

Note:

dt _ptest(dt,r3)

the

character

keypad

evaluation

must

not

have

you

must

not

Phone

test,

PO,

character.

the

argument

side-effects.
write

TRUE

R2_PHONE,

1I.e.,

dt_isvalid(*p++).

the

A5,

current

R3.
A,

C PROGRAM EXAMPLE

dt_offhook(dt)

Phone
reply

test, TRUE if the current
is R2_PHONE, R3_PH_OFFHOOK.

dt _onhook(dt)

Phone
reply

test, TRUE if the current
is R2_PHONE, R3_PH_ONHOOK.

dt_istimeout(dt)

Phone
reply

test, TRUE if the current
is R2_PHONE, R3_PH_TIMEOUT.

dt_phone(dt,p3,p4)

dt_eol(dt)

Send

"end

output

general

line*

and

force

DECtalk.

definitions
The

ascii

phone message.

following

variables

are

defined.

EOQS

End of

FALSE

For

TRUE/FALSE

string
testing

TRUE

For

TRUE/FALSE

testing

characters

The

following

control

characters

are

defined.

NUL

STX

ETX

BEL

LS1

LSO

XON

XOFF

CAN

SUB

ESC

DEL

The

following

control

§s2

SS3

DCS

APC

RDEL

The

following

also

defined.

characters

OLDID

CSI

are

DECtalk-specific

defined.

0scC

parameters

CSI_DA_PRODUCT

The DECtalk product
identification code.

DCS_F_DECTALK

The

DECtalk

control

specific

sequence

are

device

(DCS)

final

character.

P1_DECTALK

All

DCTO01

transmit
(P1)

R1_.DECTALK

DCS
this

sequences
for

their

first

parameter.

All

DCTO1

this

for

DCS
the

parameter.

replies
first

transmit
reply

C PROGRAM EXAMPLE

The

and

parameters

select

the

specific

P2_PHOTEXT

Speak

phonemic

P2_STOP

Stop

speaking.

P2_SYNC

Synchronize.

P2_SPEAK

Enable/disable

P2_INDEX

Index

text.

P2_IX__REPLY

Index

with

P2_IX_QUERY

Return

P2_DICT

Load

P2_PHONE

Telephone

control.

P2_MODE

Synthesis

mode

P2_LOG

Local

terminal

log

P2_TERMINAL

Local

terminal

control.

P2_MASK

Keypad

The

telephone

parameter

control
specify

Return

Answer

control.

takes

Hangup

the

Enable

keypad

P3_PH_NOKEYPAD

Disable

P3_PH_TIMEOUT

Send
if

entry.

report
in

greater

than

timeouts

zero;

Dial

out

using

tones.

P3_PH_PULSE

Dial

out

using

pulses.

commands

R2_IX_REPLY

return

messages

the

last

zero.
[

the

P2_IX_REPLY.

contains

seconds

P3_PH_TONE

Several

—

entry.

data

entered

action.

report.

data

keypad

disable

additional

phone.

timeout

data

rings.

P3_PH_HANGUP

control.

telephone

status

P3_.PH_KEYPAD

index.

control.

specific

P3_PH_ANSWER

speech.

spoken

mask

P3_PH_STATUS

text.

dictionary.

command
the

command.

reply.

last

user

DECtalk

host.

index

processed.
ey,

R2_IX_QUERY

P2_IX_QUERY.

contains

the

last

index

processed.

R2_DICT

P2_DICT.

contains
status

R2_PHONE

the

following

P2_PHONE

entry

code.

P2_PHONE.

contains
The

dictionary

parameters

the
are

telephone
returned

status.

after

command.

R3_PH_ONHOOK

Telephone

R3_PH_OFFHOOK

Telephone

R3_PH_TIMEQOUT

R3_PH_TOOLONG

data

was

hung

user

number

seconds.

telephone

too

long.

(inactive).

answered
entered

telephone
of

within

number

(active).
the

the

dial

required

C PROGRAM EXAMPLE

The

following

parameters

are

returned

after

P2_DICT

command.

R3_DI_LOADED

Dictionary

R3_DI_NOROOM

The

user

R3_DI_TOOLONG

The

dictionary

are

used

The

self

following

test

codes

entry

was

dictionary

entry

control

full.

too

long.

host-requested

(DECTST).

TEST_POKWER

Rerun

TEST_HDATA

Host

data

link

TEST_HCONTROL

Host

line

control

TEST_LDATA

Local

line

TEST_.SPEAK

Speak

The

following

DSR

sequence.

status

power

codes

are

Communication

DSR_.INBUFOVER

Input

buffer

Last

restore

errors

Incorrect

DSR_PRIVATE

DECtalk

DSR_DECTSTFAIL

Last

flags

phoneme

entered.
error.

DECTST

self-test

failed.

the

Log

generated

LOG_RAWHOST

Log

all

Log

nonvolatile

parameter

LOG_PHONEME

LOG_OUTHOST

failure.
from

spoken

from

extended

overflow.

Log

the

detected.

LOG_TEXT

LOG_INHOST

DCS

configure

from

test.

message.

failed.

DSR_PHONEME

following

test.

returned

memory

loopback

data

DSR_COMFAIL

DSR_DECNVRFAIL

test.

canned

DSR_0OK

The

loaded.
is

all

visible

phonemes.

without

received
change.

characters

host

command.

text.

characters

host

all

P2_L0OG

received

"“visible"

output

host

format.
in

format.

LOG_ERROR

L‘Dg

error

LOG_.TRACE

Lag

commands

messages.
in

mnemonic

form.

C PROGRAM EXAMPLE

The

following

flags

TERM_HOST

are

for

Send

TERM_SPEAK
TERM_EDITED

the

text

P2_TERMINAL

entered

local

terminal

Speak

text

local

terminal.

command:

from

the

host.

entered

from

Line-edit

text

the

local

terminal.

entered

TERM_HARD

Use

hard-copy

TERM_SETUSPEAK

Speak

TERM_FILTER

Filter

escape

local

edit

OO,

the
from

conventions.
RS

The

following

flags

MODE _SQUARE

MODE_.ASKY

SETUP

the

are

for

[

bracket

]

Use

the

dialog.
sequences

sent

terminal.
P2_MODE

command.

phonemic

text.

single-letter

phonemic

alphabet.
S

MODE_MINUS
The

Pronounce

following

flags

are

for

SPLICE_SPEAK

DECtalk

SPLICE.LOG

Text

the

The

sent

Escape

sequence
All

data

dt_splice()

text

DECtalk

may

function.

set.

sent

the

LOG_RAWHOST).
send

(P2_TERM,

text

TERM_HOST).

buffer

information

escape

"minus."

(P2_L0OG,

terminal

DECtalk

speaks

terminal
SPLICE_TERM

‘-’

needed

sequences

data

structure.

size

constants.

SEQ_INTMAX

is
It

generate

contained
is

configured

Maximum

and

the
by

number

parse

SEQUENCE
the

following

intermediate

characters.

SEQ_PARMAX

Maximum

number

parameters.
————,

contains
short

the

state

following

components.

Processing
character

char

final

Final

char

private

Private
or

‘X’

state
to

character

introducer
to

introducer

send.

indicate

sequence.

character
an

error.

C PROGRAM EXAMPLE

paraml]

short

Private parameters (unsigned);
param[(0] contains the number of
parameters.

interl]

char

Intermediate

characters;

number

the

contains

inter{0]

intermediates.

DECTALK data buffer definition

All information needed by the DECtalk applications
library is contained in the DECTALK data structure

which is created by dt_open() and freed by dt_close().
It

configured by

the following parameters.

Maximum number

PEND_SIZE

of keypad
that may be typed-ahead.
characters are discarded.

characters
Additional
Size

IN_BUFLEN

the

operating

system

input

the

operating

system output

buffer.

OUT_BUFLEN

Size

buffer.

DECTALK
short

*1link

unit

short timeout

information.

the following

The data buffer contains

Current

[/0

system

Operating

timeout

active units.

all

together

Chains

channel.

value

dt_splice

and

flags.

short

flag

Speech

short

pend_fc

Bytes in pending buffer.

short

pend_fp

Index

free

byte

pending

byte

return

buffer.

short

pend_ep

Index

from

pending

buffer.

char

*in_ptr

Input

buffer

pointer.

char

*in_end

Input

buffer

end.

char

*out_ptr

Output

free

buffer

SEQUENCE

send

Last

DCS

sequence

SEQUENCE

Last

DECtalk

SEQUENCE

seq

Look-ahead

for

pointer.
sent.

received.

string

terminator

processing.

char

*device

Remember
for

debug

dt_open()

device

printouts.

name

C PROGRAM EXAMPLE

char

pend(]

Type-ahead

char

in_buffl]

Input

char

out_buffl]

Output

struct

termio

buffer.

buffer.
buffer.

stty_save

Terminal
block

characteristics

(UNIX

System

V).
WO

struct

sgtty stty_save

Terminal
block

FILE

*fildes

struct

iosb

QIOPARM

File
iosb

parm

int#pos_xk

The

flag

entry

descriptor

I/0

status

QI0

parameter

(RSX

only).
if

(RSX

only).

internal

Set

DECtalk

Set

LOG

RAWHOST

-FLAG_TERM

Set

TERM

HOST

Set

read

and

FLAG_LOG,

application

FLAG_EIGHTBIT

must
and

8-bit

form.

ensure

that

correctly

Note
the

and

speaking.

set.

is set.
write eight-bit

control

FLAG_TERM

states.

sequences.
should

not

changed

programs.

DECtalk

sends

and

(RSX).

driver

-FLAG_SPEAK

FLAG_SPEAK,

UNIX

block

XK:

library

data

BSD).

C(RSX).

-FLAG_LOG
-FLAG_EIGHTBIT

POS

4.2

(RSX).

block

TRUE

controls

characteristics

(UNIX

set

receives

that

the

operating

DECtalk

the

application

control

program

must

application
system

setup

must

passes

set

program

sequences
8-bit

HOST

their
DORI

data

FORMAT

NONE.

Notes

UNIX

System

forced

retain

the

aware

between

9600

the

Baud.

current

that

This

Baud

there

operating

DECtalk

are

may

rate.

terminal

Also,

numerious

line

changed
you

subtle

to
should

differences

systems.

Note

UNIX

and

System

are

trademarks

AT&T

Bell

Laboratories.

Aoy,

Yendif
/i

Define

characters.

DT_DEBUG

enable

debug

printouts

transmitted

C PROGRAM EXAMPLE

fdefine

DT_DEBUG

#define

FALSE
#define TRUE
#ifndef EOS
#define EOS

0
1

*\Q"’

#fendif
#ifdef

wunix

#ifdef

BSD_42

<sgtty.h>

#include
felse

—

UNIX_.V

#ifdef

<termio.h>

#include
Yendif

#endif
¥fendif

These error

codes may

m—

control

#define
#define
fdefine
#define
#define
fdefine

¥define
#*define
#define
#define
#define

the ASCII

range.

0x00
0x02
0x03
0x07
0x08
0x0B

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

NUL code
Start of text
End of text
Bell
Backspace
Vertical tab (’\0137)

*/
*/
*/
*/
*/
*y/

0x0E
O0xOF
0x11
0x13

/*
/*
/*
/*

LS1 (SO)
LSO (S1)
DC1
DC3

*y/
*/
*/
*/

(-2)

characters

|
NUL
STX
ETX
BEL
BS
VT

¥define LS1
fdefine LSO
#define XON
fdefine XOFF

A
6«

-1)

#define DT_ERROR
#define DT_TIMEOUT

not

CAN
SUB
NUL
ESC
DEL

0x18
0x1A
0x00
0x1B
O0x7F

/*
/*
/*
/*
/*

Cancel «<CTRL/X>
Substitute
Null code
Escape
Delete

*/
*/
*/

*/
*/

* C1 control characters

f—
?'
‘

#define SS2
*define SS3

0x8E
0x8F

/* Single shift 2
/* Single shift 3

gra—

#define CSI

0x9B

/* Control Sequence Introducer

#define DCS
#define OLDID

fdefine ST
#define
*define
*define
#define

0SC
PM
APC
RDEL

0x30
0x9A

0x9C

0x9D
0x9E
0x9F
O0xFF

/* Device control
/* ESC Z

sequence

/* String terminator
/*
/*
/*
/*

Operating System sequence
Privacy Message
Application Program Control
Delete in right side

*/
*/

*y/

*/
*/
*/
*/

C PROGRAM EXAMPLE

#define

CSI_DA_PRODUCT

Dectalk

product

code

Basic

strings.

definitions

P1_DECTALK.

This

products

fit

All

for

DECtalk

device

sequences

have

provides

into

the

easy

scheme

control
a

first

place

parameter

for

future

Oy,

DECtalk

things.

#define

DCS_F_DECTALK

‘'z’

DECtalk

final

fdefine

P1_DECTALK

DECtalk

param

¥fdefine

R1_DECTALK

DECtalk

param

selects

the

basic

command.

*/
1

The

second

parameter

*/
*define

P2_PHOTEXT

Speak

*define

P2.STOP

Stop

phonemic

text

fdefine

P2_SYNC

Synchronize

¥define

P2_SPEAK

Enable

#define

P2_INDEX

INDEX

speaking
or

disable

¥define

P2_IX_REPLY

INDEX_REPLY

#define

P2_1X_QUERY

INDEX_QUERY

#define

P2_DICT

Dictionary

#define

P2_PHONE

Phone

#define

P2_MODE

Synthesis

fdefine

P2_L0OG

LOG

#define

P2_TERMINAL

Local

#define

P2_MASK

Set

speaking

control

‘

mode

control

information
terminal

keypad

local

tty

control

mask

Additional

parameters

for

the

phone

command.
a

status

#*define

P3_PH_STATUS

Send

#define

P3_PH_ANSWER

Answer

#define

P3_PH_HANGUP

Hangup

#define

P3_PH_KEYPAD

Raw

#*define

P3_PH_NOKEYPAD

Disable

#define

P3_PH_TIMEOUT

Status

#define

P3_PH_TONE

Dial

out

#define

P3_PH_PULSE

Dial

out

(P4

report

has

ring

*/
number)

keypad

keypad
report

*/
on

timeout

l'l'

The

second
the

parameter

specifies

the

general

class

sequence.

#define

R2_IX_REPLY

Sent

after

INDEX_REPLY

#define

R2_IX_QUERY

Sent

after

INDEX_QUERY

#define

R2_DICT

Sent

after

DICT

#define

R2_PHONE

Telephone

status

report

A OO

C PROGRAM EXAMPLE

/‘l

* Additional reply information is passed in the third parameter.

#define R3_PH_ONHOOK
#define R3_PH_OFFHOOK
#define R3_PH_TIMEOUT
#define R3_PH_TOOLONG
#define R3_DI_LOADED
#define R3_.DI_NOROOM
#define R3_DI_TOOLONG

/* Hung up
/* Phone is lifted
/* No reply in N seconds
/* Telephone # text too long
/* Dictionary entry loaded ok
/* No room in dictionary
/* String too long

0
1
2
3
0
1
2

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

* Test specification codes for the request self test
(DECTST)

sequence.

#define TEST_POWER
#define TEST_HDATA
#define TEST_HCONTROL
#define TEST_LDATA
#define TEST_SPEAK

*/
/* Rerun power up tests
/* Host line data loopback test */
*/
/* Host line control test
*/
/* Local line data test
*/
/* Speak a canned message

1
2
3
4
S

7 *

* Error (and success) codes for the extended DSR sequence.

#define DSR_OK
#define DSR_COMMFAIL
#define DSR_INBUFOVER
#define DSR_DECNVRFAIL
#define DSR_PHONEME
#define DSR_PRIVATE
#define DSR_DECTSTFAIL

20
22
23
24
25
26
27

*/
/* All OK
*/
/* Communication failure
*/
/* Input buffer overflow
*/
/* Last DECNVR failed
*/
/* Error in phonemic text
/* Error in DECtalk private DCS */
*/
/* Last DECTST failed

* Local logging flags for the P2_L0G command.

f—
.

#define LOG_TEXT

0x0001

/* Log text that is spoken

#define LOG_INHOST
#define LOG_OUTHOST
#define LOG_ERROR
#define LOG_TRACE

0x0008
0x0010
0x0020
0x0040

/* Log host input
/* Log host output
/* Log errors
/* Log sequence trace info.

*/
*/
*/
*/

#define LOG_PHONEME
#define LOG_RAWHOST

0x0002
0x0004

/* Log generated phonemes
/* Log raw host input

*/
*/

I *

f—

gr—
-

* Local terminal flags for the P2_TERMINAL command.

#define TERM_HOST

0x0001

/* Send text to host

#define TERM_HARD
#define TERM_SETUSPEAK
#define TERM_FILTER

0x0008
0x0010
0x0020

*/
/* Local terminal is hardcopy
*
/* Spoken setup mode
/* Filter logged esc. sequences */

#define TERM_SPEAK
#define TERM_EDITED

0x0002
0x0004

/* Speak local terminal input
/* Edited

*/
*/

C PROGRAM EXAMPLE

SR
g,

Mode

flags

for

the

P2_MODE

command.

#define

MODE_SQUARE

0x0001

#define

[

MODE_ASKY

0x0002

#define

Use

MODE_MINUS

ASKY

0x0004

"-"

are

phonemic

brackets

alphabet

pronounced

"minus"

S *®

Flags

for

dt_splice()

and

((DECTALK

*J)dt)->flag

#define

SPLICE_SPEAK

0x0001

#define

SPLICE_LOG

0x0002

Log

0x0004

Local

Speak

text

ARGy

rawhost

set

#define

SPLICE_TERM

*define

_FLAG_SPEAK

0x0001

#define

Speaking,

_FLAG_LOG

0x0002

#define

Log

rawhost

_FLAG_TERM

0x0004

#define

Term

_FLAG_EIGHTBIT

host

0x0008

Read

eight-bit

host

set

dt_splice()

from

dit_splice()

from

dt_splice()

controls

/ *

—

These

sequence

macros

and

structure

definitions

are

parser.

used

the

escape

#define

SEQ_INTMAX

#define

Max.

SEQ_PARMAX

intermediates

Max.

parameters

di_gesc()

(get

sequence)

use

escape

this

sequence)

structure

typedef

struct

di_pesc()

all

escape

{
state;

char

Processing

final;

char

Final

private;

Private

unsigned

state

character

decus

or
in

intro
seq.

introducer

*/
*/
*/

param[SEQ_PARMAX+11];

felse
unsigned

(put

processing.

short

#ifdef

short

param[SEQ_PARMAX+11];

#endif

“,

char

}

and

for

Intermediate

inter[SEQ_INTMAX+11;

SEQUENCE;

count,

values

S *

The

needed

dt_open(),
by

DECTALK
to

structure

process

freed

essentially

all

used

DECtalk

dt_close()
routines.

maintain

device.
and

It
a

all

information

allocated

required

parameter

ARy

C PROGRAM EXAMPLE

@MWM

#ifdef

rsx

* The qio parameter block controls all RSX11-M I/0 requests.
*/

g'”}‘
”
|

typedef struct qioparm {
*buffer;
char
size;
int
*P3;
char

*table;
unused(2];

char
int

}

/*
/*
/*
/*

Q10 parameter block
Buffer location
Bytes to transfer
For ctrl/c ast

/* Terminator table
/* Not used here

*/
*/
*/
*/

*/
*/

QICPARM;

* The 1/0 status block receives the status of all 1/0 requests.

@M'@

typedef struct iosb {
status;
char

‘g

terminator;

char

count;

int

}

/* 1/0 status block
/* Operation status

*/
*/

/* Bytes read from device

/* Input terminator byte

10SB;

fendif

#ifndef

PEND_SIZE

/* Pending buffer size

#define PEND_SIZE

#fendif

IN_BUFLEN

#ifndef

IN_BUFLEN

#fdefine
fendif

#ifndef

OUT_BUFLEN

128

#fdefine OUT_BUFLEN
fendif

’if

CIN_BUFLEN < 1

! OUT_BUFLEN <« 1

struct DECtalk

{

1! PEND_SIZE < 1)

<< error, mandatory parameters aren’t correct >»>

fendif

typedef

fre—
.
—
.

Chain all units together
1/0 channel
For dt_timeout()
Speech and "splice" flags

*/
*/
*/
*/

pend_fp;
pend_ep;
*in_ptr;

/* Pending buffer fill index
/* Pending buffer empty index
/* 1/0 input buffer pointer

*/
*/
*/

send;
reply;

/* Last sequence sent
/* Last sequence read

struct DECtalk *link;
unit;
short
timeout;
short
flag;
short

short

pend_fc;

char
char

*in_end;
*out_ptr;

short
short
char

SEQUENCE
SEQUENCE

SEQUENCE
char
char
char
char

seq;
*device;

/*
/*
/*
/*

/* Bytes in pending buffer

*/
/* -> end of input buffer
/* -> free spot in output buff. */
/* Sequence look-ahead
/* DECtalk hardware device

pendlPEND_SIZE]l; /* Type-ahead ring buffer
/* 1/0 input buffer
in_buff[IN_BUFLENI];
/* 1/0 output buffer
out _buff[OUT_BUFLENI;

*/
*/

*/
*/
*/

C PROGRAM EXAMPLE

SO,

m——,

The

following

entries

are

operating-system

specific.

#ifdef

unix

#ifdef

BSD_42

struct

sgttyb

stty_save;

Terminal

flags

stty_save;

Terminal

flags

File

felse
#ifdef

UNIX_V

struct

termio

(UNIX

fendif

V7)

fendif
¥endif
#ifdef

rsx

AR,

FILE

*fildes;

descriptor

10SB

iosb;

I1/0

status

QIOPARM

parm;

QI0

parameter

short

pos._xk;

Device

block

characteristics

word

Yendif
}

&
*

*
*

Certain
macros.
as

DECTALK;

not

short
In

returned

and

common

instances,

dt_open().

tests

‘dd’

Note

that

are

expressed

DECtalk

the

I/0

descriptor

arguments

should

"side-effects".

[

di_iskey(dd)

Kk ok

have

routines

all

dt_.isvalid(c)

TRUE if something in type-ahead buffer.
TRUE

argument

valid

keypad

key.

® ok

The following are only useful after executing dt-phnna();
dt _ptest(dd,

TRUE

specific

TRUE

last

DECtalk

dt_.onhook(dd)

reply
is OFFHOODK.

TRUE

last

DECtalk

r3)

dt_offhook(dd)

dt_istimeout(dd)

ONHOOK.

TRUE

last

DECtalk

TIMEOUT.

reply.

The

following

simple

commands

may

written

dt_phone(dd,p3,p4)

Send

phone

dt_get(dd,

sec)

Read

character

(with

dt_putldd,

Send

character

phone

dt_.eol(dd,

c¢)

Send

Yend

%
%k
*

which

DT_DEBUG
may

log

#defined,
all

dt_get()

characters

macros:

message.

line",

and

the

timeout)

DECtalk

flush

dt_put()

standard

output

buffers

are

functions

output

stream.

pe——————

C PROGRAM EXAMPLE

#ifndef DT.DEBUG

dt-ioget
dt_ioput

#define dt_get
#define dt_put
#endif
#jifndef

,
nomacarg

#define dt_iskey(dd)

#define dt.isvalid(c)
#define dt_ptest(dd,r3)
#define dt_offhook(dd)
#define dt_onhook(dd)

(dd->pend_fc

Cc >= ‘0’

It
it

!'= 0)

&& c <= '97)

¢ == 7#% || c == %/
Cc >= A’ && c <= ‘D’I))

\
\

(dt_test(dd, R2_PHONE, r3))
(dt_ptest(dd, R3_PH_OFFHOOK))
(dt_ptest(dd, R3_PH_ONHOOK))

#define dt_istimeout(dd) (dt_ptest(dd, R3_PH_TIMEOUT))

#define dt_phone(dd,p3,p4)
P2_PHONE,

#ifdef

unix

#define dt_eol(dd)
felse

#define dt_eold(dd)

(dt_msg(dd,

p3,

p4,

-1))

R2_PHONE,

(dt_put(dd,

‘\n’),

dt_putddd,

(dt_putCdd,

“\r’),

dt_put(dd,

‘\n’),

dt_put(dd,

0))

fendif

#ifdef

decus
DT_.DEBUG

* This

forces

on Decus C systems.-

traceback

#define

error

exit

“fatal DECtalk

#define I0_ERROR

I1/0 error"

fendif
#endif

#ifndef

I0_.ERROR

#ifdef

wvms

<ssdef.h>
SS$_ABORT

#include
#define I0_ERROR
felse

#define

I[0_ERROR

fendif
fendif
/‘l

* dt_abort may be set by a user program at any time to
Typically, it would be set by dt_trapQ)
* stop DECtalk.
* when a <CNTL/C> C(UNIX INTERRUPT signal) is typed by the
*

terminal

user.

extern int
extern DECTALK
#ifdef

DT._DEBUG

extern int
Yendif

dt .abort;
*dt_root;

*/
/* Set TRUE to stop
/* Root of device chain */

dt_debug;

/* TRUE if debug log

C PROGRAM EXAMPLE

DEMO.C
The executable program’s name is DEMO, derived from this program. DEMO.C
is the main module of the program.

#include

<stdio.h)>

#include

“"dectlk.h"

main(argc,

argv)

int

argc;

char

*argvli];

{

DECTALK

Dectalk

int

retries;

Initializations

int

ncalls;

Completed

char

DECTALK

calls

*dt_open();

"TT2:";

Cargc

dev

retries

ncalls

((dt

argvi1];

dt_debug
if

device

*dev;

extern

dev

*dt;

=
=

TRUE;
dt_open(dev))

NULL)

{

perror(dev);

return;
}
dt_trap();

while

(dt_init(dt))

dt_dcs(dt,

{

P2_MODE,

Catch

One-time

MODE_SQUARE,

retries++;

while

(dt_answer(dt,
(process(dt))

ncalls++;
retries

1))
{

{

CTRL-C

abort

setup

attempts

-1);

Count

Answer

[

the

user

User

Clear

phone

process

ran

ok,

retry

*/
count

}

dt_hangup(dt);

Hangup

Check

interrupt

Error

exit

Error

exit

Got

(dt_.abort)
goto

finis;

the

phone

}
if

(dt_abort)

(retries

goto

finis;

printf(*Too

{
many

lost?

retries\n");

break;
}
}

fprintf(stderr,

"Couldn’t

initialize

DECtalk\n");

C PROGRAM EXAMPLE

finis:

/* Restart output
/* Hangup DECtalk

dt_abort = FALSE;
dt _reset(dt);

/* Force out buffer
/* Close up DECtalk

dt_putCdt, 0);
dt_close(dt);

*/
*/

}

process(dt)

*dt;

dt_talk(dt,

/* Keypad character
/* For echo message

cs
work(301];

"Welcome to DECtalk");

sprintf(work,

dt_talk(dt,

Enable keypad
Error occurred
Do forever...
Key with timeout
Check for timeout
;
Exit if so

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

/* Make ‘*’ special

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

if ('dt_keypad(dt, TRUED)
return (FALSE);
for (33) {
¢ = dt_inkey(dt, 15);
if (Vdt_isvalid(c))
break;

"You pressed %Zc",

work)d;

if (c == "*7) {

dt_timeout(dt,
dt_talk(dt,

0);

c);

/* No timeouts now

*Long message...");

}
}
/i

Timeout

return (Cc ==

normal,

others are errors.

‘T’) ? TRUE

*/
*/

FALSE);

100

C PROGRAM EXAMPLE

DTANSW.C

This routine hangs up the phone and answers on n rings.
/*)LIBRARY
*/
#ifdef

DOCUMENTATION

title

dt_answer

[

index

Answer

the

Telephone

Answer

the

telephone

Synopsis

#include

<stdio.h>

#include

“dectlk.h"

int

dt _answer(dt,

nrings)

DECTALK

*dt;

Device

descriptor

int

nrings;

Number

rings

description

Hang

answer

the
the

phone
phone

(by

calling

after

the

dt_hangup())

specified

and

number

rings.

Return

TRUE

successful,

FALSE

#endif

error.
e

#include

<stdio.h>

#include

"“"dectlk.h"
O

int

dt_answer(dt,
register

nrings)

DECTALK

*dt;

int

nrings;

Hang

the

phone

and

answer

nrings.

{
register
again:

int

code;

(!dt_hangup(dt))

return
dt.dcs(dt,
while
if

Make

on-hook.

P3_PH_ANSWER,

nrings);

(FALSE);
P2_PHONE,

(dt_read(dt,

0),

dt_onhook(dt))

sure

it’s

{

(dt_abort)

return

(FALSE);

TS,

}
if

(dt_onhook(dt))

(!'dt_offhook(dt))

goto

again;

return

Did

answer

ok?

(FALSE);

OK,

clear

timeout

flag

and

type-ahead

counters.

dt->timeout

dt->pend_fc

dt->pend_fp

return

(TRUE);

dt->pend_ep

C PROGRAM EXAMPLE

101

DTCLOS.C

This routine closes the DECtalk channel and frees all buffers.
-

/*)LIBRARY
#ifdef

DOCUMENTATION

title
index

dt_close
|

Terminate DECtalk Operation
Terminate DECtalk Operation

#include
#include

<stdio.h>
“dectlk.h"

synopsis

dt_close(dt)

*dt;

DECTALK

/* DECtalk device

description

Close the DECtalk channel and free all buffers.
is

No error

returned.

fendif

<stdio.h>
“dectlk.h"

#include
#include
#ifdef

|
-

rsx

#include

<cx.h>

#include
#include

<giofun.h>
<qioret.h>

#include
#define QIO_EFN

<qiottd.h>
1

static QIOPARM

noparm;

/* Q10 parm Call zero)

#endif

dt_close(dt)

*dt

* Close

the DECtalk

channel.

{

#ifdef

**linkp;

unix

BSD_42

/* Restore tty flags

ioctlCdt->unit, TCSETA, &dt->stty_saved; /* Restore tty flags

stty(dt-»>unit, ¢dt->stty_save)d;

felse

#ifdef
fendif

UNIX_V

102

C PROGRAM EXAMPLE

Yendif

close(dt->unit);
fendif
#ifdef

vms

sys$dassgn(dt->unit);

fendif
#ifdef

rt11
rs_close(dt->unit);

Yendi
f
#ifdef

rsx

;

qiow(IO.DET,

dt->»unit,

QIO_EFN,

NULL,

fclose(dt->fildes):

NULL,

&noparm);

#endif
/'Ir

Unlink

the

device

&dt_root;

from

the

chain.

for

C(linkp

linkp
if

*linkp

NULL;

&CC*1linkp)->1ink))

(*linkp

*linkp

break:

dt)

{

dt->link;
L,

}

}
free(dt->device);
free((char
return

*)dt);

(NULL);

Aoy

C PROGRAM EXAMPLE

DTCMD.C

This routine sends a DCS command to the DECtalk terminal.
/*J)LIBRARY
*/

#ifdef

DOCUMENTATION

title
index

dt_.cmd

Send DCS w/o String Terminator
Send DCS w/o string terminator

#include
#include

<stdio.h>
“"dectlk.h"

synopsis

int

dt_cmd(dt,

p2,

p3)

DECTALK
int
int

*dt;
p2;
p3;

/* Device descriptor
/* P2.... parameter
/* P3.... parameter

*/
*/
*/

description

This routine sends a DCS command to the DECtalk
The string terminator is not sent.
terminal.
This is needed to send phonemic text or telephone
dial

commands.

The p2 or p3 parameter may be -1

if it

to be

ommitted.

A phonemic text sequence would be sent as follows.
dt_cmd(dt, p2, p3);
dt_talk(dt, "hh’ehlow.");
dt.st(dt);

fendif
finclude
¥include

¢<stdio.h>
"dectlk.h"

static SEQUENCE command =

DCS, DCS_F_DECTALK,

dt_cmd(dt, p2, p3)
register DECTALK
int
|
int

{

{ 3, P1_DECTALK,

*dt;
pe;
pP3;

0 }

/* Device descriptor
/* P2_command or -1
/* P3_.command or -1

*/
*/
*/

103

104

C PROGRAM EXAMPLE

Send

DCS

command,

string

terminator

*/
P

(p2

-1)

command.param(0]

else

p2;

{
command.param(2]

(p3

-1)

command.param{0]

else

{
command.param[(0]

command.param(3]

p3;

}

dt _pesc(dt,

&command);

Wse

C PROGRAM EXAMPLE

DTDCHA.C

105

This routine formats characters into a visible ASCIl datascope format and
writes the resulting text to the indicated file. Note that this routine is independent of DECtalk definitions. Output is via the C standard library. Dumps to
terminals are unbuffered.
/*)LIBRARY
*/

#ifdef

DOCUMENTATION

title
index

dt_dchar

Dump One Character Visibly
Dump one character visibly

#include

<stdio.h>

synopsis

dt_dchar(c,

int
FILE

iov)

/* Character to dump
/* File to write to

c3
*jov;

*/
*/

description

The character is formatted into a visible ASCII
Datascope format and the resulting text written
to

the

file.

indicated

Note that this routine is independent of DECtalk
definitions.

Output is via the C standard library.
is

to a

fendif

terminal,

is unbuffered.

¢<stdio.h>

#include
dt_.dchar(c, iov)
register int
register FILE

*iov;

Dump a

character.

{

work[12];

char

dt_visible(c, work);
fprintf(iov, "%s", work)d;

(isatty(filenoCiov)))
fflush(iov);

If the dump

106

C PROGRAM EXAMPLE

DTDCS.C
This routine sends a DECtalk DCS control sequence using the p2, p3, and p4
parameters. Pn parameters are -1 if not sent. No errors are possible.

/*)LIBRARY
*/

#ifdef

DOCUMENTATION

title

dt_.dcs

index

Send

DECtalk

DCS

Command

Send

DECtalk

DCS

command

sSynopsis

#include

<stdio.h>

*include

"dectlk.h"

dt_des(dt,

p2,

p3,

DECTALK

p4)

*dt;

Device

descriptor
parameter

int

p2;

P2_xxx

int

pP3;

P3_PH_xxxx

parameter

int

p4;

timeout

rings

description

This

routine

sends

using

the

p2,

p3,

and

Note

that

the

are

not

errors

DECtalk
p4

DCS

control

sequence

parameters.

parameters

are

-1

they

sent.

are

possible.

Yendif

finclude

<stdio.h>

#include

"dectlk.h"TM

static

DT_string_-terminator

SEQUENCE

};

dt_des(dt,
register

int

p2,

p3,

{
/*

String

device

terminator

p4)

DECTALK

pe,

p3,

*dt;

Dectalk

p4;

Parameters

*/
send

wfii"m

C PROGRAM EXAMPLE

* Load the parameter buffer and send the sequence.

* dt->send.param(0] contains the number of additional parameters.
*/

{

dt->send.state = DCS;

dt-»>send.final

= DCS_F_DECTALK;

dt->send.private =
dt->»send.inter(0]
dt->send.parami0]
if

(p2

>»=

0;
0;
13

{

dt->send.param(0]++;
dt->send.paraml(2] = p2;
}

(p3 >= 0) o
dt->send.param(0]++;

dt->send.param(3]

= p3;

}

>= 0) {
dt->send.param{0]++;
dt-»send.param(4] = p4;

(p4

dt.pesc(dt,
dt.pesc(dt,

t¢dt->send);
&DTmstringmtarminutor);

107

108

C PROGRAM EXAMPLE

DTDIAL. C

This routine dials the DECtalk telephone, depending on whether the telephone
used is Touch-Tone or pulse type.

/*JLIBRARY
*/

#ifdef

DOCUMENTATION

title

dt_dial

index

Dial

the

Telephone

Dial

the

telephone

Ssynopsis
Ay

#include

<stdio.h>

#include

“"dectlk.h"

int

dt_dial(dt,

p3,

numb,

wait,

DECTALK

msg)

*dt;

Device

int

p3;

P3_PH_xxxx

descriptor

parameter

char

*numb;

Number

int

wait;

See

char

below

*msg;

Announcement

dial

ARSI

description

This

routine

parameter

dials

must

P3_PH_PULSE

For

tone

valid

(pulse

dialing,

touch-tone

the

characters

the

‘"’

All

other

pulse

‘"’

are

Note

dialing

DECtalk

the
‘!’

number

the
it

(for

are

text

offhook

may

contain

any

one

second

delay)

switch-hook

p———

flash.

ignored.

selected,

telephone
is

dial)

("0123456789*#ABCD")

250 millisecond

The

(tone

dial).

interpreted.

telephone.

P3_PH_TONE

characters

that

dialing

for

the

either

will
when

only

not
the

the

digits,

hung

command

up
is

‘!’

and

before
issued.

C PROGRAM EXAMPLE

Call

Pro gress

Detection

DECtalk cannot tell if or when someone answers the
The only way to do this is to speak a message,
phone.
such as "This is DECtalk, please press any button
on the keypad." and wait some limited time for the
The wait and msg
person to press the button.
parameters provide this capability.

1f wait is less than or equal to zero, DECtalk returns
without attempting to verify that someone has answered
The return will be TRUE if the phone is
the phone.
offhook.

I1f wait is greater than zero, it specifies the number
of seconds to wait for a response, and msg is the
(If msg is NULL, the sample text
message to speak.
The message is repeated
shown above will be used.)
continuously until either the alloted time has

elapsed or a button is received.
if the phone is offhook,

TRUE

dt_dial() then returns

as above.

To cause DECtalk to silently wait for a message, use
Note, however, that an
a zero-length string ("").
audible message is required by some public telephone
systems.

When DECtalk returns after call progress detection,
keypad data entry and keypad timeout will be disabled.
fendif
¢<stdio.h>
"dectlk.h"

Yinclude
#include
fdefine

int

ANNOUNCEMENT

dt_dial( dt,
register

int
register
int

char

p3,

DECTALK
char
|

number,

“This is DECtalk, please press any key."
wait, message)

*dt;

p3;

*number;
wait;
*message;

/* Device descriptor

/* P3_PH_PULSE or TONE

/* Number to dial
/* Call progress delay
/* Announcement

*/
*/
*/

109

110

C PROGRAM EXAMPLE

By,

Send

phone

message.

{

|
register

int

code;

int

ARy

dialtime;

long

Time

Paranoia,

Ahh,

paranoia

Send

the

dial

phone

endtime;

extern

long

time();
R,

(number

number

dt_cmd(dt,

dialtime
if

(p3

P2_PHONE,

p3);

strlen(number);
P3_PH_PULSE)

dialtime
while

NULL)

(*number

2:
!=

dt_put(dt,

EO0S)

number

*number++);

MO,

dt_st(dt);

|
code

}

while

dt_read(dt,

(code

(wait

return

dialtime

30);

dt_save(dt,

code));

(dt_offhook(dt));

/“l

Call

progress

detection.

(!dt_offhook(dt)
return

endtime

time(NULL)

(message

message

{

((code

wait

message);

VT);

dt_read(dt,

time(NULL)

dt_dcs(dt,

TRUE))

ANNOUNCEMENT;

dt_put(dt,

while

!dt_keypad(dt,

NULL)

dt_talk(dt,

}

(FALSE);

P2_STOP,

di _keypad(dt,

Speak

Make

announcement
sure

it’s

heard

-1);

{

FALSE);

Enough

User

key?

already

Turn

off

S *

Drop

pending

return

Normal

(TRUE);

keypad

and

text

return

(FALSE):

-1,

-1),

}

dt _hangup(dt);

dt_drain(dt);

else
if (dt_phone(dt,

endtime);

-1,

(dt_isvalid(code))

5))

dt_offhook(dt))
S *

response,

hangup

C PROGRAM EXAMPLE

111

DTDRAI.C

This routine absorbs any type-ahead characters. No errors are possible.
/*ILIBRARY
*/

#ifdef

DOCUMENTATION

title
index

dt_.drain

Drain Pending Input
Drain pending input

#include
#include

<stdio.h>
“dectlk.h"

synopsis

dt_drain(dt)

/* Device descriptor

*dt;

DECTALK

description
type-ahead characters.

Absorb any
No errors

are

possible.

note

On UNIX systems, dt_drain() will also cancel pending
to receive word
This may cause DECtalk
output.
fragments

partial

escape

sequences.

The code is conditionally compiled for two varieties
of UNIX: Ultrix-32 (or 4.2 bsd) and UNIX System V.
Other varieties of UNIX and UNIX-like systems may
need

edit

this

file.

#endif

<stdio.h>

#include

“"dectlk.h"

#include
¥ifdef

unix

dt_drain(dt)
register

*dt;

DECTALK

* dt_drain()

tosses out any pending type-ahead.

{

#ifdef
felse

#ifdef
Yendif
fendif

dt->pend_fc = dt->pend_fp = dt->pend_ep = 0;
BSD_42

ioctl(dt->unit,

TIOCFLUSH,

UNIX_V
ioctl(dt->unit,

TCFLSH,

Yendif

0);

dt->in_ptr
}

NULL);

= dt->in_end = dt->in_buff;

/* UNIX V7

112

C PROGRAM EXAMPLE

#ifdef

wvms

oy,

#include

<iodef.h>

dt_drain(dt)
register

DECTALK

*dt;

S *

iy,

dt_drain()

tosses

out

any

pending

type-ahead.

{

dit->pend_fc

dt->pend_fp

dt->pend_ep

This

probably

sub-optimal.

I0$_READLBLK

with

should

"sys$qiow(...
a

zero-length

possible

|
IO$M_PURGE

timeout,

I0$M_TIMED

but

sure

IOSM_NOECHO

IO$SM_NOFILTR

don’t

know.

*/
while

(dt_vmsread(dt,

I0$ _READLBLK
INLBUFLEN,

>»=

IOSM_TIMED,

IN_BUFLEN)

;

dt->in_ptr

dt->in_end

dt->in_buff;

}
Yendif
#ifdef

rt11

#include

<rsts.h>

dt.drain(dt)
register

DECTALK

/¥
*

*dt;

,
di_drain()

tosses

out

any

pending

type-ahead.

{
dt->pend_fc

dt->pend_fp

dt->pend_ep

clrxrb();

xrb.xrlen
xrb.xrci

=
=

xrb.xrblkm

dt->unit
=

Cancel

type-ahead

TTYHND;

rstsys(_SPEC);
dt->in_ptr

dt->in_end

dt->in_buff;

}
#endif

#ifdef

rsx

dt_drain(dt)
register

DECTALK

*dt;

I *

di_drain()

tosses

out

any

pending

type-ahead.

{

dt->pend_fc

dt->pend_fp

dt->pend_ep

do
dt->in_ptr
}

while

dt->in_ptr

}

fendif

dt->in_end

(dt_get(dt,
=

dt->in_end

dt->in_buff;

0);
=

dt->in_buff;

C PROGRAM EXAMPLE

113

DTDUMP.C

This routine writes an escape sequence buffer to the standard output file. This
mode is for debugging.

/*)LIBRARY
*/

#ifdef

DOCUMENTATION

title

dt _dump

Dump Escape Sequence Buffer

#include
#include

<stdio.h>
“dectk.h"

index

Dump escape sequence buffer

Synopsis

int

seq)
*what;
*seq;

dt _dump(what,
char
SEQUENCE

/* Explanation
/* Buffer to dump

*/
*/

description

The requested escape uaqumncu'buffar is written
(visibly)
If

what

Output
For

the standard output

not

is via

NULL,

the C

file.

written as an

standard

library.

example,

#include

<¢stdio.h>

Yinclude

"dectlk.h"

DECTALK

*dt;

extern DECTALK

*dt_open();

*
*

Open a DECtalk device,
request phone status and

dump

returned

status

sequence.

= dt_open("kb2:");
dt_phone(dt, P2_PH_STATUS, -1);
dt_.dump("status", &dt->reply)d;
fendif

#include

<stdio.h>

finclude

"dectlk.h"

identifier.

114

C PROGRAM EXAMPLE

dt _dump(what,

seq)

char

*what:

SEQUENCE

*seq;

{
register

int

char

*wps

char

work(81];

extern

char

*dt_visible();
O,

(what

NULL)

printf("Xs:
wp

\"",

what);

dt_visible(seq->state,

switch

case

(seq->state)

work);
DN,

{

ESC:

case

CSI:

case

DCS:
if

(seq->private

for

dt_visible(seq->private,

€i

(seq->paramli]

*fwprt+

seq->param{0];

157y

sprintfCwp,

wp);

i++)

"Xu",

{

seq->paramlil);

strlen(wp);

‘

}
}

for

dt_visible(seq->inter[i],

«=

seq->inter[0];

i++)
wp);

break;
default:
break;
}
if
*wp

(seq->final
wp

EOS;

dt_visible(seq->final,

printf("%Xs%s",

work,

(what

wp);

NULL)

u\n\pu).

}

iSOy

C PROGRAM EXAMPLE

115

DTEOL.C

This routine writes an end of line to DECtalk and calls the operating system

executive service to write the local output buffer to the terminal. No value is
returned.

You need this routine on operating systems that enforce line wraparound on
the terminal. DTEOL.C also improves the appearance of the debugging logs.
/*ILIBRARY
*/

#ifdef

DOCUMENTATION

title
index

dt_eol

Write End of Line to DECtalk
Write End of Line to DECtalk

#include
#include

¢<stdio.h>
“"dectlk.h"

Ssynopsis

dt_.eol(dt)

DECTALK

*dt;

/* Device descriptor

description

An "end of line®"TM is written to DECtalk and the
operating system executive service is called to
cause the local output buffer to be written to
the

terminal.

No value

returned.

This routine is needed on operating systems that
enforce "line wrap-around" on terminal devices.
It also improves the appearance of debugging logs.
fendif

¢<stdio.h>
“"dectlk.h"

#include
#include
#ifdef

dt_.eol

undef

dt_.eol

fendif

dt_eol(dt)

*dt;

DECTALK

{

#ifndef

uni X

dt_putCdt,

‘\r?);

dt_put(dt,
dt.putd(dt,

0);

fendif

‘\n’);

Device

descriptor

116

C PROGRAM EXAMPLE

T
gy,

DTGESC.C
This routine reads an escape sequence or keypad character.
e

/*JILIBRARY

*/
#ifdef

DOCUMENTATION

title

dt_gesc

index

Read

Escape

Sequence

Character

Read

escape

sequence

character

synopsis

#include

<stdio.h>

#include

“"dectlk.h"

int
dt_gesc(dt,

sec)

DECTALK

*dt;

Device

char

sec;

0.5.

keypad

descriptor

timeout

value

degcriptibn
Read

escape

sequence

dt_gesc()

interprets

including

escape

ISO

646,

introducer

IS0

The

function

and

processes

until

DEC

Standard

dt_gesc()

138

types

CSI,

returned

the

application

dt_gesc()

escape

DCS,

and

the

structure

CSI,

stream

all

When

the

function

the

interpretted

structure.

getchar(),
except

when

value

the

case

character

but

before

get

DCS,

of
the

character

the

input

tokens

stream

DCS

string.

and

control

any

seq

cases

final

control

the

CSI, and DCS,
of these introducers

transforms

sequences,

138.

sequence,

between

representations

extensions

the

device

similarly

ESC,

after

the

dt_gesc()
is

each

characters

coded

encountered.

introduction

sequences.

ESC,

encountered,

caller

character

characters,

ESC,
is

the

with

following

sequence
to

(dt_get()),

introduction

recognizes

characters

character

from

the

sandwiched

stream
of

8-bit

required

Standard

function

6429

the

When

IS0

returns

data

adhering

and

complete

DEC

stream

2022,

control

first

sequences

character.

consisting

sequences,

and

recognized

sequence

returned

body

the

DCS

that

sequence

The

caller may treat
ignoring the returned
the

returned

function

value

DCS.

C PROGRAM EXAMPLE

117

An additional function performed by dt_gesc() is that all
C1 control functions received in their 7-bit form are returned
to the caller in their 8-bit form, thus eliminating the need
for the caller to process C1 control functions in their (7-bit)
escape sequence form and enforcing the equivalence of the 7-bit
The function
and 8-bit forms of the C1 control functions.
also enforces the sequence cancellation effect of the SUB and
CAN control

characters.

The dt_gesc() function calls the user-supplied di_get()
(read one character) function as many times as required to
complete an escape sequence, control sequence, or Digital
standard DCS introduction sequence. In the passed data
structure, it returns the final character, intermediate
characters,

and parameter values.

Since 7-bit operation is a compatible subset of 8-bit
operation, there is -- normally -- no distinction in the
dt_gesc() function between the two environments.

The application program may set the _FLAG_EIGHTBIT bit
in dt->flag to receive C1 control characters in their
1f _FLAG_EIGHTBIT is set on, the
eight-bit form.
application program must also ensure that the host
operating system communication line receives eight
data bits, and that DECtalk setup has set HOST FORMAT EIGHT.
Also, dt_get() may return two special values,
DT_ERR and DT_TIMEOUT, to indicate operating-system errors
and communication line timeouts respectively.

may be embedded in sequences,
Because C0 control characters
and must be interpretted as if they occurred before the
sequence in the stream, the dt_gesc() function
retains internal state information in the sequence data
The seq.state value is zero
structure from call to call.
If non-zero,
on return to indicate a complete escape sequence.
it contains the sequence

introducer.

I1f the "seq.state"” element is zero, dt_gesc() assumes
that the remainder of the data structure is invalid and that
A non-zero
there is no data being retained from a prior call.
value for the "seq.state® element indicates a particular
internal state (ESC, CSI, or DCS) that the parser should assume
on

the next

call.

Intermediate characters and parameter values interpretted up
to the occurrence of the embedded control character are also
stored in the returned data structure and also should not be

by the
altered

caller.

Escape sequence syntax errors are indicated by setting the
seq.private parameter to ‘X’ (which is not a possible
private parameter).

118

C PROGRAM EXAMPLE

the

dt_gesc()

function

allowed

maximum

returned

data

structure

character

was

received

after
If

number

the

dt_gesc()

indicates

than

number

are

ignored

and

the

allowed

maximum

each

contains

the

call

the

number

Zero

seq.final

The

seq.private

seq.param({0]

one

than

the

extra

data

structure

parameters
the

characters

the
parameters

indicates

was

dt->seq

indicate

that

received.

SEQUENCE

sequence

complete

final

sequence

character

Private

parameter

EAS,

number

parameter

The

course,

the

intermediate

information.

¢,

encounters

dt_gesc()

seq.state

the

parameters,

returned

following

that

allowed.

than

characters,

stored.

function

maximum

intermediate

the maximum are not

allowed

After

encounters

character:

for

errors

values

(0:SEQ_PARMAX)
seq.paramin]

(unsigned)

The

seq.inter(0]

The

number

n’th

parameter

intermediate

value

characters

(0:SEQ_INTMAX+1)
seq.interlnl]

general,

taken

ignore

the

any

action

simplify

are

sequences

returned

n’th

with

too

intermediate

and

determine

number

final

the

many

characters

action.

intermediate

character.

should
easy

the

code,

this

module

values

and

assumes

invalid

escape

doesn’t

that
sequences.

test

all

characters

since

will

not

for

overly

function.

parameter

due

The

intermediate

whole

the

large

(char)

overflow

match

errors

fendif

#include

<stdio.h>

#include

"dectlk.h"

int
dt_gesc(dt,
register

int

sec)

DECTALK

*dt

Dectalk

sec:

0.5.

device

timeout

C PROGRAM EXAMPLE

119

f"l‘

Return

sequence

character

*/
{

int

reg ister

#ifdef

dec us
reg ister

unsigned

reg ister

unsigned

*Ps

Yelse

short

*p;

fendif
#ifdef

DT. DEBUG
if

{

(dt_debug)

dt_put(dt, 0);
printf(*”get: \"");
if

(isatty(fileno(stdout)))
fflush(stdout);

#endif
for

(;3)

{

I *

* Loop until end of sequence forces an exit.
* Get the next character from the input stream.
* Note: we assume that negative values are
*

“out

band"

Note

that

signals.

DT_TIMEOUT and DT_ERR must be negative values.

((c
if

= dt_get(dt,
((dt->flag &
c &= 0x7F;

sec)) > 0) {
_FLAG_EIGHTBIT) == 0)
/* Enforce 7-bit

input

}

NUL

continue;

DEL)

Ignore NUL,

DEL

Branch

CSI,

ci_continue when

changing

<ESC>

[

etc.

cl_continue:

if (c
i1 ¢
it ¢

== ESC
== CSI
== DCS)

/*
/*
/*

ESC, CSI, DCS
Introduce control
sequences.

dt->seq.state

dt->seq.inter(0]
dt->seq.private
dt->seq.paraml0]
dt->seq.param(1]

=
=
=
=

0;
0;
0;
0;

continue;

*/
*/
*/

else

(di->seq.state

goto
else

exit;
((c

0x80

CAN)

SUB))

dt->seq.state
goto

/*
/*

pending

Return

0x9F)

{

the

sequence

character

control

sequence

resetter.

‘

exit;

}

else

goto

else

0x20)

control

error

exit;

0x2F)

{

Intermediate

dt->seq.inter[0]++;
if

(dt->seq.inter[0]

SEQ_INTMAX)

dt->seq.interldt->seq.inter[0]]
}

else

(dt->seq.state

(dt->seq.inter[0]

ESC)

{

C(c

ESC

O0x3F)

final

0x20)

{

This

the

character.

parse

control

7-bit

form

Convert

character

and

without

getting

0x3F)

0x80;

o
*

the

control

actual

restart

another

the

character.

*/
c

goto

cl1_continue;

}
else

{
break;

else

>»=

0x3F)

0x3C)

{

else

ending

introducer?

Parameter

Private

“X’;

error

dt->seq.private

{

(dt->seq.param(0]

(dt->seq.inter(0]

Not

[

not

dt->seq.inter[0]
dt->seq.private

=
=

Store it

Flag

seen

private

0;
“X’;

‘

—

dt->seq.param(0]++;
!'=

first?

{
dt->seq.param{0]++;

else

ESC

(dt->seq.param(0]
dt->seq.private

Ordinary

Record

first

Syntax

error

{

C PROGRAM EXAMPLE

/* 0..9

if Cc <= ‘97) |

if (dt->seq.param(0] <= SEQ_PARMAX) {

room.

i5s

it.

Store

* There

p points to current parameter.
This should check for value

overflow.
/

p = &4(dt->seq.paramldt->seq.param(011);
*p =

(*p *

10) + C(c -

“0°);

}

else

{

dt->seq.private =

‘X’;

}
}

/* Separator

else if (c == ‘;’) {

if (dt->seq.paraml{0] >= SEQ_PARMAX)
dt->seq.param[0] = SEQ_PARMAX + 1;

else

{
/ *

* There’s room to setup for
* another parameter value.
*/

dt->seq.paraml(0]++;

dt->seq.paramldt->seq.param(0]1] = 0;

}
}

else {

dt->seq.private

/* colon is invalid

/* CS1/DCS terminator

‘X’;

}
}

else {

if (dt->seq.paraml0] == 0) /* No parameters:
dt->seq.param[0]++; /* want one zero-value
/* Exit parser
break;

*/
*/
*/

}
}‘

* Control transfers to here as result of either of the
* two break statements. Character is the final char.
* of ESC,

CSI,

or DCS.

if (dt->seq.param(0] > SEQ_PARMAX) {

dt->seq.param[0] = SEQ_PARMAX; /* Set count to max. */
*/
/* Flag an error
dt->seq.private = ‘X’

r
.

}

#ifdef
felse

dt->seq.final = c;

/* Store final char.

c= dt->seq.state;

/* Fetch return value

decus

¢ = C(unsigned short) dt->seq.state;

121

122

C PROGRAM EXAMPLE

#endif

dt->seq.state

exit:

#ifdef

Here

and

DT_DEBUG

sequence
to

pending

return

char

*/
*/

(dt_debug)
printf("\"\n");

*endif
return

}

(c);

return.

C PROGRAM EXAMPLE

DTGET.C

This routine reads a character from the DECtalk terminal line.
/*)LIBRARY
*/

#ifdef

DOCUMENTATION

title
index

dt_get

Read one Character from DECtalk
Read one character from DECtalk

#include
Yinclude

¢<stdio.h>
“"dectlk.h"

synopsis

int

dt_.get(dt,

DECTALK
int

sec)

*dt;
sec;

/* Device descriptor
/* 0.S. timeout param.

*/
*/

description

One character is read from the DECtalk terminal line.
The sec parameter enables operating-system timeout;
it is zero if no timeout

is needed.

dt.get() returns the character or an error code.
DT_ERROR

DT_TIMEOUT

An operating system error
Cor <CTRL-C> interrupt) was received.

The sec parameter was nonzero and no

character was received in sec seconds.

I1f DT_DEBUG is #defined when the library is compiled
and the global dt_debug is set nonzero (by the
application program), the character
received is logged to the standard output device.

fendif
#include

¢<stdio.h>

#include

“"dectlk.h"

#ifdef

dt_-get

#fundef

dt_get

*fendif

123

124

C PROGRAM EXAMPLE

int

dt _debug;

int

dt_get(dt,
register

sec)

DECTALK

int

*dt:

Device

sec;

Operating

[

descriptor

system

*/
timeout

extern
¢

int

dt _debug;

dt_ioget(dt,

(dt_debug

!'=

dt_dchar(c,
return

sec);

0)
stdout);

(c);

——

C PROGRAM EXAMPLE

DTHANG.C

Hang up the telephone connected to DECtalk.

/*)LIBRARY
*/

#ifdef

DOCUMENTATION

title
index

dt_hangup

Hangup the telephone
Hangup the telephone

#include
#include

<stdio.h>
“"dectlk.h"

Synopsis

dt_hangup(dt)

*dt;

DECTALK

/* Device descriptor

description

telephone connected to DECtalk.
if successful, FALSE if an error.

Hang up the
Return TRUE
fendif

¢<stdio.h>

#include

“"dectlk.h"

#include
int

dt_hangup(dt)

*dt;

* dt_hangup()

hangs

the phone.

{

int

code;

dt_drain(dt);
if ({dt_phone(dt, P3_PH_STATUS,

/* Drain pending text
-1)) /* Check state

*/
*/

*/
/* Oops
*/
/* 1f it’s not hung up
if ('dt_phone(dt, P3_PH_HANGUP, -1))
*/
/* Couldn’t hangup?
return (FALSE);
*/
/* While still off-hook
while (dt_offhook(dt))
*/
/* Exit if interrupt
if (dt_abort)

return (FALSE);
if (dt_offhook(dt)) {

/* signal sets
return (FALSE);
/* Wait and poll
sleep(5);
if ('dt_phone(dt, P3_PH_STATUS, -1))
/* Poll failed?
return (FALSE);

again

*/
*/

¥
}

if (Ydt_onhook(dt))
return

(FALSE);

/* Did it hang up ok?

125

126

C PROGRAM EXAMPLE

DTINIT.C
This routine initializes the DECtalk terminal on the channel opened on dt.

/ *)LIBRARY
*/

#ifdef

DOCUMENTATION

title

dt_init

index

DECtalk

Initialization

Routine

DECtalk

initialization

routine

Synopsis

#include

<stdio.h>

¥include

“"dectlk.h"

int
dt.init(dt)

DECTALK

*dt;

Device

descriptor

description
Initialize

the

DECtalk

terminal

the

channel

opened

dt.

Return

TRUE

Return

FALSE

the

device

initialized

successfully.

failure.

note

This

routine

does

not

escape

turns

off

inadvertently

"local

mode"

send

response

a
to

logging
the

terminal

"who

are

you"

sequence.

Yendif
#include

¢<stdio.h>

#include

"“"dectlk.h"

static

SEQUENCE

csI,

DT.who.are_you

‘¢’

s
int
dt_init(dt)
register

DECTALK

*dt;

{

p————;

C PROGRAM EXAMPLE

127

dt_init()

called

initialize DECtalk.

{

int

code;

dt_drain(dt);
dt_dcs(dt, P2_TERMINAL, 0,
dt->flag &= ~_FLAG_TERM;

-1);

/*
/*
/*

Ignore pending input
No local->host stuff
Remember this fact

*/
*/
*/

I *

* Read device attributes and fail if it isn’t DECtalk.
* Expected reply is
<ESC>[?19c for the DTCO1-AA
*/

dt_pesc(dt,

&DT_who_are_you);

15)

dt->reply.final

dt->reply.private

dt->reply.interf0]

dt->reply.parami0]

(dt_read(dt,

CSI
‘¢’
==

2/
0

1
((code = dt->reply.param(1])
dt_reset(dt);
return (TRUE);

}

return

(FALSE);

CSI_DA_PRODUCT)) A
/* Reset device
/* Hang up and restart

*/
*/

128

C PROGRAM EXAMPLE

DTINKE. C
This routine reads a telephone keypad button.

/*)LIBRA RY
*/
#ifdef

DOCUMENTATION

title

dt_inkey

index

Read

Telephone

Keypad

Character

Read

Telephone

Keypad

Character

Synopsis

#include

<stdio.h>

#include

“"dectlk.h"

int
dt_inkey(dt,

sec)

DECTALK
int

*dt;

Device

sec;

Seconds

descriptor
to

wait

descript ion
This

routine

reads

The

application

the

keypad

telephone

program

(by

calling

di_inkey()

will

call

disable

timeouts.

sec

nonzero,

seconds

turn

will

The

for

off

will

the

value,

character

valid

Keypad

Badly

Unexpected

system

is
(as

received
may

requirements).

timeout.

button

"ABCD"TM

may

certain

operating-system

phones.)

code

will

follows.

phone

zero,

catch

plus

keypad

that

‘H’

additional

keypad

the

number

problems)

generated

the

(needed

line

(Note

The

enable

timeouts.

timeout

0123456789*#ABCD

enabled

response.

timeout

specific

returns

button.

TRUE)).

indicate

keypad

times

operating-system

dt_inkey()

dt_-keypad(dt,

communication

four

keypad

previously

dt_timeout()

operating-system

hardware
set

wait

has

error

timeout
parsed

the

required

escape

sequence.

telephone

hangup.

DECtalk
by

device

specific

hangs

telephone

C PROGRAM EXAMPLE

fendif

"dectlk.h"

Fudge

capacities

<stdio.h>

#include

needed

inspection.

and

because

terminal

strategies.

output

should

buffering

tuned

The

#include

program

DECtalk.
and

less

large

than

DECtalk
two

may

phrases

synthesizer

sections.

application

program may

the

communication

because

buffers

value

when

RSTS/E

bytes

have
in

about

the
the

RSTS/E

remain

value

incorrectly

line

100

letter

will

resume

sound

set

assume

transmitted

bytes

too

that

its

input

and
low,

the

DECtalk

broken.

#ifdef

rt11

*fdefine

FUDGE

RSTS/E

FUDGE

This

*dt;

DECtalk

device

sec;

Keypad

timeout

needs

extra

time

felse

#define

just

guess

Yendif

dt_inkey(dt,

sec)

DECTALK

int
{

int

code;

int

os.timeout;

dt_timeout(dt,
if

sec);

(dit_iskey(dt))
code

Set/clear

timeout

{

dt->pend(dt->pend_epl;

(++dt->pend_ep

dt->pend_ep

PEND_SIZE)

dt->pend_fc--;
}
else

{
if

((code

dt_read(dt,

(sec
code
else

code

(sec

(dt_istimeout(dt))

‘E’;
«

‘T*;

dt->timeout

}

else

if
code

else
{i!

(dt_onhook(dt))
=

tdt_isvalid(code))
code

}

return

‘H’;

(dt->reply.private

(code)d;

‘X’*;

‘X’

FUDGE)))

129

130

C PROGRAM EXAMPLE

—

DTIOGE.C

This routine reads one character from the DECtalk terminal line. DTIOGE.C is
maximized for efficiency.

/*)LIBRARY
*/

I *

Edit

84.04.10

History

HNGTTY

incorrectly

specified.
J

#ifdef

DOCUMENTATION

title
index

dt_.ioget

Read
Read

include

<stdio.h>

Yinclude

"dectlk.h"

one
one

Character
character

—

from DECtalk
from DECtalk

Synopsis
S

int

di_.ioget(dt,

sec)

DECTALK

*dt;

Device

int

sec;

0.S.

descriptor

timeout

param.

*/
"

description

One

character is read from the DECtalk terminal line.
sec parameter enables operating-system timeout;

The
it

zero

dt-inget()

timeout

returns

the

needed.

character

error

code.
Wi,
o omana

DT_ERROR

DT.TIMEOUT

operating

(or

<CTRL-C>

The
no

sec

system

interrupt)

parameter

character

error

was

received.

nonzero

received

and
sec

seconds.

dt_ioget()
routine.
the

is
It

DECtalk

the
is

operating-system

the

only

terminal

routine

specific
read

input

data

P ———

from

line.

note

DS,

vms,

also

defined.

not

This

call

should

this

module

4,2BSD)

internally-used

and

dt_vmsread(),

programs

should

routine.

contains

UNIX

#define

routine,

Application

specific

System

one

code

The

these

for

Ultrix-32

makefile

for

appropriate.

the

(UNIX

library
P,

C PROGRAM EXAMPLE

Yendif
#include

«<stdio.h)>

#include

“"dectlk.h'

Define

all

DECtalk

library

globals

this

module.

int

dt._abort;

TRUE

DECTALK

*dt_root;

Chain

#ifdef

unix

Yinclude

#ifdef

interrupt

all

open

units

<errno.h>

BSD_42

#include

#include

<time.h>

felse

#ifdef

UNIX_V

#include

<signal.h>

static

{}

ignore()

Dummy

function

for

signals

fendif
Yendif
int

dt_ioget(dt,

sec)

DECTALK

int

*dt;

DECtalk

s5ecC;

Wait

device

time,

forever

UNIX:

Fill

the

input

buffer,

return

the

(first)

incount;

Count

fdmask

File

timeout;

Select()

ecode;

For

errno;

System

character.

*/
{

int

and

error

code

mask

value

BSD._42

auto

int

struct

timeval

descriptor
timer

felse

#ifdef

UNIX_V

int

error

handling

error

value

*/
*/

#endif
#endif
/*

Return

buffered

character

(if

any)

(dt->in_ptr
return

dt->in_end)

(*dt->in_ptr++

O0xFF);

must

refill

the

buffer

dt->in_ptr

dt_ioput(dt,
if

dt->in_end

0);

(dt_abort)

return

(DT_ERROR);

&dt->in_buffl0];

Flush

output

131

C PROGRAM EXAMPLE

132

#ifdef

BSD.42
fdmask

¢¢

dt->unit:

timeout.tv_usec

timeout.tv_.sec
incount
if

return
if

sec;

Max.

(incount

unit

milliseconds

seconds

&fdmask,

wait

&timeout):

dt_abort)

(DT_.ERROR);

return

else

Select

select(dt->unit

(incount

else

()

(DT_TIMEQUT);

Select

Timeout

failed?

Guess

triggered?

*/
*/
*/

{
incount

read(dt-»>unit,

dt->in_buff,

IN_BUFLEN);

}
PR

#else
#ifdef

UNIX_.V

‘

signal(SIGALRM,

Enable

alarms

alarm(sec);

Start

timeout

errno

Clear

error

ignore)d;

incount

ecode

errno;

read(dt->unit,

dt->in_buff,

alarm(0);
signal (SIGALRM,

SIG_IGN);

Cincount
return

flag

*/
-

IN_BUFLEN);

Save

Cancel

timeout

Disable

alarms

error

Did

code

timeout?

ecode

EINTR)

(DT_TIMEOUT);

‘

Return

Other

error?

Return

bad

failure

fendif
s,

¥endif

(dt_abort
return

dt->in_.end
return

incount

(DT_ERROR);
=

failure

g&dt->in_bufflincountl];

(*dt->in_ptr++

O0xFF);

}
#endif
#ifdef

wvms

#include

<ssdef.h>

System

#include

Ciodef.h>

1/0

status

request

codes

A—————

Define

the

possible

vms

input

flavors
RO P,

¥define

RAW_READ

(I0$_READLBLK

#define

TIMED_READ

(RAW_READ

typedef

struct

}

io_status_block

TOSM_NOECHO

IOSM_NOFILTR)

I0$SM_TIMED)

{

short

int

status

1/0

status

code

short

int

term_offset;

Datum

size

short

int

terminator;

Input

terminator

short

int

term_size;

Terminator

*/
*/

size

I0STAB;

int

dt_ioget(dt,
register

int

sec)

DECTALK

*dt;

DECtalk

s5ec;

Wait

device

time,

forever

*/
.

C PROGRAM EXAMPLE

/'l'

* YMS:

Fill

the

input buffer,

return the next

(first)

character.

{

/* Count and error

incount;

int

code */

/’l

Return buffered

character

(if any)

(dt->in_ptr < dt->in_end)
return (*dt->in_ptr++ & OxFF);

/-lf

refill

We must

the buffer

dt->in_ptr

dt->in_end

&dt->in_buffl01l;

0);

dt.ioput(dt,

Flush output

* First read anything in the system type-ahead
* buffer by reading with a zero timeout.
* If nothing was read, read one byte (with
)
* timeout if specified).
*/

incount
if

dt_vmsread(dt,

TIMED_READ,

Cincount

DT_TIMEQUT)

incount

dt.vmsread(dt,

(sec

IN_BUFLEN,

0);

{

> 0) ? TIMED_READ: RAW_READ,

sec);

}

Cincount

return

(incount)d;

Return error

code

Common exit

from all

read

routines

dt->in_end = &dt-»in_bufflincountl;
return (*dt->in_ptr++ & OxFF);
¥

gmmg

WMMM
a

int

dt_vmsread(dt, command, how_many, timeout)
/* DECtalk device
*dt;
register DECTALK
/* QI0 command
command;
int

int

how.many;
timeout;

/* How many bytes to read
/*

timeout value

*/
*y

133

134

C PROGRAM EXAMPLE

ARG,

.[l-

L—

Actually

read

from

vms.

Return

(result

the

(result

error

(result

cannot

int

number

equal

code

bytes

(EOF

read
TIMEOUT)

zero).

I0STAB
register

int

incount:

Status

status;

1/0

status

For

debugging

parameter

block

/*
*

termset

allows

any

terminator

character".
the

operating

mask

indicating

i mplemented

system

"terminate

VMS,

handle

this

XOFF/XON.

static

long

termsetl(2]

{

};
s

(dt_abort)
return

(DT_ERROR):

The

status

will

yield

entries

the

term- offset

number

and

bytes

term_size

read.

*/
incount

Event

flag

dt->unit,

sys$qiow(1,

Input

channel

command,

Timed

read

&status,

170

status

block

NULL,

AST

block

(none)

AST

parameter

dt->in_buff,

how_many,

buffer

timeout,

wait

dtermset,

terminator

NULL,

ignored

(prompt

buffer)

0);

ignored

(prompt

size)

(incount
return

else

return

SS$_TIMEOUT)

return

!'=

buffer

length

seconds

Timeout

Some

set

returned

*/
I

SS$_NORMAL)

other

error

(DT_ERROR);
status.term_offset

(incount

return

input

(DT_TIMEQUT);

(incount

incount

(DT_TIMEDUT);

status.term_size;
/*

Nothing

equals

input?

timeout.

(incount):

}
fendif

#ifdef

rt11

/%
*

RSTS/E

*/
#include

<rsts.h)

int

p—————,

dt_ioget(dt,
register

int

sec)

DECTALK

*dt;

/¥

DECtalk

sec:!

Wait

device

time,

forever

C PROGRAM EXAMPLE

* RSTS/E: Fill the input buffer, return the next (first) character.

{

—

/* Count and error code */

incount;

* Return buffered character

(if any)

(dt->in_ptr « dt-»in_.end)
return (*dt->in_ptr++ & OxFF);

* We must refill the buffer

prom—

dt-»in_ptr = dt->in_end = &dt->in_buffl(0];
/* Flush output
dt_ioput(dt, 0);
if

(dt_abort)
return (DT_.ERROR);

/*I'

handles

RSTS/E

p—

timeout

within

the operating system.

clrxrb();

xrb.xrlen = 4;

xrb.xrci = dt->unit *
xrb.xrblkm = TTYHND;

/* No delimiter

/* No echo

rstsys(_SPEC);

clrxrb();

xrb.xrlen = 3;

[—

xrb.xrci

= dt->unit * 2;

xrb.xrblkm

TTYHND;

rstsys(_SPEC);

incount = rs_read(dt-»unit, dt->in_buff,
IN_BUFLEN, 0, 0, sec, 0);
/% 84.04.10
if Cincount == (-HNGTTY))

gn—
.

return

(DT_TIMEOUT);

else if (incount <= 0)
return (DT_ERROR);

[
*

l’*

from all

read routines

dt->in_end = &dt->in_bufflincountl;

return
}‘

p—

Common exit

fendif
#ifdef

rsx

(*dt->in_ptr++

O0xFF);

135

136

C PROGRAM EXAMPLE

T
—

Load

RSX

specific

information:

cx.h

common

qiofun.h

I1/0

service

function

qioret.h

I1/0

service

error

qiottd.h

Terminal

lunbuf.h

Device

header

I/0

codes

and

service

status

bits

characteristics

and

codes

bytes

buffer

#include

<cx.h>

#include

<qiofun.h>

#include

<qioret.h>

#include

<qiottd.h>

#include

<lunbuf.h>

#define

QIO_EFN

1/0

#define

MKT_EFN

Time

static

char

gmcbufl2]

{

static

GQIOPARM

gmcparm

{

gmcbuf,

static

int

termtablel( 161

TC_TBF

};

sizeof
/*

event

get

event

flag

typeahead

gmcbuf

flag

count

};

Terminator

bitmask

int

dt_ioget(dt,
register

sec)

DECTALK

int

*dt;

DECtalk

s5ec;

Wait

buffer,

return

device

time,

forever

*y/

RSX:

Fill

the

input

the

incount;

Count

*ip;

Event

(first)

character.

{

int

char

int

errorcode;

int

efn_bufferl(41];

and

copy

flag

error
rsx

code
buff

buffer

*/
*/

/’*

Return

bufferedicharacter

(if

any)

-y,

(dt->in_ptr
return

dt->in_end)

(*dt->in_ptr++

O0xFF);

/'I'

must

refill

the

buffer

*/
dt->in_ptr

dt _ioput(dt,

dt->in_end

0);

(dt_abort)

(dt->pos_xk)

return

&dt->in_buffl0];

Flush

output

(DT_ERROR):

{

AT,

C PROGRAM EXAMPLE

* The PR0O-350 XK:

port

is actually pretty simple.

dt->in_buff;

dt->parm.buffer

—
*

dt->parm.size = IN_BUFLEN;
dt->parm.p3 = 0;

pa—
i

if (Cincount = fixiosb(dt))
dt->parm.size = 1;

MMW%

&dt-»iosb,

errorcode

NULL,

é¢dt->iosb,

{

NULL,

&dt->parm);

{

GQIO_EFN,

&dt->iosb,

Cerrorcode

[S_SUC)

DT_TIMEQOUT

TF_TMO,

{

NULL,

dt->unit,

&dt->parm);

((errorcode

return
?

qiow(IO_RLB

errorcode

&dt->parm);

QIO_-EFN,

((dt->parm.p3 = (256 * sec)) == 0) {
errorcode = qiow(IO_RLB, dt->unit, QIO_EFN,

else

a—

/* No timeout
dt->unit,

TF_TMO,

qiow(IO_RLB

[S_TMO)

DT_ERROR);

}

fixiosb(dt))

(Cincount

{

(DT_TIMEOUT);

return

}

r—

}

;

}

else

—
?

{

* Read from a terminal.
*
*

First, check whether anything
system type-ahead buffer.

the

errorcode = qiow(SF_GMC, dt->unit,
&dt->»iosb, NULL, &gmcparm);
if (errorcode !'= [S_SUC)
gmcbufl11

dt->parm.buffer

dt->in_buff;

dt->parm.size = 1;
if (Cincount = (gmcbufl1]

I
7

(incount
incount

>
=

dt->parm.size

errorcode =
f

/* Assume 1
O0xFFJ)) > 0)

byte
|

read

incount;

qiow(IO_RTT

TF_RNE,

&dt->parm)d;

dt->unit,

fixiosb(dt);

incount

(incount

{

}

—

(sec

dt->parm.table

termtable;

qiow(IO_RTT { TF_RNE, dt->unit, QIO-EFN,
&¢dt->iosb, NULL, &dt->parm);

?
}

else

{

IN_BUFLEN)
IN_BUFLEN;

&¢dt->iosb, NULL,

frm—

QIO_EFN,

(Cincount = fixiosb(dt))
return (DT_ERROR);

QIO_EFN,

137

138

C PROGRAM EXAMPLE

AR,

/‘*

AIOIS

VAX

timeout

(nor

have

Set

Read

completes,

cancel

completes,

cancel

compatibility

doesn’t

does

this

support

cause

the

hard

read

error).

with

Thus,

way .

mark

one

time

byte

(mrkt{MKT_EFN,

qio(I0O.RTT

(alarm)

without

"timeout"

seconds.

the

wait

the

timeout.

the

timeout

the

readin.

sec,

TF_RNE,

&dt->iosb,

return

for

waiting.

NULL)

!'=

dt->unit,

NULL,

IS_SUC

QIO_EFN,

&dt->parm)

(DT_ERROR):;

Can’t

IS_SUC)

happen

/'I

Wait

until

something

read

event

flags

request

that

witloOCQIO_EFN

didn’t

completes,

then

cancel

the

pr—————————

complete.

MKT_EFN);

rdaf(efn_buffer);
if

(Cefn_buffer(0]
cmkt(MKT_EFN,

(Cefn_bufferl(0]
qiow(IO_KIL,

MKT_EFN)

QIO_EFN)

dt-»unit,

&dt->iosb,
return

NULL);

NULL,

()

Cancel

timer

{

QIO_EFN,

¢dt->parm)d;

(DT_TIMEOUT);

}

(Cincount
return

fixiosb(dt))

(DT_ERROR);

}
}
A5

Common

(success)

exit

from

all

read

routines

dt->in_end

return

&dt->in_bufflincountl;:

(*dt->in_ptr++

O0xFF);

}
static

int

fixiosb(dt)
register

DECTALK

*dt:

DECtalk

device

B—

—

C PROGRAM EXAMPLE

* This
*

The

routine
is

code

returns

the correct

input

count.

unusual.

——

fixiosb()

returns

the true byte count.
,

{

extern

$$ferr;

int

!= NUL)

if (dt->iosb.terminator

{

Append

the

terminator

dt-»in_buffldt-»>iosb.count]

the

buffer.

= dt->»>iosb.terminator;

dt->iosb.count++;
}

MMNM

(dt_.abort

dt->iosb.status
dt->iosb.count

return

else if

==
==

IE_ABO
0)

{

(0);

(dt->iosb.status

!'=

return (0);
return
}

fendif

(dt->iosb.count);

1/0 error

IS_SUC

&4 dt->iosb.status !'= IS_TMO)
$$ferr = dt->iosb.status;

(emm

/* Read aborted

139

140

C PROGRAM EXAMPLE

DTIOPU.C

—

If the argument character is zero, or output buffer is full, this routine writes
output buffer contents to the DECtalk device. Otherwise, DTIOPU.C stores the

character in a local buffer.

/*)LIBRARY
*/

#ifdef

DOCUMENTATION

title

dt_ioput

index

Write

one

Character

DECtalk

Write

one

character

DECtalk
ea—

Synopsis

#include

<stdio.h>

#include

"dectlk.h"
g

int

dit_ioput(dt,

byte)

DECTALK

*dt;

Device

char

byte;

Character

descriptor
to

*/
A

write

description

the

buffer

argument

character

the

written

full,

the

DECtalk

the

argument

the

output

buffering

the

input

routine

the

output

buffer

The

*"speak"

the

nonzero,

subsequent

pe—————-——w

output
are

before

the

load

data

routine.

attempting

also

the

Note

will

read

flushes

that

flush

any

data.

the
B,

returned.
is
It

DECtalk

reduced.

dt_ioget())

dt_talk(),

stored

transmission.

internally,

significantly

(dt_get(),

routine,

contents

buffer.

dt_ioput()

the

for

characters

system

zero,

buffer

device.

character

buffer

operating

output

the
is

Errors

are

fatal.

operating-system

the

terminal

only

routine

specific
write

output

data

line.
.

—

C PROGRAM EXAMPLE

fendif
#include
#include

#ifdef

“"dectlk.h"
vms

<ssdef.h>
<ciodef.h>

#include
#include

typedef struct io_status_block {
shor t
shor t

int

int
shor t int
shor t

status

1/0

code

status;

terminator;
term_size;

/* Input terminator
/* Terminator size

/* Datum size

term_offset;

int

*/
*/
*/
*/

I0OSTAB

}

fendif
#ifdef

rsx

in RSX specific
cx.h

qiofun.h
qioret.h

Load

information:
common

header

1/0 service function codes

1/0 service error and status codes
Terminal 1/0 service bits and bytles

qiottd.h

<cx.hd>

#include
#include

<qiofun. h>

#include

<qioret. h>

#include

<qiottd. h>

fdefine

QIOD_EFN

1/0

event

flag

fendif
dt_ioput (dt, ¢)
register DECTALK

/* DECtalk

*dt;

device

/* Character

int

to output

* Store the byte (if not E0S). 1f the byte is EOS,
*

or the buffer is full, write it out.

*/
{

#ifdef

int

5ize;}

int

code;

vms

status

IOSTAB

fendif
#ifdef

Yendif
4ifdef

rt11

code;

$$ferr;

rsx

int

code;
$$ferr;

int

fendif

if
#ifdef
felse

rt11

{

*dt->out_ptr++ = (c == ESC) ? (ESC | 0x80) : c;
*dt->out_ptr++

141

142

C PROGRAM EXAMPLE

Yendif

}
size

(Cc

(dt->out_ptr

dt->out_buff);

must

size

QUT_BUFLEN)

/ *

{
e —

write

the

buffer.

*/
if

#ifdef

('dt_abort)

<«

unix

R
if

(write(dt->unit,

dt->out_buff,

size)

-1)

{

perror(dt->device);

exit(1);

}

fendif
#ifdef

wvms

((code

sys$qiow(1,

dt->unit,
IO$_WRITELBLK

Event

flag

Input

channel

IO$M_NOFORMAT,

format

¢status,

NULL,

AST

block

AST

parameter

1/0

status

block

buffer

5ize,

bytes

ignored

carriage

ctl

PS5

ignored

SS$_NORMAL)

0))
!=

dt->out_buff,

{

perror(dt->device);

exit(code);

}
fendif
F—

#ifdef

rt11
if

((code

rs.write(dt->unit,

size,

$$ferr

0))

dt->out_buff,

{

code;

perror(dt->device);

exit(I0O_ERROR);

*endif
#ifdef

rsx
dt->parm.size

dt->parm.buffer
dt->parm.table
if

((code

=
=

dt->out_buff;
NULL;

qiow(IO_WAL,

&dt->iosb,

$$ferr

sjize;

NULL,

v
dt->unit,

&dt->parm))

IS_SUC)

code;

perror(dt->device);

exit(I0_ERROR);

—

QIO_EFN,

|
{
—

fendif

}
dt—)nut_ptr

dt->out_buff;

E—

p—

C PROGRAM EXAMPLE

143

This routine returns TRUE if the telephone user already typed any characters.

/*)LIBRARY
*/

ra—

#ifdef

DOCUMENTATION

title
index

dt_iskey

Test for
Test for

#include
#include

<stdio.h>
“dectlk.h"

type-ahead
type-ahead

synopsis

int

dt.iskey(dt)

DECTALK

r—

*dt;

/* Device descriptor

description

This routine (which may be implemented as a macro)

returns TRUE if any characters have already been
typed by the telephone user, or if an asynchronous
status message (such as timeout) was received.

fendif

<stdio.h>
"dectlk.h*

#include
include
*ifdef
#fundef

dt_iskey
dt_iskey

fendif
int

dt_iskey(dt)

Test

for

*dt;

/* Device descriptor

type-ahead.

return(dt->pend_fc != 0);

"
}

144

C PROGRAM EXAMPLE

DTISTI.C

———

Used to test the result of a dt_phone () message for keypad timeout.
P ——

/*ILIBRARY

*/
#ifdef

DOCUMENTATION

title

dt_istimeout

index

Test

Phone

for

Keypad

Timeout

Test

phone

for

keypad

timeout

Synopsis

#include

<stdio.h>

#include

“dectlk.h"

int

dt_istimeout(dt)
DECTALK

*dt;

Device

implemented

descriptor

description
This

routine

tests
It

the

returns

phone

(which

result
TRUE

may

of
if

with

dt_phone()

the

current

parameter

macro)

message.
is

equal

the
to

DECtalk
R3_PH_TIMEOUT.
[

Yendif
¥include

<stdio.h>

#include

"dectlk.h"

#ifdef

dt_istimeout

#undef

dt_istimeout

#endif
ot
i

int

dt_istimeout(dt)
register

DECTALK

*dt;

Device

descriptor

*/
PO

Test

for

telephone

keypad

timeout.

*/
¢

return

(dt_test(dt,

R2_PHONE,

R3_PH_TIMEOUT)):

}

[

C PROGRAM EXAMPLE

145

DTISVA.C

This routine returns TRUE if the argument character is one of
0123456789#*ABCD.
/*)LIBRARY
.

#ifdef

DOCUMENTATION

title

dt_isvalid

index

Test

for

Test

for

Valid Keypad
valid keypad

Character

character

Synopsis

Yinclude

<stdio.h>

#include

“dectlk.h"

int

dt_isvalid(c)
description

This routine
returns TRUE

(which may be implemented as a macro)
if the argument character is one of

0123456789#*ABCD
fendif

<stdio.h>
“"dectlk.h"

Yinclude
include
#ifdef
#undef

dt_isvalid
dt_isvalid

Yfendif
int

dt_isvalid(c)
char

Cc;3

Test

for

valid pushbutton

key.

{

return

(
il

>»=
==

‘0’
twr

A’

&&
1Y

<=
o=

'9%)
R

‘D’));

146

C PROGRAM EXAMPLE

DTKEYP.C

This routine enables the telephone keypad if the flag is TRUE, and disables the

keypad if it is FALSE.

/*>L1BRARY
*/

mm—————,

#ifdef

DOCUMENTATION

title

dt _keypad

index

Enable

Disable

the

Telephone

Keypad

Enable

Disable

the

Telephone

Keypad

fmmmmmwmmmw

Synopsis

#include

<stdio.h>

#include

“dectlk.h"

int

grom——;

dt _keypad(dt,

flag)

DECTALK

*dt;

Device

int

flag;

TRUE

descriptor

enable

*/
o

description
Enable

the

disable

Returns

TRUE

may

have

telephone

keypad

the

flag

TRUE,

FALSE.
if

been

successful.

hung

FALSE,

the

telephone

up.

Yendif

#include

<stdio.h>

#include

"dectlk.h"

int

dt_keypad(dt,
register

enable)

DECTALK

*dt;

int

enable;

Enable

disable

the

telephone

keypad.

*
Gy

{
dt .phone(dt,

(enable)
if

P3_PH_KEYPAD

(dt_offhook(dt))

return
return

P3_PH_NOKEYPAD,

-1);
e

(TRUE)D;

(FALSE);

C PROGRAM EXAMPLE

147

DTMSG.C

This routine sends a DECtalk DCS control sequence using the p2, p3, and p4
parameters. The r2 and r3 parameters are not checked by the module. A
FALSE reply means an error occurred.

The user may have pressed keypad buttons or a timeout may have occurred.
These values are saved for use by the dt_save routine.
/*JLIBRARY
*/

#ifdef

DOCUMENTATION

title
index

dt_msg

Send a DECtalk Command with Reply
Send a DECtalk command with reply

#include
#include

<stdio.h>
“"dectlk.h"

Synopsis

int

dt_msg(dt,

DECTALK
int
int
int
int

p2,

p3,

*dt;
p2;
p3;
P4;
re;
r3;

int

p4,

r2,

/*
/*
/*
/*
/*

r3)

Device descriptor
P2_xxxx parameter
P3_PH_xxxx parameter
timeout or rings
R2_xxxx parametler

/* R3_xxxx parameter

*/
*/
*/
*/
*/

description

This routine sends a DECtalk DCS control sequence
It then reads
using the p2, p3, and p4 parameters.
a DCS reply from DECtalk, returning TRUE if it matches
the r2 and r3 calling parameters.

1f p2 is -1, no sequence is sent;
is

read and

but a DCS reply

tested.

Note that the Pn and Rn parameters are -1

are not

sent or checked respectively.

Returns TRUE if successful.

if they

|[If FALSE, something is funny.

Note: dt_msg() saves user keypad characters in the type-ahead
buffer.

148

C PROGRAM EXAMPLE

SO,

*endif
#include

<stdio.h>

#include

“dectlk.h"

int
dt-msg(dt,uPE,
register

p3,

p4,

r2,

DECTALK

int

p2,

p3,

int

re,

r3;

r3)

*dt;

Device

p4;

descriptor

parameters

and

Send

Return

DECtalk

DCS

message

and

wait

TRUE

the

proper

was

for

*/
send

parameters

reply.

received.

*/
{

int

code;
L

(p2

{

dt_decs(dt,
code

}

while

return
}‘

—

-1)

p2,

p3,

p4);

dt_read(dt,

60);

(code

(dt_test(dt,

||
r2,

the

sequence

*/
SR,

dt_save(dt,
r3));

Send

code)):
Check

result

*/
B—

[

——

R———

C PROGRAM EXAMPLE

DTOFFH.C

This routine tests the result of a dt_phone () message for OFFHOOK.
/*)LIBRARY
*/

#ifdef

DOCUMENTATION

title
index

dt_offhook

Test Phone Reply for Offhook
Test phone reply for Offhook

#include
#include

<stdio.h>
“"dectlk.h"

Synopsis

int

dt_offhook(dt)

DECTALK

*dt;

/* Device descriptor

description

This routine (which may be implemented as a macro)
is used to test the result of a dt_phone() message.
It returns TRUE if the current reply is the DECtalk
phone reply with the R3 parameter equal to R3_PH_OFFHOOK.
#endif

#include
#include
#ifdef
#undef

¢<stdio.h>
"dectlk.h"
dt_offhook
dt_offhook

fendif
int

dt_offhook(dt)

*dt;

/* Device descriptor

* Test whether

the phone

is off-hook.

{
}

return (dt_test(dt,

R2_PHONE,

R3_PH_OFFHOOK));

149

150

C PROGRAM EXAMPLE

DTONHO.C
This routine tests the result of a dt_phone () message for ONHOOK.
A

/*)L IBRARY
*/

#ifdef

DOCUMENTATION

title

dt _onhook

index

Test

Phone

for

Onhook

Test

phone

for

onhook
L—

Synopsis

#include

<stdio.h>

#include

"dectlk.h"

—

int

dt_onhook(dt)
DECTALK

*dt;

Device

descriptor

description
This

routine

(which

used

test

the

returns

TRUE

phone

with

may

result

the

implemented
of

current

dt_phone()

parameter

equal

macro)

the
to

B
—

message.

DECtalk
R3_PH_ONHOOK.

fendif
Yinclude

<stdio.h>

¥#include

"dectlk.h"

#ifdef

dt_onhook

#undef

dt_onhook

#endif

int
dt_onhook(dt)
register

DECTALK

*dt;

Device

descriptor

/'I"

Test

whether

the

phone

on-hook.

*/
{

return

(dt_test(dt,

R2_PHONE,

R3_PH_ONHOOK));

}

C PROGRAM EXAMPLE

151

DTOPEN.C
This routine performs operating-specific initializations to initiate communica-

tions with a DECtalk device. Operating systems include UNIX, RSX, RSTS/E,
and VMS (either compatibility or native modes).
/*)LIBRARY
*/

#ifdef

DOCUMENTATION

title

dt_open

index

Connect

DECtalk

Terminal

Connect

DECtalk

terminal

Terminal

device

Synopsis

#include

¢<stdio.h>

#include

"dectlk .h"

DECTALK

dt _open(dev)
char

*dev;

name

description

Perform

operating-specific

initiate

(This

communication

routine

devices.)

similar

the

open

else

return

block

that

will

pointer

initializations

with

fopen()

fails,
to

used

failed,

the

DECtalk

for

return

data

for

all

device.

FILE

NULL;

descriptor

other

DECtalk

operations.

the

open

routine

may

called

This

routine

does

For

example,

the

checks
mode,

that
and

not

DECtalk.

opens

DECtalk,

'"square-bracket"

message:

<stdio.h>

#include

"“dectlk.h"

sets

perror()

information.

with

sequence

responding,
a

library

error

communicate

include

main()

following

speaks

DECTALK

standard

*dt;
A

((dt

dt_open("kb2:"))

NULL)

{

perror(*"kb2:");

printf("Can’t

open

DECtalk\n');

}

else

(ldt_initddt))

printf("Can’t
else

initiate

DECtalk\n");

{

dt .decs(dt,

P2_MODE,

dt_talk(dt,

"Hello

MODE_SQUARE,

world.");

dt_sync(dt);
dt_close(dt);
printf("Success.\n");

-1);

152

UNIX

C PROGRAM EXAMPLE

————

notes
This
and

routine
System

Zeus

conditionally

V.,

version

There

UNIX.

UNIX

implementors

this

module

UNIX

and

are

when

System

This

are

for

Ultrix-32

conditional

hasn’t

encouraged

developing
V

compiles

also

been

DECtalk

trademarks

for

(4.2BSD)

the

Zilog

independently

read

and

checked.

understand

applications.
AT&T

Bell

Laboratories.

fendif

#include

¢<stdio. h>

#include

"dectlk . h*

#ifdef

wunix

UNIX

specific

definitions

*/
#include

#include

<errno. h>

fendif
#ifdef

wvms

/®

VMS

native

specific

definitions

#include

<ssdef.h>

Status

#include

Ciodef.h>

1/0

#include

<descrip.h>

String

typedef

struct

dsc$descriptor_s

STRING;

definitions

request

codes

descriptors
string

descriptor

/‘l

The

following

macro

builds

descriptor

from

argument

string.

descrip(text,

((p)->dsc$a_pointer

(p)->dsc$w_length

strlen(text),

T
T

#define

text,

(p)->dsc$b_dtype

DSC$K_DTYPE_T,

(p2->dsc$b_class

DSC$K_CLASS_S)

#endif
#ifdef

rt11

/7 *

RSTS/E

native

specific

definitions

*/
#include

<rsts.h>

Yendif
#ifdef

rsx

#include

<cx.h>

#include

<qiofun.h>

#include

<qioret.h>

#include

<qiottd.h>

#include

#define
static
Yendif

pm—————

<lunbuf.h>

QIO_EFN
QIOPARM

1
noparm;

GI0

parm

(all

zero)

C PROGRAM EXAMPLE

DECTALK

dt_open(name)

/* Device name

*name;

char
/*

Initialize

terminal

the DECtalk

line.

*y
{

#ifdef

DECTALK

int

char

temp

Channel

*tiname;

->»

sgttyb

stty_buffer;

/* Terminal

flags

termio

stty_buffer;

/* Terminal

flags

*ttyname();

/* Get

stdin name

wunix

BSD_42

struct

search,

*dt;

stdin name

¥else

#ifdef

UNIX_V

struct
fendif
fendif

extern char
¥endif

#ifdef

wvms

dev;

STRING
Yendif

#ifdef

rti1

work[301;

char
extern

$$rstis;

int

extern char
extern char
extern char

*ES$SNOD;
*E$SFAT;
*ES$SS$SNOC;

Invalid device

/*
/*

Fatal error
No more channels

*/
*/

/* TRUE if RSTS/E
/* TRUE if P/0S
/* Dir. status word
/* DECUS C error value
/* Get lun information

*/
*/
*/
*/
*/

fendif
¥ifdef

rsx

extern
extern
extern
extern
struct

int
int
int
int
lunbuf

$$rsts;
$$pos;
$dsw;
$$ferr;
lunbuf;

extern
extern

char
char

*calloc();

Yendif

*malloc();

/‘!

*
*

Allocate the DECtalk buffer and
device name (for debugging).

save

the

if ((dt = (DECTALK *)calloc(sizeof (DECTALK),
return

(NULL);

((dt->device
goto

= malloc(strlen(name)

errore;

strcpy(dt->device,

name)

1))

1)) == NULL)
NULL)

153

154

¥ifdef

C PROGRAM EXAMPLE

—

unix

(Cttname

dt->unit

else
if

ttyname(fileno(stdin)))

strcmp(titname,

name)

fileno(stdin);

((dt->unit

goto

errori;

open(name,

(lisatty(dt->unitd)

NULL

2))

stdin

S A5,

close(dt->unit);

goto

error1;

}
‘f*

Force

the

terminal

into

single-character,

no-echo

mode.
RSO

*/
#ifdef

BSD_42
gtty(dt->unit,

&stty_buffer)d;

Get

current

info

gtty(dt->unit,

&dt->stty_saved;

For

restore,

too

echo

character

5tty-buffer.3gmflags

~ECHO;

Set

5tty,buffer.mg_flags

CBREAK;

Single

Set

Ignore

stty(dt->unit,

&stty_buffer);

signal(SIGALRM,

SIG_IGN);

temp.

mode

timer

signals

¥else

#ifdef

UNIX_V
ioctl(dt->unit,

TCGETA,

&stty_buffer);

Get

current

info

ioctl(dt->unit,

TCGETA,

¢dt->stty_saved;/*

For

restore,

too

stty_buffer.c_iflag

BRKINT

stty_buffer.c_oflag

stty_buffer.c_cflag

B9600

{

IXON

CS8

{

simpssmes Sy

#jifdef

IXOFF;

CREAD

CLOCAL;

zeus
/*

The

"Zeus"

following
port

edit

but

was

hasn’t

reported
been

customer

independently

for

Zilog

tested.

stty_buffer.c_lflag

0101;

stty_buffer.c_lflag

felse
Yendif
stty_-buffer.c_ccl[VMIN]

pm—o

stty_buffer.c_ccIVTIME]

ioctl(dt->unit,

&stiy_buffer);

TCSETA,

Set

temp.

mode

Yendif

¥endif

¥endif
#ifdef

vims

descrip(name,
if

&dev);

(sys$assign(&dev,
goto

&dt->unit,

NULL)

SS$_NORMAL)

errori;

popm—————,

C PROGRAM EXAMPLE

fendif
#ifdef

rt11

(V$8$rsts)

GES$SFAT;

(int)

$$ferr

function

Illegal

errori;

goto
}

/l*

free channel.

for

125

>»

{

i--)

clrxrb();

xrb.xrci

(rstsys(_POSTN)

NOTOPN)

break;
}

if (i

if all

/* Fail

<= 0)

$$ferr

(int)

&ES$S$SNOC;

channels

use.

are

Save unit

*/
*/

errori;

goto
}

dt->»unit

number

/fl*

*
*

16
32

special mode:

in a

do not abort on CTRL-C or modem hangup
terminal service handles XOFF/XON

“Ys/mo:%d",

(rs_open(i,
goto

opened

binary

sprintf(work,
if

terminal

the

* On RSTS,

work,

)

name,

1+16+32);

errori;

((firgb.fqflag & OxFF) !'= TTYHND) A
/* Not
$$ferr = (int) GE$SNOD;

terminal

rs_.close(i);
goto

errori;

}

fendif
#ifdef

rsx

($$rsts)

$$ferr
goto

/* Not on RSTS/E

IE_IFC;

errori;

}
/'lr

fopen()

* We only call

to get a free

if ((dt->fildes = fopen(name,
goto

dt->»unit

== NULL)

errori;

fileno(dt->fildes);

glun(dt->unit,
if

"rn"))

lun.

&lunbuf);

($$pos

lunbuf.g-lunal0]
lunbuf.g-lunal1]l

&&
&%

==
==

dt-»>pos_xk

TRUE;

dt-»>pos_xk

FALSE;

“X’
‘K’)

else

(€i

= qiow(IO_ATT, dt->unit, QIO_EFN,
NULL, NULL, &noparm)) !'= IS_SUC)

fclose(dt->fildes);
$$ferr

goto

errori;

{

155

156

C PROGRAM EXAMPLE

fendif
/’l

Normal

exit,

initialize

other

pointers

*/
dt->1link

dt_root

dt_.root;

dt;

dt->out_ptr
dt->flag
return

dt->out_buff;

_FLAG_SPEAK;

(dt);

Out

Normally

Normal

exit

free

device

DECTALK

buffer

errorl:

free(dt->device);

Error,

error2:

free((char

and

Error

return
}

dt);

((DECTALK

*)NULL);

setup

speaking

exit

*/
*/
*/
*/

r——_

———

——_5_

C PROGRAM EXAMPLE

DTPEEK.C

157

This routine tests if a character is pending from DECtalk. The character may be
a keypad character (user selected) or part of an escape sequence.
/*J)LIBRARY
*/

#ifdef

DOCUMENTATION

title
index

dt_peek

Test if Character Available from DECtalk
Test if character available from DECtalk

#include
#include

<stdio.h>
“"dectlk.h"

synopsis

int

dt_peek(dt)

DECTALK

*dt

/* Device descriptor

description

Returns TRUE if a character is pending from DECtalk.
Note that this may be a keypad input character (as
entered by the user) or part of an escape sequence.

dt_peek() does not flush pending output.

It contains

operating-system specific code.
note

This module contains specific code for UNIX
The makefile for the library should
4.2BSD.
#define BSD_42.
bugs

Tested only on VMS.
fendif

<stdio.h>

#include

“dectlk.h"

#include
/*

* Define all DECtalk library globals in this module.

#ifdef

unix

<errno.h>

#include
#ifdef

#include
#include
fendif

BSD_42

158

C PROGRAM EXAMPLE

P-

int

ORIy,

dt _peek( dt,
register

sec)

DECTALK

*dt:

DECtalk

device

UNIX.

{
register

#ifdef

int

incount:

Count

pending;

Number

ecode;

For

errno;

System

BSD_42
auto

error

code

*/
ATt

long

felse
register

extern

and

int

¥endif

pending

error

handling

error

value

*/
*/

Anything

buffered?

(dt->pend_fc
return

#ifdef

dt->in_ptr

dt->in_end)

(TRUE);

BSD_42
/*

Works

for

Won’t

work

4.1

BSD,

for

too.

Unix

System

*/
ioctl(dt->unit,
return(pending

FIONREAD,
>

&pending);

0);

felse

dit->in_ptr

dt~>in“end

&dt->in_buffl01;

alarm(1);
errno

incount

ecode

errno;

read(dt-»unit,

Cincount

return
if

dt->»>in_end
return

ecode

(FALSE);

(dt_abort
return

incount

(FALSE);

Start

timeout

Clear

error

dt->in_buff,

alarm(0);
==

IN_BUFLEN):

Save

Cancel

EINTR)

Return

flag

————

error

code

timeout

Did

timeout?

failure

*/
*/
*/

Other

error?

Return

bad

&dt->in_bufflincountl;

failure

(TRUE);

fendif

}
fendif
#ifdef

vms

#include

#include
typedef

}

QUSRO;

<ssdef.h>

<iodef.h>
struct

io_status_block

System

1/0

request

status

codes

code

{

shor t

int

status;

shor t

int

1/0

term_offset;

Datum

size
terminator

shor t

int

terminator;

shor t

int

Input

term_size;

Terminator

I0STAB;

size

GO,

®/
i

C PROGRAM EXAMPLE

159

int

dt_peek(dt)

*dt;

/* DECtalk device

buffer,

too.

/'l

Fill

YVMS:

the

input

*/
{

incount;
int
struct type_ahead {
pending_cuunt;
short
first_character;
char

}

char

char_reserved;

int

long_reserved;

type_ahead;

if (dt->pend_fc
return

incount

(TRUE);

= sys$qiow(1,

1/0 status block

status;

I0STAB

dt->in_ptr

< dt->in_end)

/* Event flag

*/
/* Input channel
dt->unit,
IOSM_TYPEAHDCNT,
I10$ _SENSEMODE
*/
/* 1/0 status block
¢status,
*/
/* AST block (none)d
NULL,
*/
/* AST parameter
0,
*/
/* P1 - buffer
¢type_.ahead,
*/
sizeof type_ahead, /* P2 - buffer length
*/
/* P3 0,
*/
/* P4 NULL,
/* PS - ignored (prompt buffer) */
NULL,
*/
/* P6 - ignored (prompt size)
0);

return Cincount

== SS$_NORMAL && type_ahead.pending_count

}

fendif

#ifdef

rti11

/fi

RSTS/E

Krsts.h>

#include
int

dt_peek(dt)

ragister

DECTALK

*dt

DECtalk

device

> 0);

160

C PROGRAM EXAMPLE

—

/*
*

RSTS/E:

Fill

the

input

buffer,

return

the

(first)

character.

{

incount;

(dt->pend_fc
return

/* Count and error code */

dt->in_ptr

dt->in_end)

(TRUE);

must

refill

the

buffer

dt->in_ptr

dt->in_end

&dt->in_buffl0];

clrxrb();

xrb.xrlen
xrb.xrci

=
=

dt->unit

xrb.xrblkm

delimiter

‘

TTYHND;:

rstsys(_SPEC);

clrxrb();

xrb.xrlen

xrb.xrci

dt->unit

xrb.xrblkm

echo

TTYHND;

premmn,

rstsys(_SPEC);

incount

rs_read(dt->unit,

INLBUFLEN,

C(incount
return

else

dt->in_end

dt->in_buff,

8192);

-(HNGTTY))

(FALSE);

(incount

return

(FALSE);

&dt->in_bufflincountl;

"
§

(TRUE):

}
Yendif
o,

#ifdef

rsx

Load

RSX

specific

information:

cx.h

common

qiofun.h

I/0

service

function

service

error

header

gioret.h

[/0

qiottd.h

Terminal

lunbuf.h

Device

#include

I/0

codes

and

service

status
bits

characteristics

and

codes
bytes

buffer

<cx.h>

#include

<qiofun.h>

#include

<qioret.h>

#include

<qiottd.h>

#include

<lunbuf.h>

#define

QIO_EFN

1/0

#define

MKT_EFN

Time

get

static

char

gmcbufl2]

{

static

QIOPARM

gmcparm

{

gmcbuf,

static

int

termtablel161];

TC_TBF

};

sizeof
/*

event
event

flag
flag

typeahead

gmcbuf

*/
count

*/
*/

};

Terminator

1
bitmask

C PROGRAM EXAMPLE

int

dt_peek(dt)

*dt;

/* DECtalk

device

Count and error code
To copy to rsx buff

*/
*/

J *

RSX:

*/
{

int
char

incount;
*ips

/*
/*

errorcode;

int
/*

(if

Return buffered character

any)

(dt->pend_fc
return

dt->in_ptr

dt->in_end)

(TRUE);

l‘l

must

*y/

dt->in_ptr
if

the

refill

buffer

= dt->in_end = &dt->in_buffl(01;
o

(dt->pos_xk)
/*l

The PRO-350

dt->parm.buffer
=

dt->parm.size

XK:

port

&¢dt->»iosb,
(Cincount =
return

actually pretty simple.

= dt->in_buff;
IN_BUFLEN;

dt->parm.p3 = 0;
errorcode = qiow(IO_RLB
if

{

TF_TMO,

&dt->parm);
fixiosb(dt)) == 0)

/* No timeout
*/
dt->unit, QIO_EFN,

NULL,

{

(FALSE);

}

dt->in_end
return

&dt->in_.bufflincountl;

(TRUE);

}

else

|
/*

*
*

Check whether anything is
system type-ahead buffer.

the

errorcode = qiow(SFmGMC, dt->»unit, QIO_EFN,
¢dt->iosb, NULL,
return (errorcode ==
}

&gmcparm);
IS_SUC && gmcbufl1]

0);

161

162

C PROGRAM EXAMPLE

static

int

fixiosb(dt)
register

DECTALK

*dt;

DECtalk

device

This

The

routine
code

returns

the

correct

input

count.

unusual.

fixiosb()

returns

the

true

byte

count.

{

extern
if

int

$$ferr;

(dt->iosb.terminator

NUL)

{

—

Append

the

terminator

the

buffer.

——

dt->in_buffldt->iosb.count]

dt->iosb.terminator;

dt->iosb.count++;

}
if

(dt_abort

—

dt->iosb.status

dt->iosb.count
return

else

if
&4

IE_ABO

(0);

(dt->iosb.status

1S5_SUC

dt->iosb.status

IS_TMO)

$$ferr

return

(0);

Read

1/0

aborted

{

dt->iosb.status;

}
return

{

(dt->iosb.count);

error

—

|
‘

}
#endif

ST,

C PROGRAM EXAMPLE

163

DTPESC.C

This routine compiles an appropriate escape sequence from the parameter
buffer.

/*)LIBRARY
*/

#ifdef

DOCUMENTATION

title

dt_pesc

Transmit

Escape Sequence

Transmit

escape

#include
#include

<stdio.h>
“dectlk.h"

index

sequence

5yNOpsis

dt_pesc(dt, seq)

wmm@

DECTALK

?MWM

*dt;

*seq;

SEQUENCE

/* Device descriptor
/* What

to transmit

description
Compile an appropriate escape

sequence from the

This is similar to putchar()
parameter buffer.
In
except when seq->state is ESC, CSI, or DCS.
these cases, the function generates an appropriate

p—
P
|

sequence from the passed data structure.
calls

the user-supplied dt_put()

dt_pesc(O)

to output each

character.

C1 control sequences are sent in their eight-bit
If
form if _FLAG_EIGHTBIT is set in dt->flag.
this bit is off, they are sent in their <ESC>X
If the application program sets _FLAG_EIGHTBIT
form.
it must also ensure that the operating system
transmits eight data bits, and that DECtalk

was setup as HOST FORMAT EIGHT.

No value

?MMM

#endif

returned.

164

C PROGRAM EXAMPLE

#include

<stdio.h>

#include

“"dectlk.h"

dt_pesc(dt,

—

seq)

DECTALK

*dt;

Dectalk

SEQUENCE

*seq;

Sequence

device

buffer

Output

the

character

(in

seq->state)

and

maybe

sequence,

too.

{
register

unsigned

#ifdef

Index

max;

Max

into

for

interl],

interl]

and

param(]l.

*/
p

]

—

DT_DEBUG
if

(dt_debug)

{

printf(put:

\"");

(isatty(fileno(stdout)))
fflush(stdout);

}

fendif
i

seq->state;

((dt->flag

NSRS
255,

_FLAG_EIGHTBIT)

0x80

Output

0x9F)

{

/'l

7-bit

control

mode

and

character.

the

character

Convert

it.

*/
dt _put(dt,

ESC);

dt_put(dt,

0x40);

}

else

{
/'Ir

Not

the

special

case;

output

the

character.

Ao,

*/
dt _put(dt,

i);

}

switch

case

(i)

ESC:

case

CSI:

case

DCS:
/*
OSSO,

Here

sequence.

Output

all

its

components.

First,

the

parameters.

counts

the

parameters

max

stores

the

parameter

wval

working

copy

max.

parameter

value.

*/
if

(seq->private

dt_put(dt,

seq-»>private)d;

max

(max

SEQ_PARMAX)

max

SEQ_PARMAX;

for

seq->paraml0];

max;

dt_putCdt,
if

Too

{

“;7);

(seq->paraml(il]
intout(dt,

/*
i++)

!'=

seq->paramlil);

many,

use

limit

C PROGRAM EXAMPLE

165

*
*

OQutput
i

max

intermediates.
counts intermediates.

the number

stores

to output.

max = seq->inter(01];
if (max > SEQ_INTMAX)

max

/* Too many,

SEQ_INTMAX;

use

limit

(i = 13 i <= max;) {
dt_putddt, seq->inter(i++1);

for
}

dt_put(dt,

/* Output

seq->final);

the final

break;

default:
break;
}

DT_DEBUG
if (dt_debug)

#ifdef

printf(*\"\n");
#fendif
}

#ifndef

INT_32

#ifdef

vax

#define

INT_32

fendif

#ifdef

M8000

fdefine

INT_32

fendif
fendif

static

unsigned power10(]

Powers

for

intout

INT_32

#ifdef

10000000,
1000000,

100000,
#endif
10000,
1000,

100,
10,

1,
}s

#define NPOWERS ((sizeof power10) /

(sizeof (unsigned)))

static

intout(dt,

wvalue)

DECTALK
register unsigned

*dt;
value;

/* DECtalk device
/* Value to convert

* Convert an unsigned number
*

each character.

does

not

output

Note,

anything.

to ASCII

and call dt_put() on

implemented here,

zero value

*/
*/

166

C PROGRAM EXAMPLE

{

—

unsigned

*power;

int

out_.char;

int

nonzero;

power

nonzero

power10;

Pointer

Don’t

FALSE:

power

output

table

leading

zeros

*/
*/

{
/l'

Loop

until

all

have

been

done.

places

except

digits

place

for

(out_char
value

0:;

value

»=

*power;

(nonzero

nonzero

out_char

*power;
/*

TRUE;

power

zZero

{
/*

out_char++)

Subtract
Not

dt_put(dt,

out_char

“0’);

(++power

&power 10[NPOWERSI1);

leading

(R,

}
}

while

}

e Sasesnt
iy

B ——

oy,

A5,

C PROGRAM EXAMPLE

DTPHON.C

This routine sends a DECtalk phone message.

/*)LIBRARY
*/

#ifdef

DOCUMENTATION

title

dt_.phone

Send a Phone Message

#include
#include

<stdio.h>
“"dectlk.h"

Send a phone message

index
Synopsis

int

dt_phone(dt,

p3,

DECTALK
int
int

p4)

*dt;
p3;
p4;

*/
/* Device descriptor
/* P3.PH_xxxx parameter */
*/
/* timeout or rings

description

This routine (which may be implemented as a macro)
sends a DECtalk phone message (i.e., the p2 parameter
is

P2_PHONE).

p3 and p4 should be given as -1
be

sent.

then reads

the r1

R2_PHONE

if no parameter

the status reply and returns TRUE

and r2 parameters are R1_DECTALK and

respectively.

The application program

should then test for offhook/onhook as appropriate.

Returns TRUE if successful.

[If FALSE,

something is funny.

fendif

¢stdio.h>
"dectlk.h"

#include
#include
#ifdef

dt_phone

#undef

dt_phone

#endif
int

dt_phone(dt,

p3,

p4)

int
int

*dt;

/* Device descriptor

p3;
p4;

/‘l

Send

phone message.

{
}‘

return (dt_msg(dt,

P2_PHONE, p3,

p4,

R2_PHONE,

-1));

167

168

C PROGRAM EXAMPLE

DTPTES .C

This routine tests a phone reply.

/*ILIBRARY
*/
#ifdef

DOCUMENTATION

title

dt_ptest

index

Test

Phone

Test

phone

Synopsis

#include

<stdio.h>

#include

“dectlk.h"

int

dt_ptest(dt,

r3)
A0

DECTALK

*dt;

Device

int

r3;

R3_PH_xxxx

descriptor

parameter

description
i

This
is

The

routine

used

C(which may be

test

parameter

returns

phone

result

R3_PH_...

TRUE

implemented

the

with

the

dt_phone()

macro)

message.

current

specified

value.
reply is a

DECtalk

—

parameter.

Yendif
A,

#include

<stdio.h>

#include

"dectlk.h"

#ifdef

dt_ptest

¥undef

dt_ptest

Yendif
int

di_ptest (dt,

r3)

DECTALK

ragister

*dt:

int

Device

descriptor

r3:;
[—

Test

phone

message.

*y/

{
return

(dt_test(dt,

R2_PHONE,

r3));

}‘

C PROGRAM EXAMPLE

169

This routine sends one character to the DECtalk terminal line. No value is
returned.

/*)LIBRARY
*/

#ifdef

DOCUMENTATION

title
index

dt_put

to DECtalk
Write one Character
Write one character to DECtalk

Synopsis

#include

P
4

DECTALK
int

¢<stdio.h>
“"dectlk.h"

#include
dt_putCdt,

)

*dt;
c

/* Device descriptor
/* Character to write

*/
*/

description

One character is written to the DECtalk terminal line.
is

No value

returned.

If DT_DEBUG is #defined when the library is compiled

and the global dt_debug is set nonzero (by the
application program), the charactler
written is logged to the standard output device.
Yendif

¢stdio.h>
"dectlk.h"

#finclude
#include
#ifdef

di_put

#undef

dt_put

#endif

dt_put(dt,

*dt;
c;

/* Device descriptor
/* Character to write

{

extern

g T

int

dt .debug;

dit-ioputldt, c);
#ifdef

DT.DEBUG

if (dt_debug

!= 0)

dt_dchar(c,
fendif
}

stdout);

*/
*/

170

C PROGRAM EXAMPLE

DTREAD.C

This routine reads a sequence or character.
),

/*ILIBRARY
*/

#ifdef

DOCUMENTATION

title

dt_read

index

Read

Sequence

Character

Read

sequence

character

Synopsis

#include

<stdio.h>

#include

"dectlk.h"

int
dt_read(dt,

DECTALK

*dt;

Device

char

5ecC;

0.5.

sequence

keypad

between

the

DECtalk

descriptor

timeout

value

description
A

Read
any

characters

string

the

escape

terminator.

sequence

Return

the

character.
final

character

Ignore

and

the

read

introducer.

#endif
#include

<stdio.h)>

#include

"“*dectlk.h"

int

dt_.read(dt,
register

sec)

DECTALK

int

*dt;

Dectalk

sec;

Operating

device

{

int

code;

int

%
*k

Copy

Note,

escape

properly

inside

escape

sequences

operating

system

cannot

Read

another
the

sequence

this

code

sequence

deal

(or

into

not

quite

parsing.

with

continue

read

the

reading

working

general

enough

Specifically,

control

characters

(as

process

for

one),

buffer.
all

cannot

embedded

necessary

XOFF/XON

this

"reply"

ARy

the

controls).

timeout

system

C PROGRAM EXAMPLE

dt->seq.state =
ugain:

dt->reply.state = code = di_gesc(dt, sec);
switch (code)
case CAN:
case

{

SUB:
goto

again;

case ESC:
case CSI:
case DCS:

dt->reply.final = dt->seq.final;
dt->reply.private = dt->seq.private;

for (i = 0; 1 <= dt~)ueq.inter[01; ++i)
dt->reply.interli]l = dt->seq.interli];
for (i = 0; 1 <= dt->seq.paraml0]; ++1)
dt->reply.paramli] = dt->seq.paramlil;

break;

default:

dt->reply.final = dt->reply.private =
dt->reply.interl0] = dt->reply.paraml0] = 0;
break;

}

if (dt->reply.state == DCS) {
/"Ir

* Ignore text between DCS final and ST
*/

dt->seq.state
do

{

code

= dt_gesc(dt,

1);

} while Ccode » 0 && code < 0x80);
}

return (dt->reply.stated;

171

172

C PROGRAM EXAMPLE

DTRESE.C

This routine sends a soft-reset escape sequence.

/*ILIBRARY

*/
#ifdef

DOCUMENTATION

title

dt_reset

index

DECtalk

Soft

Reset

DECtalk

soft

reset

Synopsis

include

<stdio.h>

#include

“"dectlk.h"

dt _reset(dt)

DECTALK

*dt:

Device

descriptor

*/
L

—

description

Send
No

"soft

errors

are

reset"

escape

sequence.

possible.

*endif

#include

<stdio.h>

#include

"dectlk.h"

static

SEQUENCE

cs1,

‘p’,

soft_reset
{

0},

{

[

=
1,

{
*1v7

di_reset(dt)
register

ROy,

DECTALK

*dt;

I *

dit_reset()

sends

soft-reset

escape

sequence.
J—————————

{

dt_pesc(dt,

&soft_reset);

dt->flag

_FLAG_SPEAK;

dt->timeout

Speaking

now

timeout

now

*/
*/

C PROGRAM EXAMPLE

DTSAVE.C
This routine saves user type-ahead characters.

—
b

/*)LIBRARY
*/

#ifdef

DOCUMENTATION

title
index

dt_.save

Save User Type-ahead
Save user type-ahead

#include
#include

<stdio.h>
“dectlk.h"

Synopsis

int

dt_save(dt,

DECTALK
char

*dt;
cs

/* Device descriptor
/* Character to save

description

I1f ¢ is a keypad character, save it in the
type-ahead buffer and return TRUE, else return
FALSE.

I1f the current reply is a timeout and nothing
is stored in the type-ahead buffer, save ‘T’

This is necessary
and clear the timeout flag.
as a timeout sequence may be returned in
the middle of a message/reply sequence.

This routine should not be called by application
programs.

fendif

—
7
.

#include
#include

<stdio.h>
“"dectlk.h"

v/
*/

173

174

C PROGRAM EXAMPLE

int

dt_save(dt,
register

DECTALK

int

*dt;

Dectalk

Character

device
to

int

timeout;

(Ydt_isvalid(c))
if

{

(!dt_istimeout(di))
return

else

(FALSE):

{

test

{
/*

Current

value

Not

keypad

button?

isn’t

timeout,

it’s

Timeout

not

for

us.

funny

/*l‘

* Ignore timeout if timer

the

type-ahead

Get

old

Clear

something

already

*/
*/

set

zero

RGO,

buffer.

*/
timeout

dt->timeout;

dt->timeout

C(timeout
return

*/
*/

dt_iskey(dt))

(TRUE);

'T’;

}

Toss

away

Save

typeahead

}

value

timer

A
i

(dt->pend_fc

PEND_SIZE)

{

dt->pend_fc++;
di->pendldt->pend_fpl

(++dt->pend_fp

dt->pend_fp

¢;

Save

enough

throw

there’s

room,

else

away.

*/
*/

PEND_SIZE)

}
return

(TRUE):

—

C PROGRAM EXAMPLE

DTSPLICE.C

This routine lets you control a terminal connected to DECtalk’s local port.
/*)LIBRARY
*/

#ifdef

DOCUMENTATION

title
index

dt_splice

Manage Local Terminal
Manage Local Terminal

#include
#include

<stdio.h>
"dectlk.h"

Synopsis

dt.splice(dt,

DECTALK
int

flag)

/* Device descriptor
/* Required state

*dt;
flag;

*/
*/

description

dt_splice() allows control over a terminal
Note that
connected to DECtalk’s local port.
the terminal must correctly process ANSI escape
Specifically, it must ignore any
sequences.
escape sequence that it doesn’t understand.

The flag parameter may have
(bit-encoded)

the following

values.

SPLICE.SPEAK

Speak

SPLICE_.LOG

Text

if
if

subsequent

to DECtalk

sent

(in raw mode) to
terminal if set.

not

text
zero.

is sent

the local
Initially

set.

Text

SPLICE_TERM

text,

not speak
Initially

Do
set.
not set.

typed on the

local

terminal is sent to DECtalk
if set. Initially not set.

The bits would normally be set and cleared in combination.
For

example:

dt_splice(dt,

Speak

text, don’t

dt_splice(dt,

SPLICE_SPEAK);

log it,

SPLICE_LOG

Stop speaking text,
terminal.

ignore text typed on the host.
i

SPLICE_TERM);

transmit text from/to the attached

175

176

C PROGRAM EXAMPLE

fendif

#include

<stdio.h>

#include

"dectlk.h"

di_splice(dt,

flag)

DECTALK

*dt;

int

flag;

i
TR,

Manage

line-splice

modes.

{

splice(dt,

flag

SPLICE_SPEAK,

_FLAG.SPEAK,

P2_SPEAK,
splice(dt,

flag

SPLICE_LOG,

~-FLAG_LOG,

P2_L0G,
splice(dt,

flag

1);

LOG_-RAWHOST);

SPLICE_TERM,

_FLAG_TERM,

P2_TERMINAL,

}

TERM_HOST);

static

splice(dt,
register

flag,

bit,

p2,

DECTALK

*dt;

int

flag;

TRUE

int

bit;

dt->flag

For

int

p2,

p3;

work.

/-l

send

the

dt_splice()

the

—

p3)

appropriate

dt->flag

set

bit

DCS

doesn’t

agree

with

dt_dcs().

flag,
AR

{
if

(((dt->flag
if

(flag

!'=

dt->flag

bit)
0)
iI=

{
bit;

dt_dcs(dt
p2,
, p3,

-1);

(flag

{

dt->flag

dt_decs(dt,
}

~bit;
p2,

-1);

0))

{

Turn

Set

Sends

the

p2/p3

mode

off,

}
else

mode
flag

on,
bit

and

“
Turn

Clear

flag

bit

Send

"mode

off"

*/
*/

and

*/
*/

,
L

SRS,

C PROGRAM EXAMPLE

DTST.C

177

This routine sends a string terminator to DECtalk. This string terminates phonemic text or telephone dial commands.

/*)LIBRARY
*/

#ifdef

DOCUMENTATION

title

dt_.st

Send'Strlng‘Tarminatur

#include
#include

<stdio.h>
“"dectlk.h"

index

Send String Terminator

synopsis

int

dt_st(dt)

*dt;

DECTALK

/* Device descriptor

description

This routine sends a string terminator to DECtalk.
This is needed to terminate phonemic text or telephone
dial

commands.

A phonemic

text sequence would be sent as follows.

dt_cmd(dt,

dt_talk(dt,

p2,

p3);

"hh’ehlow.");

dt_st(dt);
fendif

¢<stdio.h>
“dectlk.h"

#include
finclude

static SEQUENCE string-terminator

{

s
dt_st(dt)

*dt;

DECTALK
/*

Send a

string

terminator

{

dt_pesc(dt,
}

&string_terminator);

/* Device descriptor

178

C PROGRAM EXAMPLE

NSO

DTSYNC.C

This routine synchronizes the application with DECtalk.
O

/*)LIBRARY
*/

#ifdef

DOCUMENTATION

title

dt_sync

index

Synchronize

with

DECtalk

Synchronize

with

DECtalk

Synopsis

|
#include

<stdio.h>

#include

“"dectlk.h"

int

dt_sync(dt)
DECTALK

*dt;

Device

descriptor

description
The

program

has

been

Returns

delays

until

all

text

sent

DECtalk

spoken.

TRUE

successful.

FALSE,

something

funny.

Yendif

#include

<stdio.h>

#include

“"dectlk.h"

int

dt_sync(dt)
register

DECTALK

*dt;

Device

descriptor

/'l»

Synchronize

DECtalk

and

the

P2_SYNC,

-1,

application.

*/
{
dt_.des(dt,

dit->flag
return

-1);

_FLAG_.SPEAK;

(dt_msg(dt,

P2_IX_QGUERY,

Synchronize

Now

-1,

speaking
R2_IX_QUERY,

-1));

C PROGRAM EXAMPLE

DTTALK.C

This routine speaks one line of text.

/*)LIBRARY
*/

#ifdef

DOCUMENTATION

title
index

dt_-talk

Speak One Line of Text
Speak one line of text

#include
#include

<stdio.h>
“dectlk.h"

synopsis

dt.talk(dt,

text)

*dt;
*text;

DECTALK
char

/* Device descriptor
/* What to say

*/
*/

description

This function sends a line of
dt_talk(dt,

flushes DECtalk

NULL)

a vertical-tab

text

to DECtalk.
by sending

sequence.

#endif

#include
#include

<stdio.h>
"“"dectlk.h"

static char

vtlinell

dt_talk(dt,

text)

{ VT,

*dt;
*text;

{

== NULL)
= vtline;
(*text '= 0)

(text
text

while
dt_put(dt,

dt_eol(dt);

*text++);

};

/* Device descriptor
/* Text pointer

*/
*/

179

180

C PROGRAM EXAMPLE

DTTEST.C
This routine tests a DECtalk reply.

/*)LIBRARY
*/

#ifdef

DOCUMENTATION

title

di_test

index

Test
a DECtalk

Test

DECtalk

Synopsis

#include

<stdio.h>

#include

“"dectlk.h"

——

AORry,

int

dt_test(dt,

r2,

r3)

DECTALK

*dt;

Device

descriptor

int

re;

R2_xxx

parameter

int

r3;

R3.xxx

parameter

description

This

routine

DECtalk
It

checks

against

returns

DECtalk

TRUE

the

the
if

last

model.
the

sequence,

reply
or

FALSE

received

-1

properly
on

any

from

ignore

it.
A

parsed

failure.

fendif
g,

#include

<stdio.h>

#include

“"dectlk.h"

int

dt_test(dt,
register

r2,

r3)

DECTALK

*dt;

int

re;

int

r3;

Device

descriptor

/I‘

Test

DECtalk

the

current

reply.

returned

sequence

-1

ignore

(dt->reply.state

DCS

for

the

proper

it.

*/
{

di-d>reply.final

dt->reply.interl0]

dt->reply.private
if

DCS_F_DECTALK
==

{

(dt->reply.param(1]

R1_DECTALK

dt->reply.paraml[2]

&¢

(r3

return

}
return

(FALSE);

-1

dt->reply.param[3]

(TRUE);

r3))

GO,

C PROGRAM EXAMPLE

DTTIME.C

This routine enables or disables telephone keypad timeout.
/*)LIBRARY
*/

#ifdef

DOCUMENTATION

title
index

dt_timeout

Enable or Disable Keypad Timeout
Enable or disable keypad timeout

#include
#include

<stdio.h>
“"dectlk.h"

5ynopsis

int

dt_timeout(dt,

DECTALK
int

sec)

*dt;
sec;

/* Device descriptor
/* Timeout in seconds

*/
*/

description

1f sec is nonzero, timeouts are being enabled;
if zero,

they are being disabled.

Enable keypad timeouts if sec is nonzero and there
is no data in the type-ahead buffer (and timeouts
are not already enabled).

Disable timeouts if they are enabled and sec is zero,

or any data is in the type-ahead buffer (even if
sec

nonzero)d.

Before enabling timeouts, DECtalk is synchronized.

%“ ;

Returns TRUE if successful.

If FALSE, the telephone

may have been hung up.

)

#endif
¢<stdio.h>

#include

"dectlk.h"

#include

int

dt_timeout(dt,

sec)

*dt;

sec;

/* Device descriptor

/* Timeout in sec seconds

181

182

C PROGRAM EXAMPLE

Enable
Note

disable

that

type-ahead

timeouts

timeout.

timeout(dt,
buffer

on,

(sec
if
if

before

off,

15)

errors

looks

deciding

are

the

possible.

state

whether

nothing.

{

1If

(dt_iskey(dt))

Disable

sec

(sec

the

turn

enabling,

typeahead

{

Still

dt _sync(dt);

Synchronize

Check

Don’t

set

same

value

(di_iskey(dt ))
sec

enabling?
and

again.

*/
*/

}

}
if

(dt->timeout
return

dt_phone(dt,

dt->timeout
if

P3_PH_TIMEOUT,

return

the

sec):

sec;

(dt_onhook(dt)
return

sec)

(TRUE):;

dt -offhook(dt))

(TRUE);

(FALSE);

SR,

C PROGRAM EXAMPLE

DTTONE.C

This routine sends the msg test string as a tone dialing sequence.

#ifdef

DOCUMENTATION

title

dt_tone

Send DTMF Tones

#include
#include

<stdio.h>»
"dectlk.h"

index

Send DTMF

tones

Synopsis

int

dt_tone(dt,

DECTALK
char

msg)

*dt;
*msg;

/* Device descriptor
/* Announcement

*/
*/

description

This routine sends the msg text string as a tone
If the telephone was on-hook
dialing sequence.
when dttone() was called, it will be returned
Note, this routine
to the on-hook condition.
may not work to your satisfaction in countries
which require automatic announcement messages

on automatically dialed calls.
‘s manual
programmer

for more

See your DECtalk

information.

For message text may contain any valid touch-tone
characters (*"0123456789*#ABCD") or the characters

*14 (for a one second delay) or the ‘"’ for a 250

millisecond switch-hook flash. All other characters
are

ignored.

Note that the telephone will not be hung up before
dialing if it is offhook when the command is issued.
fendif

#include
#include

<stdio.h>
- Y"dectlk.h"

int

dt_tone(dt,

message)

*dt;
*message;

/* Device descriptor
/* Announcement

*/
*/

183

184

C PROGRAM EXAMPLE

Send

)

tones.

{

int

state;

int

code;

dt _phone(dt,

state

-1,

-1);

dt_onhook(dt);

dt_cmd(dt,
dt_talk(dt,

P2_PHONE,

P3_PH_TONE);

message) ;

dt_st(dt);
do

A
code

}
if

while

dt_read(dt,

(code

T
1

30);

dt_save(dt,

code)):

(state)
dt_hangup(dt);

}

PSS

AT,

C PROGRAM EXAMPLE

DTTRAP.C

This routine traps CTRL-C interrupts.
/*)LIBRARY
*/

#ifdef

DOCUMENTATION

title
index

dt_trap

Trap <CTRL-C> Interrupts
Trap <CTRL-C> Interrupts

#include
#include

<stdio.h>
"dectlk.h"

synopsis

dt.trapQ)
description

Set the global dt_abort flag if the user types
(On UNIX,
¢CTRL-C>» at the command terminal.
this is interpreted as catching the INTERRUPT
signal, which is not necessarily <CTRL-C>, and
which may be generated by running the "kill*
system

program.

When the interrupt is received, pending I1/0
is cancelled (on those operating systems where
this makes

sense).

1f dt_abort is set TRUE when the interrupt is received,

the program aborts.

No error

returned.

fendif

¢stdio.h>
"dectlk.h"

#include
#include
#ifdef

wunix

<signal.h>

#include
static

catch()
{

(dt_abort)
—exit(2);

dt_abort
}

dt_trap()

TRUE;

186

C PROGRAM EXAMPLE

/‘*

Trap

CTRL-C

interrupts.

{
signal(SIGINT,

catch);

signal(SIGTERM,

catch);

}
#endif
#ifdef

wvms

#include

<ssdef.h>

#include

<signal.h>

static
catch()

{
register

DECTALK

*dt;

(dt_abort)
-exit(SS$_ABORT);

dt_abort
for

(dt

=
=

TRUE;
dt_root;

NULL;

AST

dt->link)

sys$cancel(dt->unit);

}

dt_trap()
/*

Trap

CTRL-C

interrupts.

{
signal(SIGINT,

catch);

}
¥endi
f

#ifdef

rsx

#include

<cx.h>

#include

<qiofun.h>

#include

<qioret.h>

#include

<qiottd.h>

¥define

QIO_EFN

static
catch()

{
register

DECTALK

*dt;

asiset();
if

entry

(dt_abort)

$$fail();

dit_abort

TRUE:

/Iv

Kill

all

pending

DECtalk

I/0

*/
for

(dt

dt_root;

qiow(IO_KIL,

NULL;

dt->unit,

&dt->iosb,

NULL,

}
astx(1);

;

dt->link)

{

QIO_EFN,

&dt->parm);
/*

AST

exit

C PROGRAM EXAMPLE

static QIOPARM

astparm = { NULL, 0, catch };

dt_trap()
/*

* Trap CTRL-C

interrupts.

*/
|

qiow(ID-fiTfi,

fileno(stderr), QIO_EFN,

NULL,

&astparm);

}

#Yendif

#ifdef

rti1

static

catch()
/l'

* Executed by the operating system if an interrupt is
*

detected.

{

(dt_abort)
$$fail();

dt_abort

TRUE}:

}

dt_trap()
/*

Trap CTRL-C

interrupts.

%/
{

setcc(catch);
}

fendif

187

188

C PROGRAM EXAMPLE

DTVISI.C
This routine generates a visible ASCII representation of a character stored in

the work buffer.

/*JLIBRARY
AP

#ifdef

DOCUMENTATION

title

dt_visible

index

Generate

Visible

Representation

Generate

Visible

Representation

Synopsis
R

char

workl(12);

char

Output

buffer

dt _visible(c,

work)

TN,

int

Character

char

workll;

Work

dump

buffer

description
A

visible

stored

end

Note

ASCII
in

the

that

work

output

this

definitions

and

representation

the

string

routine

(except

DT_TIMEOUT

buffer.

error

that

of
A

the

character

pointer

the

returned.

independent
it

knows

about

DECtalk
the

DT_ERROR

codes).

Yendif

#include

<stdio.h>

#include

"dectlk.h"

char

dt_visible(c,

buffer)

int

Character

char

*buffer;

Where

convert

store

conversion

*/
*/

C PROGRAM EXAMPLE

* Make a character "visibl e" ASCII.
*

Return a pointer

the

trailing

EOS.

fla g3

int

switch (c) |
NUL:
strcpy(buffer,

case

"“"<NUL>");

break;

case DT_ERROR:
strcpy(buffer,

M¢ERROR>");

break;

case DT_TIMEQOUT:
strcpy(buffer,

“¢TIMEOUT>");

break;

case

ESC:
strcpy(buffer,

"CESC>");

break;

case

DCS:
"¢DCS>»");

strcpy(buffer,
break;

CSI:

case

strcpy(buffer,

"¢<CSI»TM);

break;

ST:

case

strcpy(buffer,

"eST>TM);

break;

default:
flag

0x 7F
7

*buffer++

(flag)

(Cc
c

\n’

0x80)

{

»=

‘\r’));

0"’;

OxFF)

&& c

0x80;

*buffer++

P
H

}

<«

*buffer++

(flag

b4;

}

else

(flag

*buffer++

| t

\n?’

]

(flag)

*buffer++

[

>73

*buffer = EO0S;
return (buffer) ¥
»

}

return

(buffer

st rlen(buffer));

189

190

C PROGRAM EXAMPLE

HELLO.C

This is a very simple test program, to show that DECtalk is operating correCtly.

/*)BUILD
$CINCLUDE)

{

$(RTLIB)

{

dtlib,c:rstslb,c:clib

$(RXLIB)

{

dtlib/lb,c:cx/1lb,c:c/lb

dectlk.h

}

}
}

*/
#include

<stdio.h>

#include

“"dectlk.h"

#jifdef
extern

#define

vms

i nt

errno;

I0_ERROR

errno
Sy

#endif
#ifdef

unix

#¥define

I0O_ERROR

¥endif
Aoy

DECTALK

*dt;

main(arg c,

argv)

int

argc;

char

*argv(i];

{
char

dev
if
if

*dev;

"ttg7:";

Cargc

dev

argv(1];

((dt

dt_open(dev))

NULLD

{

perror(dev);

printf("Can’t

open

DECtalk\n");

exit(I0O_ERROR):
}

dt _debug

TRUE;

dt_trap();
printf("calling

Log

CTRL-C

text
trap

*/
enabled

init\n");

('dt_init(dt))
printf('"Can’t

else

initiate

DECtalk\n');

{
printf("Initialized\n");

dt_dcs(dt,

P2_MODE,

dt_talk(dt,

"Hello

MODE_SQUARE,

-1);

world.");

dt _sync(dt);

dt_dump("after

sync",

dt_close(dt);

&dt->reply)d;
[

printf(“Success.\n");

AASOIESy,

BASIC-PLUS
PROGRAM EXAMPLE

This chapter provides the source listings of a simple DECtalk telephone

answering program, written in BASIC-PLUS for RSTS/E. You can copy and use
this program; however, the program is only a model, and cannot cover all

possible DECtalk applications.
RSTS/E SYSTEMS

On some RSTS/E systems, you may need system manager privileges to run

this program. Please refer to the appropriate RSTS/E manuals for more
information.

EXTEND

1 #

DECtalk

The

library,

function

—

)

the

string

w
g
)

”

function
with

library

and

generally

some minor

sample

application.

duplicates

the

simplifications.

digits.

The

them as a number,
’‘*’

key

functions

&
&

!* The sample program reads a string of numbers from
keypad and speaks

and as a
as

dollar

&
&
&

!'* sign, and the ‘#’ key functions as a decimal point.
!* The program also illustrates how an application
'* might manage keypad timeouts.

&
&
&

Defaults

DEF.kbs$ = *KB2:"
\ DEF.log$ = "yesTM

!
!

DECtalk device
Assume log?

&
&

191

192

1000

—

BASIC-PLUS PROGRAM EXAMPLE

i
!'*

Main

program

1 #

1010

Initialize

Channel

Console

Channel

Log

file

input

open

"kb:"

kb$

DECtalk

for

debugX

file

FNyesnoX("Enable
ncallsX

error.count¥

(debug%

logfile$

open

the

debug

then

FNprompt$("Debug
for

DEF.kb$)

logging",

logfile$

parameters

DT.logX)

DEMO

for

terminal',

(FNyesnoX('"Enable

retries%,

start

keyboard

FNprompt$("Dectalk

DT.log%

and

output

DEF.log$))

printouts",

Clear

Need

log
as

errors
a

yet

log

file",

file

"yes")

counters
file.

"kb:')

2%
BRSOy

while

(FNinit%(kb$))

retriesX

while

retriesX

(FNprocessX)
=

ncallsX

retriesX

goto

1800

(retriesX

then

(debugX

Answer

many

goto

initializations
the

this

call

Got

Clear

goto

32767

2000

def*

FNprocessX

&
&

retry

0%)

&
&
&

Fatal.

For

all

calls

For

all

restarts

numi$(ncalls¥))

DT.log%

1900

call

Trouble?

"TM

retries")

1800

after

phone

error.countX

FNlog%Z("Too

and
then

2%)

FNlogx("finished

Count

DECtalk

next
\

1800

(FNanswerX)

1300

Initialize

FNlogX("Initialization")

ncallsZ

1200

&
!

All

done

1100

OB,

FNprocessZX
!

User

speak

process.

Return

Read

out.

TRUEXZ

number

Return
if

ok,

when

FALSEX

from

phone
on

the

keypad

and

hung

up.

error.

FNprocess%Z

FALSEX

FNlogX("answered")

FNspeak%("[:np

nkeysZ

FNspeakX('"It

2010

FNspeakX("Enter

FNspeakZ('dollar

FNspeakX('"key

(not

:ra

goto

Count

Welcome

time$(0X)

date$(0X)

*".'")

number,
sign,

means

while

then

enabling

DECtalk.")

star
the

key

means'")

number-sign'")

point.'")
turn

the

keypad

keypad')

presses

the

decimal

failure

button

FNlogX("error

2080

Assume

FNphoneX("20'))

1801

now

Error

exit

‘

BASIC-PLUS PROGRAM EXAMPLE

2020

2030

if (not FNptestX(R3.PH.OFFHOOKX))
g%

FNlogX("enable

goto

keypad,

2080

while TRUEX

then

state:

10%

Error

For

exit

all

numbers

first

character

timerX% =

work$

Input

while

TRUEX

Get

the

number

Read

character

Get both flavors

&
&

buffer

&
&

¢cX

¢c$

= chr$(cX)

goto

2080

‘H’

Hangup

goto

2080

‘E’

Error

goto

2080

‘X’

Escape

goto

2050

c¢$

‘T’

Timeout

&
&

'8’

Fix

\c$

’#’

buttons

work$

Stuff

Short

prompt

Read

work$

timerX

goto

2060

FNspeakX("You

FNspeakXZ("that

FNprocessX

2080

(work$

*')

entered
is"

\ gX

FNhangupX

“
~

= FNlogX("process

2090

fnend

3000

read

work$

Read

Normal

Turn

off

And

hang

exit after "

now

all

loop

anything?

",")

&
+

".")

completion

keypad
up

the

phone

numi$(nkeysX))

FNexpand$

(text$)

Expand

number

Note

that

this

application

the

caller

% m12.3",
the

string

into

its

would

useful

speak

number,

could

copy

the

output

leading

blank.

will

component
in

"“bank

digit

down.
be

the

point

bytes.

phone"

digit,
input
3".

Note

&
&

def* FNexpand$(texts)
o

g¢

for q%

3090

numbers

P *

number

Did we
"

error

funny

FNexpand$(work$)

TRUEX

FNphoneX('21")
=

sequence

2060

RSTS/E

\Nc$

from

q1$

1%
=

len(text$)

OQutput

For each byte &

mid(text$,

g%,

1%)

Locate

q1$
=

"pointTM

q1$

*.°

Fix

q1$

"minus"

q1$

*-*

q1$

"dollar

sign"

q1$

FNexpand$

fnend

qX%
=

q1$

‘$°

work
it

&
&

the

special

cases

and

stuff

That’s

‘em

&
it

all

&
L

2050

FNkeyX(timerX)

For

numi1$(R3%))

193

194

BASIC-PLUS PROGRAM EXAMPLE

Note

that

the

code

functions
is

not

error

conditions

Escape

the

for

DECtalk

particularly

that

are

Sequence

fast

handled

parser

are

and

some

the

ignored.

version

Note:

input

channels

DECtalk

output

following

8
2

Log

file

(AR

the

DT.log%

fEE

Support
the

Basic-Plus

| *

channel

are

used:

log

file

open

RIS,

SRR

TRUE,

Application

programs

call

the

following

routines

INE

FNinitZ(kb$)

Initialize

SHE

FNanswerX

Finish

last

FNhangupX

Hangup

the

FNkeyX(timeout®)

Read

character

DECtalk

call,

with

(from

Phone

hung

Timeout

Error

A
SHE

specified

FNtestX(R2%,

Test

current

FEER
ED
AR

reply,

FNtest%()

intermediates,

followed

text

Send

Log

SsEE

text

FNlogX(text$)

FNvisible$(charXk)

Make

text

R
IR

finals.

(R2X

checked)
:A

message
and

printable
debugging

DCS

text

seq.

for
msgs.

SOt
i,

test

return

IOWF

R3.PH.TIMEQUT

TRUE

tE
SWER
AR

R3%Z

FNfunnyX

returns

EAS

R2%X

FNdumpX(text$)

Dump

ok.

is
must
not

bad
the

ignores

replies.

sequence,

DCS

text

FNfunnyX(text$)

FNmessageX()

IANE

Send

reply.

"P2;P3...",

STNE

Note:

it.

R3X)
Send

FNphoneX(text$)

none

DECtalk.

character

logging

3OS

character,

and

Send

FNspeakZ(text$)

R2%Z,

checks

true

ignore

phone

FNsendX(text$)

FNmessageXZ(text$,

Test

FNptestX(R3X)

sequence

timeout,

R3%

-1

RSTS)
up

Escape

Set

SEE

Bad

FNtimeoutX(sec%)

timeout

character,

R3%)

call

the

kb:

answer

THE

Returns

ENEE

10000

test

"P3;P4..."
be

R2.PHONEX

tested

called

error
P

FNmessageX()

sequence
current

the

——

log

reply
g

BASIC-PLUS PROGRAM EXAMPLE

!'*

The application program generally doesn’t

following

call

the

routines.

i»

FNsaveX(char)

Save type-ahead character,
return TRUE if saved.

FNdcsX(text$)

Send DECtalk

EWe

DCS message.

FNfromdectalkXZ(timeX)

Read

key

escape

sequence.

FNgetseqX(timeX)

Read

key

escape

sequence.

FNgetXZ(timeoutX)

Read one character.

parity

FANE

<NUL>

and

EINE

JER

Send DECtalk CSI
text has parm,

SEE

"“P2;P3...",

text

FNcsiX(text$)

Return

read

from

Read

<DEL>
on

not

are

use

the

record

are

ignored.

timeout.
fatal.

fngeti()

telephone

FAE
A

JEE

from DECtalk

Globals:

R1%,

R2%,

R3X

DT.timeoutX

TRUE

currently enabled.

error.count%
ESCX

Incremented on serious errors
ESC character (parity bit cleared)

CANZ
SUBX

CTRL-U character
CTRL-Z character
CSI character

timeouts

(cancel

are

sequence)

AEEE
FOIB

ESCS

GIEE

CRLFS$

FEEE

VTS

SINR

character

STX%

R2.PHONEX

R2%

phone

FNNE

DCS

keypad

R3.PH.ONHOOKZ

R3%

(phone

hung

EANE

CSIX
DCS%

R3.PH.OFFHOOKX

R3%

(phone

SANR

CHEE

SEE

FER

ETE

current reply parameters
set by FNgetsequenceX()

ST character

R3.PH.TIMEOUTX

R3X

(keypad

Carriage-return,

escape

send

Vertical

(DECtalk

flush)

up)

alive)

timeout)

SEEE

Tab

chr$(155%)

Line-feed

DT.anything
SEQ.anything

reserved
reserved

qlanythingl

general

for
for

local

buffers
parser

sequence

temporaries

keypad.

SRR

FNreadX(timeoutX)

message.
inter, final.

stripped.

errors

s BN

SUERE

Other
NOTE:

10010

CAE

195

10100

BASIC-PLUS PROGRAM EXAMPLE

def*

FNinitX(kb$)

H
!

Return

the

TRUEX

DECtalk

ok,

device

FALSEX

Initialize

error

[]

10110

196

P+
!*

Open

the

Then

initialize

terminal

all

"binary"

mode.

constants.

I »

10190

kb$

input

DT.inendX

SEQ.stateX

DIM

DT.p%(3),

DIM

qX(256)

TRUEZ

FALSEX

ESCX

27%

ESC$

chr$(ESCXZ

VT$

CRLF$

CANXZ

SUBX

(1%

8X,

file
0X

32X+16%X+4%+1%

mode

32%X++16X+4%X+1X%

Clear

input

buffer

Clear

input

state

SEQ.pX(3)

For

1X)

TRUE

TRUEX

FALSE

mode

9X,
!

not

128%)

chr$(ascii(’K’)

Escape

Define

escape

char

flush

char

)

DECtalk

chr$C10X)

ascii(’U’)

CANcel

ascii(’Z2’)

64%

SUBstitute

CSIX

ascii(’[’)

B4%

128%

Define

DCSX

ascii(’P’)

b64%

128%

STX

ascii(’\’)

64X

128%

characters

R2.PHONEX

R3.PH.ONHOOKZ

R3.PH.OFFHOOKXZ

R3.PH.TIMEOQUTX

64%)

debugging

chr$(13%)

parameters

string

(CTRL-U)

(CTRL-2)
control

70X
=

FNsendX(chr$(ascii(’Q’)
=

FNget%(2%)

FNdcsx("82'")

FNcsiX("c')

“"Who

are

gq¥

FNfromdectalkX(5%)

escape

(DT.charX

while

(g%

64%
0%)

+
!

128%))
Drain

local->host

Read

CSIX%

Check
for

DT.final$

‘c’

DT.private$

*?°

DECtalk

R1%

19%)

q% = FNsendX(ESCS$
\

DT.timeoutX

FNinitX

fnend

+ "ip")

FNdcsX("80;1')
=

TRUEX

Return

from

failure

FNinitXxQ)

Soft

Set
No

Return

Terminal

MODE

Reset

SQUARE

timeouts
TRUE

now

FALSEX

10190

—

goto

FNinitX

sequence

FNfunnyXZ("initialization'")

FOER

you"

then

CTRL-Q

text

input

file

DT.incount%,

for

10130

for

open

10120

kb$

open

SO
Y,

BASIC-PLUS PROGRAM EXAMPLE

def*
!

FNanswerX

&
&

FNanswerX%

10210

10220

FNanswerX

Assume error

Drain

goto 10290 if (not FNphoneX(""))
1f (R3X = R3.PH.OFFHOOKX) then
goto 10290 if (not FNhangupX)

!
'
!

poll status
if alive,
hangup phone

&
&
&
&

(R3% <> R3.PH.ONHOOKX) then
q%¥ = FNfunnyX("hangup/poll®)

!
!

&
&

still alive?
Urk.
exit this

!
'

answer
ok?

&
&

Urk.

exit

\
\

10230

gotu
\ if

10250

FALSEX
while

(qX

0X)

10290

10290 if (not FNphoneX("10;1"))
(R3X <> R3.PH.ONHOOKX) then
\

10240

FNgetX(2%)

goto

= FNfunnyX("enable answer')
goto 10290

qX%
= FNfromdectalkX(0X)
\

(q%X <> DCSX) then
g% = FNfunnyX("waiting
\ goto 10290

(not
=

goto

for

FNfunnyX("expecting

ring

this

!
!
!

ring")

DT;timaout% = 0%

10290

fnend

10300

def*

then

offhook")

&
&

' No timeouts now

DT.pending$ = "*
FNanswerX% = TRUEX

!
'

Nothing pending now
ok.

&
&

FNtimeoutX(secondsX)

imeoutlt%Zdseconds

FAR

Enable or disable keypad timeout.
Note that
FNtimeout%(non-zeroX) will examine the state of the
type-ahead buffer before actually enabling timeouts

SR
B
W

10310
|

ok?
oops.
exit this

10290

10260

\
\

! wait for ring

FNptestX(R3.PH.OFFHOOKZ))

text

&
&
&
&

Finish off any current call (hanging up the phone)
Then setup and answer the next call.
Return TRUEX if the call was answered.
Return FALSEX if there’s serious problems.

!
!
!
!

10200

if (seconds% > 0%) then
secondsX
\

fr—

FEEE

IWAE

SANE

sER

(secondsX

if
>

= FNsyncX

(len(DT.pending$)
0X)

0X)

then

make sure all

heard

\ seconds¥% = 0% if (len(DT.pending$) > 0%)

the program requests that timeouts be turned
perform some special checks that the user
hasn’t already entered any text (which would be
stored in one of the type-ahead buffers.
If
something is pending, turn timeouts off.
This is
needed because RSTS allows a program to run even
if all output has not been sent to the device.

on,

197

10330

10390

#2%,

(not

fnend

10400

def*

DT.timeoutX)

set
+

secondsX

Don’t

resend

(DT.log%)

numi1$(seconds%))

seconds¥%

save

FNptestX(R3.PH.OFFHOOK%Z))

PRIy

timeout

state

then

FNfunnyX("timeout")
o

10390

"timeouts

FNphoneX("30;"

DT.timeout’%
\

(seconds%

goto

10320

ATy,

BASIC-PLUS PROGRAM EXAMPLE

198

FNsyncX

Synchronize

when

Warning:

the

slight

chance

FNsyneci2

system

timeout,

all

with

text
if

you

have

sent

the

wrong

that

this

even

This

DECtalk

function

has

much

text

phase,

code

though

been
to

there

could
there

returns

spoken.
DECtalk
is

get
are

an
no

and

very

operating
errors.

moon

DECtalk.

sent

FNsendX(VT$)-

Flush

Send

FNdcsx("11'")

(not

10490

fnend

10500

def*

FNmessageX('22",

32,

-1))

then

FNfunnyZ("sync'")

speech
sync

10410

ey
v

FNhangup%

telephone.

Returns

(TRUEX)

when

the

error

phone

detected.

on-hook

the

properly

Hangup

FNhangupiZ

10510

FNhangupX

FALSEX

goto

10590

while

(R3%Z

sleep

goto

10590

FNhangup%

10590

fnend

10600

def*

Assume

FNphoneX('"11"))

R3.PH.OFFHOOKX>

\
\

(not

problems

send

wait

until

it’s

hung

hangup
[

FNphoneX("*))

TRUEX

loop

forever

now.

FNphoneX(text$)

FNphoneZ

(text

Send

You

phone

should

message,

then

state

call

actually

return

the

FNtestX

FNmessageX
see

just

extra

tack

them

just

code.

what

the

is.

(texts

then

text$

"')
=

"60:;*"

else

text$

“eO0O"

texts$

parameters
on,

status

else

report

10610

BASIC-PLUS PROGRAM EXAMPLE

FNphonu%

10690

fnend

10700

def*

FNmessageX(text$,

R2.PHONEX,

-1%)
-

10620

JER

the

charX

came

DT.pending$

return

asynchronous

from

buffer

FALSEX.

Note

keypad

user

and

that

data

return

entry,

TRUEX,

FNsaveX()

save

otherwise,

watches

for

timeouts.

that

cause

the

unreasonable
program

amounts

overflow

type-ahead may

memory.

Note

AEE

the

FNsawveX(charZ%)

10790

DT.timeoutX

goto

charX

10790

if Cinstr(0%,

=
if

None

Save

‘T’

chr$(charX))

0X)

FALSEX

DT.pending$

chr$(chari)

now

0%)

"0123456789*#ABCDT",

DT.pending$

def*

Disabled?

ascii(’'T’)

else

10800

Timeout?

0X)

(len(DT.pending$)

FNsaveX

fnend

then

10790

then

(DT.timeoutX

e
e

goto

10720

TRUEX

FNptestX(R3.PH.TIMEQUTX)

FNsaveX%

10710

e o e Qo o o Ko G0 o 0

FNsaveX(charX)

FNkeyX(timeoutX)
(CtimeoutX)

Read

type-ahead

sequence

from DECtalk.

EONE

FNkeyZ

keypad

character

non-zero

buffer,

enable

(in

read

there
a

The

one

character

timeoutX

the

escape

parameter

timeouts.

EANRE

extended

that

the
to

timeout

parameter,

compensate

for

RSTS/E

non-zero,

output

will

buffering.

FNkeyX

ignores

user

timeout

was

disabled.

FNtimeoutX(timeoutX)
FNkeyX

10820

10890

DT.pending$

goto

!
0%X)

timeouts

right(DT.pending$,

2%)

10890

(timeout%

4%X)

60%

FNfromdectalkX(timeout?Z)

ascii(’T’)

DT.timeoutX

q%¥

FNkeyX

fnend

Set/clear

then

ascii(DT.pending$)

timeoutX

(len(DT.pending$)

0X%

timeoutX

FNptestX(R3.PH.TIMEOQUTZ)

(g%

ascii(’H’)

FNptestX(R3.PH.ONHOOKZX)

ascii(’E’)

(g%

=
<=

ascii(’T’))
0%)

0.S.

error

qX%
Lo

10810

Note

TWIE

O EUNE

200

def*

FNmessageX(text$,

t2%,

t3%)

FNmessage$

(text$,

DECtalk

for

and

t3%X

reply.

DCS

sequence

Make

sure

parameters.

DECtalk

and

the

matches

Return

TRUEX

ok,

wait
the

else

t2%

FALSEX.

keypad

(AR

(EE

Send

12000

BASIC-PLUS PROGRAM EXAMPLE

are

timeout

(escape

the

timeout

IEE

expecting

set

FALSE

ignored,
we

sequence)

other

read

the

may

read

reply.

timeout

status

another

this

when

case,

flag

sequence.

TRUEX

goto

FNfromdectalk%Z(60%)

12020

(q%

goto

12020

FNsaveX(qX)

not
g%

12090

fnend

12100

def*

STX)

(FNtestX(t2%,

t3%))

FNfunnyX("message

FNmessageX

Send

Assume

the

get

ignore

save

something

string

term.

type-ahead

then

test

sequence

success

Check

seq.

error')

FALSEZX

FNfromdectalkZ(timeoutX)

junk

between

escape

sequence

DCS

final

keypad

character.

and

string

terminator.

Dump
A

SHR

Read

FANE

FNfromdectalék*CtimeoutZ)

sHiE

(SEQ.stateX
gosub
\

12120

goto

SEQ.stateX
\

gosub

and

SEQ.stateX

STZ)

then

Grab

the

12180

And

return

Nothing

Get

Make

Toss

junk

Return

12200

12190

fnend

12200

if
=

(g%

DCSX)

DT.charX

sequence
char

pending

value
now

something

current

until

character

Subroutine

last

buffer.

FNfromdectalkX

FNtossX

12180

the

FNgetsequenceX(timeoutX)

12200

12110

TM=

R
B NN

FNdcsZ(text$)

12020

FNmessageX

escape
DCS

called

from

sequence

FNfromdectalkX

read

This

needed

final

and

the

into
skip

string

the

copy

"current

over

junk

terminator.

the

sequence"

between

oo
o
R

12010

and

some

T
:

BASIC-PLUS PROGRAM EXAMPLE

12210

! Sequence type
! Sequence terminator
! private characters
! Intermediates

DT.charX% = SEQ.charX
\ DT.final$ = SEQ.final$

\ DT.private$ = SEQ.private$
\ DT.inter$ = SEQ.inters$

! Parameter count
! Param’s

\ DT.parm% = SEQ.parmX
\ R1%, DT.p%XC(1%) = SEQ.pX(1%)

9
L

!
\ R2%, DT.p%(2%) = SEQ.p%(2X)
!
\ R3%, DT.p%(3%) = SEQ.pX(3%)
dt.parm¥X; "“parms:
' \ print #2%,

12290

return

12300

def* FNtossX
'
!
L

“;

R1%: R2%X;

R3%

&
&

FNtoss X

! Called after reading a DCS, this function reads
! text to the terminating string terminator.

p
L

&
&

&
&
&

&
&

12310

SEQG.stateX = 0X%

12320

qZ = FNgetsequenceX(5%)

\ if (q% <= 0% or (g% >=
then FNtoss% = qX%
else goto 12320

128X and q% <=

159%))

&
&

12390

fnend

13000

def* FNgetsequenceX(timeoutX)
FNgetsequenceXCtimeout?Z)

!
!

! Read

!
!

the next ANSI

the next character or

Escape

standard

Sequence.

Returns:
Initialize by setting SEQ.stateX to zero.
sequence final character

! SEQ.stateX

Note

the

following goto’s:

!
!
!

goto
goto

13010 to read the next character in a sequence.
13020 to continue processing (needed when escape
followed by a second character turns

goto

13120

into a C1 control character).

~goto
' ~goto
]

to exit

an ESC

sequence

13130 to exit after reading a DCS/CSI sequence.
13140 to exit a CO control within a sequence.

'
'
'
'
'

!
'

|
|
'

The following

SEQ.charX
SEQ.finals$
SEQ.stateX
SEGQ.parm%
SEQ.p%([]
SEQ.inter$

SEQ.private$

is set by

this module:

the character or sequence type
the sequence final for CSI/DCS/ESC
zero when sequence ends.
number of parameters
each parameter as read
intermediates

private

introducer,

‘X’

if error seen

0 Qo Do 0 G G Qo G0 G Q0 Qo G0 Do Qo O Qo Qo o o O o o 0 o & o

201

BASIC-PLUS PROGRAM EXAMPLE

13010

DT.c%

13020

fngetX(timeout¥)

Get

a
the

character

(DT.c%

ESC%

DT.c%

CSI%

introduces

DT.cX

DCS%Z)

then

sequence,

DT.c%

all

SEQ.stateX

13030

SEQ.inter$

#2X%,

“seq

SEQ.privates

SEQ.parm%

SEQ.pX(1%),

goto

start:

character

work

new

initialize

areas.

fnvisible$(dt.c¥%)

"u
=

SEQ.pX%(2%),

SEQ.p%(3%)

13010

13140

202

(SEQ.stateX

0X)

done

read

another

byte

sequence

control

;

Continue

processing

the

current

sequence

((DT.c%

>»=

128%

(DT.c%

CANX%)

(DT.c%

SUB%))

SEQ.stateX
\

\
13040

goto

and

DT.c%

then

#2%,

"cO0

control:

(DT.c%

32%)

CTRL-U

CTRL-2

force

sequence

exit

fnvisible$(dt.c¥%)

"“;

13140

160%)
!

and

Exit

return
if

control

!
!

Process

sequence

introducers,

terminators

intermediates,

and

other

)

13060

goto

DT.cX

goto
13120

goto

’

fnvisible$(dt.c¥%)

get

then

63%

(SEQ.inter$

128%

#2%,

"c0

c1:

13020
if

(DT.cX

#2%,

"not

13080

"intermediate:

ESCX)

and

13130

DT.cX

#2%,

(SEQ.parm%

64%)

terminator

(DT.cX

"private
>

60%)

¢<ESC>

Mask

out

"""

Make

bits

32%)

control

Sequence

control

terminator

frnvisible$(dt.cX)
private
'";

introducer?

fnvisible$(dt.c%)

maybe,

but

illegal

after

first

param.

else

SEQ.private$

chr$(DT.c%)

SEQ.parmX

13010

Process

goto

control?

lower

SEQ.private$
=

fnvisible$(dt.c¥%)

introducer

0%)

another

then
\

13070

#2%,

Intermediate

chr$(DT.c¥%)

13010

(SEQ.stateX

goto

!
+

goto

then

SEQ.inter$

!
\

48%)

(DT.cX

SEQ@.inter$

13050

stuff

Mark

"param"

Read

another

S,
]

char.

parameters,

strange

BASIC-PLUS PROGRAM EXAMPLE

13080

]

We know the character is in the range “0’..°9’
7;’ (separator) or ‘:’ (illegal separator)

!
!

SEQ.parmX = 1% if (SEQ.parmX = 0X%)
! \ print #2%, "param or sep: "; fnvisible$(dt.cX)
! No param’s after
\ if (SEQ.inter$ <> "'") then
! intermediates.
SEQ.inter$ = "%
! Mark it invalid.
\ SEQ.privates$ = "X"

13090

! Parameter digit
if (DT.c% <= ascii(’9’)) then
! Make it a number
SEQ.pX(SEQ.parm%) =
(SEQ.pX(SEQ.parm%) * 10%) + (DT.c% - ascii(’0’))
! \ print #2%, "digit, param :="; seq.pX(SEQ.parmX)
! Go read another byte
\ goto 13010

13100

Lad

and

another

byte

read another byte

|If no parameters
! Character is a sequence terminator.
! were read, return a single zero-valued parameter.
(SEQ.parm%

the end of

0X)

fnvisible$(dt.cX)

Jump here at

“terminator:

;

sequence.

!
!

Set the final
Get return value

Not

13140

SEQ.char% = DT.c%

Character code

13180

FNgetsequenceX = SEQ.charZ

Return value

13190

fnend

That’s all,

14100

def*

SEQ.stateX

in a

sequence

folks

FNsendXZ(text$)

FNsend%d(texts$)

Note, the text
‘Send a string of text to DECtalk.
‘length must be less than the DECtalk terminal buffer

go Qo

size.

fo fe

SEE
A
FUR
SER
SENE

SEQ.final$ = chr$(DT.cX)
\ DT.c% = SEQ.stateX

[

ithe

\ print #2%,

read

13010

SEQ.parm¥%

13130

separator

t #:’ isn’t a separator
SEQ.private$ = "X
' \ print #2%, “bad separator “; fnvisible$(dt.c%)
\ goto

13120

parameter

R0 g5 2

13110

13010

goto

(DT.c% = ascii(’3;’)) then
SEQ.parmX% = SEQ.parm%Z + 1%

Re e o RN Qe

inter"

"“parm or separator after

\ print #2%,

203

q¢

put

#9%,

(debugX%

#2%,

def*

‘sent:

then

len(text$)

###

"’

Jen(text$);

qX%

FNvisible$(qX(q%X));

#2%,

qX(0%)

‘'’

14200

count

using

4096%,
DT.log%)

text$

#2%,

for

fnend

and

record

change

14190

text$

len(text$)

lset

#9%,

field

SR,

14110

BASIC-PLUS PROGRAM EXAMPLE

204

FNcsiX(text$)

FNsend%X(ESC$

"["

text$)

FNcsi%2Ctexts$)

]

i Send a Control Sequence to DECtalk.
]

14300

def*

FNdcsX(text$)
FNsendX(ESC$

"PO;"TM

text$

ESCS$

"\")

FNdcs

Send

AMEE

Note

that

Z(text$)

string

DECtalk
the

Device

Control

DECtalk

terminator

are

Sequence.

parameter,

final,

automatically

and

SENE

included.

14400

def*

FNspeakX(text$)

FNsendX(text$

CRLFS$)

FN]l1ineX

(text$)

Send

line

text

DECtalk,

followed

character

means

(EEE

timeout%

wait

timeoutX

-1%

return

IWE

return

timeout,

fatal

character

and

<NUL>

(000>

forced

timeoutX

into

<DEL>

seconds

immediately

exit

the

(127)

range
are

other

none

errors

000

127

ignored

and

DECtalk.
none

The

from

timeout%

FUNE

Read

the

(timeoutZ)

FNgetX

FNgetX(timeoutX)

def*
EB

15000

15020

(DT.incount%

goto

15080

DT.inend%)

(not

None

FNread%(timeout%))

saved?

while

15010

BASIC-PLUS PROGRAM EXAMPLE

15030

:
g

field #8%, DT.incount% as q$, 1% as q%

! get char

\ FNgetX = qX
\ goto 15090

! return char
! exit

&
&

\ DT.incount% = DT.incountX + 12X
\ q% = ascii(q$) and 127X
\ goto 15010 if (g% = 0% or q% = 127%)

! step index
! drop parity
! ignore nulls

! got timeout

15080

FNget% = 0X

15090

fnend

15100

def* FNreadX%(timeoutX)

!
'

FNreadXCtimeout?X)

15110

&
&
&
&
&
&
&

goto 15120 if DT.incountX < DT.inendX

! Still stuff

\ q¢ = sys(chr$(3%) + chr$(9%))

! no echo

\ on error goto 15150

-+ sys(chr$(4%) + chr$(9%))
\ wait timeoutX if timeoutX > 0X

! grab error

! odt mode
! timeout

! read buffer
\ get #8X% if timeoutX >= 0X
\ get #8%, record 8192% if timeoutX ¢ 0X
! got it
\ DT.inend% = recount

"
.
:

&
&

Read a record from DECtalk.
means none
0%
timeoutX =
wait timeoutX seconds
0%
timeoutX >
return immediately if none
-1%
timeoutX =
return FALSEX on timeout, fatal exit on other errors
return TRUEX on success.

!
!
!
!
!
!
'

\ wait 0%
\ DT.incountX = 0X
\ on error goto 19000
\ if (debugX and DT.logX) then

! no timeout
! clear index
! common exit

print #2%, using “read: ### ‘" DT.inendX;
\ field #8%, DT.inendX as q$
\ change q$ to qX
\ print #2%, FNvisible$(qX(qX));
for q% = 1% to qXC(0%)

\ print #2%, "%

&
&
&

&
&

&
&
&

&
&
&
&

15120

FNreadX = TRUEX

\ goto 15190

15150

resume 15180

15180

FNreadX = FALSEX

15190

fnend

if (Cerr = 15% and timeoutX > 0X)
or Cerr = 13X and timeoutX < 0X))
\ goto 19000

&
&
&

205

206

BASIC-PLUS PROGRAM EXAMPLE

16000

def*

FNtestX(t2%,

t3%)

(DT.charX%

DCS%)

and

(DT.final$

and

(len(DT.inter$)

and

(len(DT.privates$)

and

(R1%

0%)

and

(t2%

R2%)

and

(t3%

R3%

72z7)

t3%

0%)

it’s

from
DECtalk

Check

-1%)

R2%

maybe

check

R3%

FNtestxCt22x,

Return

SAB

formed

GUEE

parameters

t3%)

the

current

match

sequence

T2X%

and

whose

T3X.

T3%

properly-

R2%
is

-1%.

and

R3%

ignored

MBSO

SHE

TRUEX

DECtalk

def*

FNptestX(t3%)

FNtestX(R2.PHONEX%,

Test

phone

test

SONE

Return

FAES

TRUEX

the

and

current

the

T3%

R2X

parameter

R3%

def*

FNfunnyX(text$)

FNfunny

Ctexts$)

! Log an error message and dump the current reply.
=

(DT.log%)
print

#2%

FNfunnyX

fnend

17100

def*

then
if

#2X%,
=

(ccpos(2%)

"Illegal

0%)

FNdumpX("")

FNdumpX(text$)

".»

Dump

FNdumpZCtexts$)

texts$;

|- ad

17090

error.count%

= 0o o

2 G

error.countX

17010

fo Qo

the

current

reply.
L

17000
-

matches

EHE

R2.PHONEX

vam

t3%)

fe oo

515

16100

then

(DT.log%)

print #2%,

sequence read';

"Last

text$;

\ print #2%, " at ";

if C(texts <> ")

print #2X, e M.
if (DT.charX = 0%)
then print #2%, "eTIMEQUTM

\
\

for q% = 1X to DT.parmX
\ print #2%, numi1$(DT.pX(q%x));
if (DT.p%X(q%) <> 0X)
\ print #2%, ";%;
if (g% + 1%) < DT.parm)

next qX
print #2X%,

\ print #2%,

fnend

17200

def*

DT.final$;

"eSTH»":

if (DT.char¥% = DCSX)

#2X

17190

V
else print #2%, FNvisible$(DT.charX);
\ print #2%, DT.privates$; DT.inter$;

o R O 06 o O

Qo oo S0 Do B

17110

e D 2 R

BASIC-PLUS PROGRAM EXAMPLE

FNvisible$(cX)

(cXx)

Return "datascope" version of cX

sEE

SWR

FNvisible$

if (cX% = ESCX)
else if (cX = DCSX)
else if (cX = CSIX)
STX)
else if (cX%
10%)
else if (cX
else a if (cX = 11%)
else e if (c% = 13%)
els e q.vis% = (cX >=
q‘

=
FNvisible$
FNvisible$ =
FNvisible$ =
FNvisible$ =
FNvisible$ =
FNvisible$ -]
FNvisible$ |

127% or cX < 32X%)

NCESCHTM
"eDCSH"TM

"<¢CSI>»*"TM
"¢ST>»"
CRLFS$
"
HeVTH
s

= "¢~
qs$
qs$ = "<
cX

then
then
then
then
then
then
then

if
if

and

(cX
(cX

>=
<«

128%)
32%)

127%

q$ = q$ + uAu 4 chr$(cX% + 64%) if (cX < 32%)
q$ = q$ + chr$(cX) if (cX >= 32%)
q.visX
:

q$ = q$ + '">" if
FNvisible$ = q$

fnend

17300

def* FNlogX(text$)

(text$)

FNl1og%
text

message

Log

koo

17310

i (DT.log%) then

print #2%, date$C0X); " “;

SEER

sNiE

17290

A
A A
.

17210

time$C0X);

" ";

texts

207

208

BASIC-PLUS PROGRAM EXAMPLE

17390

fnend

17400

def*

FNyesnoX(prompt$,

defaults$)

FNyesnoX(prompts$
!

Prompt

and

get

yes/no

,defaultsts)

answer

17410

q%
\

until

(g%

FNprompt$(prompt$

g¥

instr(1%,

fnyesnoX

17490

fnend

17500

def*

(g%

5%)

"YES

NO",

"(Yes/Nod",
cviss(qs,

defaults$)

-1%))

1%)

FNprompt$(prompt$,

defaults$)

#1%,

input

FNprompt$,

FNprompt$

fnend

19000

i
!

response

prompt$;

line

\
17590

get

<";

default$;

#1%,

cvt$s$(qs$,

397%)

cvt$s$(default$,

Fatal

*>?

and

17510

Prompt

(prompts$,defaults)

Err

NpromptX

397%)

len(q$)

'!F

19100

print
\

‘Fatal

Error

"’;

cvi$s$(right(sys(chr$(6%X)
+

19180

stop

19190

goto

32767

end

chr$(errori)?,

line’:

3%),

error.lineX

line

and

take

fatal

force

new

error

exit

line

32767

p——————,

(

message

chr$(9%)

4%)
!

number

error

and

line

number

error

and

resume

erl

save

err

error.line%

19100

error%

19010

DECtalk ESCAPE SEQUENCES

This appendix summarizes the escape sequences (and their parameters)

described in this manual. The following tables list escape sequence mnemonics and their ASCII representations.

You can verify each ASCIl character by checking the decimal value that
appears below the character.

209

210

APPENDIX A: DECtalk ESCAPE SEQUENCES

IS5

SRy

PRI,

APPENDIX A: DECtalk ESCAPE SEQUENCES 211

212

APPENDIX A: DECtalk ESCAPE SEQUENCES

—

R S,

RO,

—

OIS,

APPENDIX A: DECtalk ESCAPE SEQUENCES

213

214

APPENDIX A: DECtalk ESCAPE SEQUENCES

Ao,

—

——

—

——

gr—

APPENDIX A: DECtalk ESCAPE SEQUENCES

215

216

APPENDIX A: DECtalk ESCAPE SEQUENCES

—

TSSO

»rmmmm»m

{

Twwmmmmwwm

APPENDIX A: DECtalk ESCAPE SEQUENCES

217

218

APPENDIX A: DECtalk ESCAPE SEQUENCES

—

p——————

[

—

PHONEMIC ALPHABET

—
o

This appendix summarizes the phonemic symbols that DECtalk uses. DECtalk
recognizes all 17 vowel phonemes and 24 consonant phonemes in the English
language (Table B-1).

DECtalk uses two-character symbols for each English phoneme. DECtalk also
recognizes a one-character system of representing phonemes. Use of the one-

f—

character system is discouraged, as it is not in wide use and may not be
supported on future releases of DECtalk. However, DECtalk can be set to the
one-character system. Refer to Chapter 4 of the DECtalk DTCO1 Owner’s
Manual.

Table B-2 lists emphasis characters, for adding stress and suggesting proper
phrasing (syntax).

219

220

APPENDIX B: PHONEMIC ALPHABET

SOy

v}fiwwmwwmwmw

p———

—

r—

APPENDIX B: PHONEMIC ALPHABET

221

TR,

SR,

P
—

DOCUMENTATION