Digital PDFs

01-0033-03-PRE

June 1982

226 pages

Original

82MB

Document:	XT Tool Kit User's Guide
Order Number:	01-0033-03
Revision:	PRE
Pages:	226
Original Filename:	XT%20Tool%20Kit%20uses%20guide.pdf

OCR Text

Dra- f+
TOOL KIT
USER'S GU IDE

t
,-

w]ffi-

R es tri cte d D is tri bu ti o n

EHEHNEI

I'']k0i't:SS I Oti AL t,, gV iLflPtR ,s
T00L KIT {.lSEti'S GIJIr)E

Document: 01-0033-03

June 19B2
1'his Gui<re explains t)o,1 Eo use the TooI Kit tc
write 6qpllcation softv.,are tnat may oe rntegrateo
wi€h che i)roiessional
i-rperat,ing Systerir (p/0d).
I i)e intor;rration in tlris docurFent is Drelrnrinarv
and suojecE to chanqe without notice.

P?. r.L]-l.i I I'r A it

Y ut(A F1'

i<C.S'r RI C I'I.,U DI S

IRI BUTiO.i

Page 2

The lnfornatlon 1n t.h1s ciocument,1s subject to change wlthout notice

and should not be construeo as a commitment oy Dlgltal Equipment
cgrporatton. D191taI Equipment corporation assumes no responsibility
for any errors that may appear 1n thls document,
The softlrare described ln thls docurnent 1s furnished under a license
and may only be used or copied in accordance wlth the terms of such
llcens e .

1s assumed for the use or rellability of software on
egulpment lhat 1s not supplied by DIGITAL or lts affiliated companles.

No responsibility

The speclflcations and drawings, herein, are the property of DisltaI
Egulpment Corporation and shall not be reproduceci or copled or useci 1n
whole or ln part as the basts for the manufacture or sale of items
wlthout wriEten permlsslon.

Copyrignt (c) 1982 by DlgltaI Equipment Corporatlon
A11 Rights Reserved
The following are trademarks of Digital gquipnrent Corporation:
DEC

DECne t

IiF:CSYSTEh-20
DI BOL
IAS

DEC US

PDT

UNIBUS

DIGITAL
HASSBUS
RSTS
VAX

DECsystem-1 0
DECPr iter

Edusys tem
PDP
RSX

vhs

RESTRICTED DISTRIBUl ION

Page 3
PiiEFACE

PART I

OVERVIEI{S

CHAPTER 1

PROFESSIONAL DEVELOPER'S TOOLKIT

1.1
1.2

IITTRODUCTION TO THE PROFESSIONAL
INTRODUCTION TO THE PROFESSIONAL IJEVE,LOPER'S TOOL

KIT

Figure ? fool KIE Envl r onmen !

t-2

P/OS COIICEPTS FOR APPLICATION DEVELOPERS

CHAPTER 2

2.L

2.t.7
2.t.2

SYSTEI'{ CONVENTIOIIS

2.3 .2
2.4

2.4.t

2.4.2
2.1.3
2.4.4
2.4.5

2.4.6
2.5

2-t

Prograrn Types .

Programstates..2-2
2-1.2.1
Interactlve Programs
)1)2
Noninteractlve Prograrns
2.7.2.3
Apptlcatlon l'lultltasKing
USER APPLICATIOIIS
2.2
2.3
P/OS SYSTEH SERVICTJS
2.3.r
FiIe, Print, And DisK Services
PROSE ANcJ P/OS COMI.lIJNIC4TIONS
USER INTERFACE SERVICES

2-2

FACILITY

Menu services

. 2-3
. Z-3
.2-3
. . 2-3
.2-4
. 2-4
.2.4
. 2.5
.2-6

Figure ?: DISK-BASED P/OS
Syst.em
^,lenu
Figure ?: DISKETTC-tsASED P/0S
Menu System
HeIp Servlces
Fessage Servlces
Message/Status Board
.
Function Keys
.

t-o
t-o
2-10
2-10

2-12

f igure ?: Professional Keyboard
0peration 0f Funct. lon Keys In P/OS
TaDIe ?: Descrlption ot Function Keys

P/IJS SYSTEI{ COHPONLNTS

Figure: Flor of Control At Run-Ti me
Resident Clustered Libraries
2.5.1
ProDispatcher
2.5.2
2.5.3
RSX/EXEC
PART II

1-1

2- Ls
2- L1

2-t1

2- t8

APPTICATION DEYELOPMENT CYCI,E

Figure:
CHAPTEK 3

Program DevelopmenE CycIe

SELECIIIIG SOFTWAtiE COl\,1PONEI:TS FOR A PRLF'ESIIJNAL
/'.PPLICATION

3.1

PR0FESSI0I{At HARDI'lARE CONFIGURATIOf.S .

3-1

Par;e 4
3 .2
PiiOFESS IONAL SOFTl{ARE COI'IF] GURAl.I ONS
Table 3-1: Applicati on Packages

CHAPTER

TOOTS FOR iiRITI NG TTiE APPTICATION

4.1

PROGRAI.',M I NG LANGUAGES

4.1.1
4.L.2
4.1.3
4.2
4.3
4.4
4.5
4.6
4.7
4.8

P R 0,/ B A S

3-1

I C - P L' U S - 2 ,

PRO,/D I EOL

PDP-11 !'lACRO-11 . .
FOR!{S J'lANAGEliENT SYSTEM (PRO/F14S-11)
PRO/RECORD iiAT{AGE}.{ENT SERVICES (RMS.1 1)
P RO,/SORT

P/OS SERVICES LIBRARY
GRAPH ICS LISRARY

RSX MACRO LIBRARY AND SYSLIB (SYSTEM OBJECT

LIBRARY).

FRAHE DEVELOPI'{Ei'JT 1'OOL (i'DT)

TASK BUILDIIiG THE APPLICATION OTi THE HOST

CHAPTER 6

CREATJNG AN APPLICATION INSTALIJATION FILE

CHAPTER 1

TRAt'ISFERING THE lASK TO THE PROFESSIONAL

4-5
4-5

II'ISTALLING, EXECUTII.,IG, AND DEBUGGIT.JG ThE APPLICATION

6.1

FAST INS'IALL
EXECUTE THE APPLICATIOI'I
DEBUG THE APPLICATION

8.2
8.3

9.1
a?
PART III

8-1
E-2

8-2

APPLICATI9iT D].SKLTTE BUILDER

CHAPTER 9

EH APT TR

CHAPTER 5

CHAPTER

4-1
4-2
4-2
4-3
4-3
4-4
4-5
4-5
4-5

RUN THE APPLICATION DISKETTE BUILDTR

LA8sl, TTISKETTES .

9-1

9-2

THE TARGET SYSTEM AND SOFThARE TOOLS

PROGRA},l},(INC EON\,ENTIONS FOR P/OS

10. 1

FUilCTION (EY UPEKAlION

10.1.1

10 " t.2

10.1.3

set.tinqs
Assigning Settings 1o The Function Keys
Function Key 0peratiorr During Appt icaLl on
Executlon
TabLe ?: Apptlcatlon Execution

10-1
10-1
10-2
I O-2

Page 5

t0.2

10.3

CHI.PTER 11

APPLICATION MULTITASKII'JG
THE PROFESSIONAL TEIiMINAIJ C;{ARACTER SET
Figure ? 3 DEC hultlnational Character Set
CALI,AtsLE SER,V ICES

FIIJE, DISK, Al'tD PRINT SERVICES o . ..
11.1
Conventions
11.1.1
, .
Table ? z User-vlslbLe File Types
Lt . L.2
rL-z

7t.2.I
rL .2.2
It -2 -2.1
tL .2.2.2

10-3
10-3

.
. , .

11-1
11-1

Table ?z SysLem/Appllcation F11e lypes
TabIe ?z Physlcal and Logical Devlce fiames
tL-4
Se rvices

OVgRV]El{ OF P/AS COHI{UNICATIONS F'ACILITY
Comrnunicatlons Servlces Ca111ng Conventions

11 . 2.3

11.2.3.1

rt.2.3.2

11.2.3.3
r1.2.3.4

Returned
....
St.atus Informatlon
'LlO Status
BIock
Fil-e rransfer Statistlcs Buffer .
CalI Control Services
EnaoIe/Dlsable Comntunicatlons 0pt.1on (CCEi'iBL
.And CCDSBL) .

CaII Control BIock Allocatlon (CCBALC).
Attach Llne (CCATT And CCATA) .
Derateh Ltne (ccDET) .

11 .2 .3 .5

. Set Line Characterlstics (CCSnC) .
Get Llne Characterlstics (CCGMC).
Get/Pu! Line Conflguratlon Record (CCLCRG

11.2.3.8

DiaI CaLL (CCDIAL)
Answer CalI (CCAliS)
liangup A CaIL (CCHIiG)
Transmlt Data (ccTxD)
Receive Data (ccRXD).
Flush lnput buffer (CCFLSH) .
Generate tsreak (CCBRK ) .
KiII Transfer (CCKILL) . .
File Transfer Services
Setup File Transfer 0ptions (FT0PTG Ano

11,2.3.b
LL .2.3 .7

rr
2 0
Lt.L.J.t ')
tt.2 -3 .10

11.2.3.11
Lt .2.3 . L2
11.2.3.13

tL.2.3.r4

11.2.3.15
r1 .2.1

And CCLCRP) .

11-5
r r-7
11-7
11-7
1 1-9
11-9

1 1-9
11-11
11-12
11-13
T

I-T4

11-r5

11-15
11-17
11-18
11-19

It-20
Lt-2t
Lt-22

11-23

tt-24

t t-25

it.z.q.t
11-25
FTOPTP )
.
LL-21
Sencj A FiIe (FTSl,lD)
t1.2.4.2
11-28
send A t'1Ie And hait (FTSND'r)
rL-2-4-3
11-29
Ret,rieve A Flle (FlGET) .
1t.2.4.4
11-30
Get A FlLe And hait (FTGETbJ) .
t1.2.4.5
11-31
I1.2.4.6
Get Transfer Status (FTSTS) .
LL-32
Abort Current Transfer (FIAET) .
LL.2.4.7
11-33
Ii'{S Services
. .
11.2.5
11-33
Cna-nge Mode (CcP,oDts) .
11.2.5.1
11-34
0r19inate ca]] (ccoRG) .
Lt.2.5.2
(ccAUxK)
11-35
.
euxlliary
Keyboard
Enable/DisabIe
1 1.2.5.3
11-36
Iurn Speaker On/Of. f ( CcSPKR )
lL .2.5.4
11-3?
I 1 . 2 .5.5
Prepare To Go Voice ( CCPTGV ) .
11-37
Set DTrF Escape Sequen:e (CCtiTriF)
Il .2.5 .6
11-38
PROSE, TEXT EDITOR
1 1 .3
11-38
Cal Iable Editor Task
I 1 .3. I
11-40
Lxample Callinq Seguences .
11.3.2

Page 6

.4
CALL.ABLE SORT PROGRAM (PRO/SORT )
PRO,zSort Comn,ands
LL.4.1
L1-4t
11.4.2
Comment SEetement .
. Ll-42
Indirect Coinmano File Command .
11.4.3
" tl-42
1L.4.4
CoLLATE Comrnand
. tI-42
DEFAULT Command
11.4.5
. tI-42
FIELD Cornmand
11.4.6
11-43
FORCE Command
17.4.7
11-43
. .
1 1 .4.8
INCLUDE Command
. 1 1-43
I NPUT Command
1 1 .4.9
7t-44
11,4.10 0UTPUT Command -.
. tt-44
, .
SORT Conmanci
11 .4. 1 1
. LL-44
LL.4.t2 dRITE Command
1 1-44
11.4.13 Comparlson 0f PR0/Sort And PDP-11 S0RT-11
tt-44
11.4.13.1 Comment Statement .
11-45
11.4.13.2 C0LtAl'E Commanci Compared t{ith ALTSE0 Recorcjs 11-45
1 1 .4. 1 3. 3
FORCn Commano ComF ared l{i Eh F Command
. 1 1-45
11.4.13.4 IIJCLUDE Command Compared ltlth 0 And I Recorci
11

I .4.13.5

.4. 13.5

11.4.13.7
CHAPTER L2
12 .1

t2.r.L

12.1.2
L2 "2

12.2.1
L2.2.2
12.2.3

12.2.3.t

12.2.3.2
12"3

L2 .4

Specif!catlons

INPUT And 0UTPUT Command Compared v{itn

Command Line Format ,
S0RT Comr''tand Compared with

Speciflcatlons

N And O Fleld

i{RITE Command Compared lilth D i'j.eIo

Soecifications

7r-46

. l1-46

. rL-41
. tI-47

FRAHE DEVELOPhENT TOOL (FOT)

t2-2

PLANN ING THE FRA}'1CS

fienus

L2-2

Flgure ?:
Figure ?:

A single-choice Menu
A Help henu
Figure ?: A frultiple-choice ilenu
l'i9ure ?: A Short-forin i'{enu
Help And I'iessage Text Frames.
Figure ?: A HeIp Tex! Frame
f-igure ?: A l1 essage Text Frame

L2-9

DEVELOPII.;G THE FRAI4ES

. T2-t2
. L2-t2
. i2-13
.12-16

Overview

Sanple Terrninal Sesslon

Frairre Development TooI Conmands

File Edltlne
L2-I9
Frame 0ciitlnq
.12-23
Figure ?: screen Edltor Keypad
CREATIT\G A,SINGLt-CH0ICE MENU
t2-21
Fiaure ?: Profi Ie Form for sinqle-choice Menu
F'lqure ?: Display F0rn for slnqie-choice !lenu
Flgure ?: Actlon Form f or Single-choice l'{enu
12'34
CREATING HELP ItENUS AtrD i"JELP TEXT t"RAi{l'-S
F lgure ?:
Prof ile Form f or Help I'lenu
t'igure ?: Display F,)rm f or help I'ienu
Fioure ?:

Action !'orm f or tlelp

l'1

enu

i'igure ?: ProflIe Form for HeIp Text i'ratne
Figure ?: trisplay Form for ttelp Text Frane

12,5

12.6
1

2.6.1

t2 .6 .2

CREATI NG I'lESSAGE TEXT FRAXES

Figure ?z Profile Form
RESOLVIHG ERROR CONDITIOIJS
Forirrat 0f l,tessages .
User Error liessages ..

FDT fnternal

12.5.3
CHAPTER 1 3

13.1
13.2
13.3
13.4
13.5

13.5.1

13.5
APPENDIX A

A.1

A.1.1
A.1.2
A.1.3
A.1.4
A.1.5
A.1.6
APPENDIX B
GLOSSAR Y

Errors . i .

P/OS SERVICES tItsRARY
DETAILED OVERVIEW

13-1

CONVENTIONS

IIENU SERVICE ROUTINES . .
HELP SERVICE ROUTINES
HSSSAGE SERVICE ROUTINES

VaIues Returned In Status

r3-2

L3-2
13-15
L3-2L

aa.a

I3-22

13-24

I SCELLAIJEOUS SERVICE.S

SUI.l!.(ARY OF EIiTRY PIJINTS TO P,/OS

SUdI4ARY OI- ENTRY POINTS

File services
Disk Servlces

Connrunicatlons
EciiEor

User Interface
|.liscellaneous System Servlces

THE DEC I'TULTIIiATIONAL CHARACTER SET

aa
a.oa

A- 1
A-1
A-1
A-1
A-1
A-1
A-2

Page 8
PLEF ACE

INTENDED AUDIENCE

rne TooI Kt t user's Gulde is for application developers l{ho are
use the
creatlng software for P/0S, Thls manual explains how to you
are
that
assumes
manual
Thls
professlonal Developer's Tool Ktt.
or
(RSX-11i'{
RSX-11H-PLUS'
envlronment
wlth the nost system
f amillar
'
your
user.
end
o'tJn
of
needs
you
the
understand
vAX/Vl.1S) and that
DOCUI.TENT DESIGN

part I provldes ttro overvlers: the first overview lnEroduces the TooI
kit.
The second overvlew lntroduces the target oPerating system'
P/OS.

part II descrlbes the soft*are developmenL tools in Che Tool Kit and
the program oevelopment cycle for applicatlons.
callable
P/OS I
Part, III descrlbes programmlng conventions for Iibrary.
servlces, Franre Development TooI' and P/OS Services
DOCUI'TENTATION CON VENTIONS

different
Certain conventlons are useci in the manual to distinguish
fo110ws:
as
are
Kinds of information. Ihese coriventions
o Examples conslst of computer out.put wherever possiole.
o The term filespec cienotes a file specification' awhich
file
inclurJes a device name, a cilrectory speclfication,
nunber'
version
a
applicable,
1f
and
type,
name, flIe
o User lnput is printed in red Eo dlslinquish it from cornpufer
output.

Altnough you
o Required characters are 1n UPPERCASE leEters.
f Or eXampIe, a Command name
uSE Eype reqUired characters
in the seguence shownr You can type t.hose characters in
eiLher uppercase or Ioi{ercase characters.
ln
o Variables, for which you rr ust supply a value, in are
eitner
Io,eercaSe Cnaract,ers. You can type variaoles
uFpercase or 1o*ercase characters.
lndicate
o vertlcat or horizontal elliPsis polnts ( 3 or ... ) can
repeat
You
lnformation.
repetiEive
optional
of
omlsslon
precedes
elllpsls
the
that
itenr
Ehe
rrr

Paqe 9
PART I

OVERV IEIIS

Chap,ter l presents an overview of the Professional 300 FamlIy and the

Piofesslonal Deve] oper's TooIkit.

Chapter 2 presents an overview of the Professional 0peratlng System

(P/0s).

CHAPTER 1

PROFESSIONAL DEVELOPER'S TOOL KIT

The Frofessional Developer's TooI K1t is a set of software development

tools cjesigned to be used by applicatlon developers t0 bulld
applicatlons for the Professionaf 300 family and computers. The Tool
Klt contalns soft,dare tooLs to help you develop stanciard appllcaclon
software for the Professional Operatlng System (P/OS), P/rJS is Che
operating system for the Professiorral 325 and 350 hardware.
1.1 INTRODUCTIOIT TO THE PROFESSIOI{AL
A Professional is 6 computer that belongs to a family of single-user,
desk-top computers tnat can De useci 1n many ways. For exarrple, a
ProfessionaL can be used as a:
1. Personal coriput,er for Professional englneers, executlves,
scientists, journalists, and ot,hers
2. SmalI-business system to perform accounts receivable,
accounts oayaole, payroll, inventory, oersonnel records,
corresfonrience, and so forth
qeneral
3. VAX/V,{S or RSX-11M,/H-PLUS '{orKstation
f or
program devel,opment. large-scale data
tlme-sharino,
processinq, and so forth
ALl members of tne ProfessionaJ. family sha!e tne followlng
f eatures:

l<ey

PDP-11 baseo t)rocessor

o 255K8 memory
o Dual disKette drive for 400K8 cilskettes
These common features fornr the Professional 325 and 350. hol'Jever, the
Prof.essionaf 325 does not accept acidltional options. 0f orimary

j.nterest to appllcation developers are the folloling

dlfferences

PROFLSSIONAIJ DT,VELOPEi{'S TOOL KIl

Pase L'2

rnode 1s :

'Ihe Professional 350 may have' ln addlt,ion to the 400K4 dual
dlsl<ette drlve, a 5MB disK.

P/0S may be e lther dlsJ<ette-bas ed
upon the hardware configuratlon.

disK-based depending

p/OS sof t.Y'are is a successor of on the RSX-11!-1-PLUS operatlng system.
However, the P/oS user interface replaces the RsX command lnterface.
keyboard and screen
The user lnterface lncludes on-Ilne help

'
reserved for t.he
conventlons, and a menu Lree with a branch
applications you develop. The user interface can be used by people
wiEh differlng Ievels of knowlege about, conrputers. lnexperienced
computer users can quickly star! using P/DS services through the
menus.

The menus and screen prornpts gulcie the user in

creatlng f 11es
printing
leECers, and $riting programs in BASIC. Displays of'
lnst.rucEionat informatlon appear on the screen at, the touch of the
HELp Key. p/oS users who are familiar wiE.h other computers can
quicKly learn Profess lonaI keyboarci and P/OS system convent.ions. A
full compJ.ement, of user documentation is provided rvlth the sysf,em.
therefore , You can
a foundetlon for applicat ion softlrare i
write programs that. work well with its operating system and blend in
wlth the complete system. Application prograns tnat. use the features
of p/OS wlIl provirje t,ne end user wit.h a consistenC wav to interact
with Ehe system. using fhe TooI Kit, programmers can creat.e P/0s
applicat.ions in which the user lnterface is cons istent wlth P/0s
services provioeo bY DIGITAL.
p,/0S is

L.2

INTROI.JUCTION Ti] THE PiiOFESSIONAL DCVELOPER'S TOOL KIT

The TooI Kit sofEr.are consists of application

deVelopment soft|{are:

A program development Ianguage that generates
capacle of executing on tne Profess lonal:

Programs

?PO/bASIC-PLUS.2 EX tended BASlC Compller ancj Debugger

PR0/DIilot Buslness-tJrlented programmlnq Ianquaqe

MACR0-11 AssernoIY Language

The Professional 0perating system (P/0s) services Library
(0b ject)
incluoing lnterf aces ':o IIr€nl.)s, nelp, messges, and
graphi cs

PROFESSIOiiAL DCVELOPER,S TOOL KIT

Fl."S-11 F'orms l{anagement System

RHS-11 FiIe i'lanagemenE System wit.h nrultlkey ISAM

Page

1-3

o PR0/Sort CaIlabIe sorting task
o Frame Devefopment TooI (FDT) for creating menusr on-line help
text, and message frames
o
RSX Task Builder for buildlng RSX-based programs
o

P/OS Macro Interfaces LibrarY

PRO/Diskette Builder to create Professional
Dlskettes

Program devel.opment documentatlon

0n-line DeDuqglng Technique (0DT)

APpllcation

You can use RSX-11M, RSX-11H-PLUS, or VAX/Vl'1S to create an aPPli'cation
t.hat wlII run on Che target system. 0n VAX,/VM-s, the t)rogram
development tools run uncjer the A.pplications l'i lgratlon Executlve
(Al,,E). Any supportec! conf lguration of these systems is appropriate
f or P/0S appllcation deveJ-opnrent.

In addltion to the above software and documentat.ion, to complete the
developer's TooI Kit develooment envi.ronment you must obtain the
Comrnunlcations
profesiionat
325 or 350, P/OS, and Professional
(*i.th caoling Eo the host). The Professlonal with P/OS 1s
FaciliEy
the tarqet run-tine systelTr tor applications you oevelop.
you can use the Termlnal Emulator
14iEh p/0S Conrmunications Facllity,
and FiIe Transfer program on t.he Professional to crea!e an executable
professionat applicaEion on the nost system. In terminal emulaEion
mocje, the profess ional behaves like a terminal on the hosE system.
on the
/ihen you are ready to run and cjebug the applicatlon
professional,
t,he yoU can Eranfer the files over the comlriunication
liow you can test ano ciebug tne application
Line to the professional.
in tlre target environmenE.
il'!nen your appl-ication is reaciy to be given to an enci uSBrr you
professional
DisKettes on rhe Professional wit.h the Application
Disket,te tsulIder.
Figure ? TooI KIE tnvironment
TO Bi, SU PPL I ED

CHAPTER 2

P/OS C0NCEPTS FOR APPLICATIOI.I DEVEIJOPERS

This chapter gives a conceptual overview of the Professtonal 0perating
System (P/OS) ano lntroduces lmportant terms'
Thls chapter discusses t,ne following toPlcs:
o

SysEem ConvenEions

o User APPIlcations
o P/OS SYstem S'ervlces
o User Interface Servlces

2.I

P/OS SYsEem Components

sYS'rE14 coft /friTroiis

P/0S is a single-user operatinq system. I'l,enus and forms are the
user's conrmand interface to system servlces and applications'
syster0 conventions dlctate the types of programs tnat P/0s supporls
anci the resources eacn tvpe of proqram can use' These are introduced

in the next sectlon.
'SyStem conVentions also govern Che nulnber of applications tnaE can oe
in
in use at one time anrj the state of an aFtplication when it is not
Tnese
nonlnteractive.
programs
or
may be lnteractive
use.
convenLlons are ciescribed in Sectlon ?

/OS C0iiCEPTS f OR

2.1 .1

A PPLI CAT I

iiN' DUVELCPERS

Page 2-2

Prograrn Types

P/OS supports t.xo types appl ications
1.

eno utilities

User applicatlons:
These applicatlons perform functions
related to the user's wopK, since they are olrected towards
the speclfic problems that the end user wants to solve. Your
appllcatlon w11I most likeIy be in Ehis category.
P/OS services: These services help the user manage
Professlona] computet resources. Your apolication can use
these services ouring progran execution. Services are
ciescrtbeci in Section ?

P/AS prograriis are categor Lzed accoroing to

use in tlre Iist beIow.
are appropriate for ?/OS ate listed 1n the
Ief thand column anci P /05 System Services are listed in Lne righthanri

iJser aopllcatlons that
column.
USER

P/OS SYSTUM

tPPLICATICivS

SERVICUs

Phone dialer
General Ledger

Flle Services
Dis)< Services
Print -servlces

ChecKbook Program
l.{ortgage Proqram

Cornmr:nicat ions FacilitY
PR0SE text edltor

1.2 Program SEates
P/0S is a neh operat.inq system that has 1ES rooLs in Ehe RSX-1 1M-ptUS
operating systern. As such, iE employ5 man! of the satrre rneLhods of
rnanaging resources as the RSx f an'ily of syst.ens. For example, p/0s
uses chec<polntinq to move tasks from menory to disK to make effective
use of memory, it runs tasKs on a prloritv
basis to respond to
real-tlme events, anq it aIIo*s multitasxing so multiple tasKs can run

simulCaneously. the faclliCies for usinq t,hese features are fulIy
descrioed in the SYstesr Peierence Eaoual-. This section introcjuces the
i.mportant concept.s.
Programs inay be eit.her inEeract. lve or nonint,eractive, and the eno user

cannot alter

chis Droperty of an aoplication.

AFplications you

cjevelop must ce interactlve.
l:oninteractive progranrs, sucn as prlnI
services anti t,he Conrnrunications Facllity, are provided oy DIGITAL.

P/0S allows n,uLtiple noninteractive Frograrns (such es file print.inq
and file transfer to anofher syscen) tn rurl sln'ultaneously iritn a
single lnteractive oroqranr (such as PROSE). The inEeractive
apolicatlon has direcE control over tne Keyooaro ancj screen. .r.;hiIe
the nonint.eractive applicarj.on is 1n operatlon. it 1s not direcEly

P/OS CONCEPTS FOR APPLICATIOI\ DEVELOPERS

Page 2-3

connect,ed to the keyboard and screen.

2.t.2.L rnEeractlve Programs - whlle lnteractlve
programs are
runnlng, Ehe funct.lon keys on the Professlonal keyboard are passed to
the running task, excegt for t.he system functlon keys.
The
Professlonal keyboard and programming conventions are lntroduced ln a
subsequent sectlon of thls chapter.
2.L.2.2 lionlnteractlve Programs - tlonlnteractive Programs operate,
for the most partr wit.hout lnteractlng with the end user. After they
are invoked from a menu, nonlnteractlve appllca!lons can lnteract wlth
the end user only indlrectly through the ltessage,/status Board. p/os
reserves thls executlon envlronmen! for lts own use.
Hore than one noninteractlve appllcat lon can run in parallel lvith an
interaetive application.
NonlnteracE,lve applicat lons do not have
access Eo the screen or the keyboard.
2.1.2.3 Appticatlon Mul tltasklng - One program can actlvate another
by us ing an execut,ive system servlce and through Ianguage-speclfic
f eatures, sucn as CHAIII and CALIJ i n Pro/3ASIC-PLUS-2. Thus, an
interactive appllcation may lnclude more E.han one proqram. Cnapter 10
discussses this 1n more cietail.
2.2

USER APPLICATIOiiS

An appllcatlon 1s a computer program t.hat addresses the needs of an
end user. The execut,able part of a user appllcatlon 1s one or more
tas ks .

A Eask 1s Ehe runnable portlon of an appllcati.on. To create a task,
you must flrst writ.e a source program and, by grocesslng it through a
Ianguage processor, create an objecE module. You create the task by
subrritting the object, module to the Iasi< Builder. The Task Bullcier
creates a f1le containlng a task image which may be executed on P,/os.
To create the task, the Task Buirder accesses system and
user-speclfied Ilbrarles to resolve references 1n iE. Appltcatlon
tasKs can access commonly used P/0s subroutines whlch are cont.ained ln
resident llbrarles.
Resldent ]lbrarles are bulLc and installed-into
t.he system separately from tasks that might reference them. To build
a task that references subrot:tines conEained 1n a resldent ]1brary,
for each Iibrary you must speclfy a symbol deflnition file in the Eask
bullder cornrnand line. The symbol definltlon file contains links thac
resolve caIIs from wltnin the referencing task to locations within the
Iibrary.

P/OS CONCEPTS FOR APPLICATION DEVELOPThS

Page Z-4

In acidltlon to tasi(s, !he P/oS apolication has disK or olskette f i1es.
The files
contain the applicatlon menu, nessager Boo help files, as
well as ciisK overlays for Lasks in memory. These fi-1es reslde on disK
or oiskette durinc't application execution. fn Figure ?, they reslde on
provlde the user
the RD50 d1sk. Tne menu, message, ancj help files
lnterface for an applicat,ion.
The P/OS applicatlon also has an installatlon f11e on disl< with Ehe
other files. The 1nstallat.lon f11e contalns informatlon whlch dlrects

ProDlspatcher to instaLl all Ehe tasKs associated with this
The
applicatlon.
lnstallation
also names aII
flle
the
appllcatlon-relaEed fi.les.
The installation
flle provldes enough
informatlon to ProDisoatcher so 1t can start t.he application I or
lnterrupt and terminate lt.
2.3

/AS SYSTEI.i SERVICES

P/OS offers many services for manlpulating flLes on dlsk or disKette,
and for printing sEored files or displayed screen images. These
services are caIIed File, Prlnt, and Disk servl ces. P/0S provides a
text editor ( PRCSE) and Communications FaciIiEy as weL1.
P/AS also offers P.roBasic for end users ivho want to write programs.
However, slnce 1E is neither an appllcaE ion development toot nor a
cal"LabLe system service, ProBaslc 1s noE, dlscussed here.

2.3.1 File, Print, Ano Disk Servlces
File services allow Ehe eno user Eo coFyr rename, cielete, bacKup,
restore, append 2 DUrg€ r dlsplay and delete-protect flIes.
Files can be printeo if the system includes a printer. Print services
accepts commands to start,, suspend, stop, and continue prinC jobs.
Dlsk services allow the end user to initlallze diskettes, format the
hard oisk, ano o'uplicafe volumes. Dlrectories can be creaEed,
deleteo, and Iisreci.
CerEain File, Print., and DisK servlces are callable

aoplicatlon
servlces.
2"3.2

software.

Chapter ?

at run-time by
oescribes interfaces to callable

PROSE ANCJ P/OS COI'iMI.JNICATIONS F.ACILITY

editor.
PR0SE is intencied tor a business
environment anci is sultable for creaEing memos or entering ddt,a for
applicatlons. The end user presses arrow Keys on the P/AS keyboard to
move the cursor and edit or ent,er text. In acidition to t,he basic
edltlng funct.lons, PR0SE allows the eno user to move text seqments,
PR0Si: is Ehe P/0S text

p/OS CCTiCiPTS FoR APPLICATI0Ii DL:VELOPUR'S

Page 2'5

6upIlcate texE segments, set nargins, ano perform gIobaI search and
replace of specifled text segments.
p/0S Communications Facllity includes File Transfer, Termina]
Emulation, ano Ielephone l{anaqement Syst,em.
To use Termlnal Emulatlon, you can connect the Professlonal to a host
computer vla a IocaI connection or a t,elephone Iine connect,lon. You
can use the Professlonal as a VT102 or a VT125 Eerminal through the
Communlcat,lons Fac111ty. As a VT125 termlnal, the Professlonal
lnterprets REGIS code sent by t,he host. The Communications Phone Book
1s used to store and retrieve communlcatlons Ilne and host
characterist. lcs.
Ihe FiIe Transfer service allows data files to be passed beLween two
professionals or between a Professlonal anci a host running VAX/Vl,tS or
RSX-1 1l{/H-pLUS. Io use FlIe Transfer, the Professional must, be 1n
Terminal Emulatlon mode.

The Telephone Management System (Tl,S) integraEes Ehe use of t,he
telephone for volce and data comfirunlcations into the ProfesslonaI.
Any of the functions t.haE can be performed using the KernaI
Communication port can be done wlLh the Telephone l'4anagement Syslem.
The Phone Book
This inclucies file Eransfer and ternrinal emulation.
voice and data calls.
can be used to inltlate
PR0SE and Communications FaciIlty are calLable at run-r1me by
applicatlon software. Chapter 1 1 describes inEerfaces to calIabIe
services.

P/OS CONCEPTS FOR APPLICATION DEVELI]PERS

2.4

Page 2-6

USER IIrTERFACE SERVICES

lnterface enables the end user to lrlteract witn
appllcat,ions and P/0S services through a serles of menus and forns.
It provides a simple method for selecting activities by positionlng
the pointer to items on menus or by typing the ltem on a conmand llne,
fllIing 1n bfanks on forms, and Pressing labeled function Keys.
0n-Iine text provldes helpful lnformatlon whenever 1t is needed.
Hessages are dlsplayed Eo lnform the user of errors or confirm
completlon of an activltY.
your appllcation can use P,/0S Service Routlnes t,o provlde the same
Service routlnes t.o access
user lnterface for your applications.
are
oescrlbeo
in ChaPter 13.
message
servlces
menu, help, anci
TDe P/OS user

2.4.L

Menu Servlces

The end user interacts wlEh P/OS services through menus. Menus are an
efficlent command interface for both novlce and experienced computer
users.

of commands. Like conimand Ilnes in other systemst
the menu options a.re used to direct. P/OS to perform useful functlons.
The top
The nenus supplieci with P/oS are organlzed in a hierarchy,
Level fiain Menu branches out lo related rnenus. The Xain Menu lists
categories of P/0S services. After the end user slgns oD, the main
menu appears anci t.he end user select.s a submenu or P /OS servlce. VJnen
the end user stops using a service or an appllcation ' the drsplay
returns to the ain Henu.
Figure ? shows the oisk-based P/OS nienu system as it appears before
any opt,ional appllcations have been added.
A menu 1s a list

l'1

Pag e 2-'l

P/O.S CUNCLPTS FOR APPLICATION Df,VE:LOPLRS

Prelihinary

[,AIN MENU
FIVE (5I
OPEN SLOTS FOR

VIEW
MESSAGE/STATUS

PFIINTER MENU

DISK & DISKETT€
SERVICES MENU

Figure ?: DlsK-Dased P/0S Menu System
After purchasing a P/0S appllcation, the end user integrates it into
his system with tne InstaIl program. The InstalI progran acios the
name of the appllcat,ion to a menu so it can be invoked. The end user
rnay add the appliction naine to one of five si-ots on the aln Henu or
on an .4dditionel Applications submenu. Tnls group of menus is
resetved for user-installed apolications on disk-baseo P/OS (the
lJserjs GuIde descrioes the application installation service),
0n cjisKette-based P/OS, applications are pre-installeci by the
applicat1on developer. The Maln l4enu has an entry for using
aoplicatlorrs contained on another cjiskette. To run an application
residing on a separate diskette, the end user selects that opEion,
f€fTroVps the currenL system dlskette, and replaces it with the
t'1

Page 2-8

P/OS CONCEPTS FOI{ APPLICATION DEVSLOPERS

In addition, the P/OS main nenu has t.vJo open
alternate diskette.
s1ots. r.rhen you create an application for P/0s, you mus t place an
entry for your apolication on the P/oS main menu, Flgure ? shows the
dlskette-basecj P/0S menu system.

TWO 12)
OPEN SLOTS FOR

APPLICATION MENUS

RUN

APPLICATION ON
ANOTHER DISKETTE

PRINTER MENU

OISK & DISKETTE
SEFVICES MENU

Flgure ?:

Diskette-baseci P/0s lenu 5yst,er0

Each appllcation must have an entry on either the main nrenu 1n

dlskette-based P/0S or either on the naln menu or the Acidltional
Appticat, lons fl.enu on disK-based P/0S. The enci user invol<es an
aopIlcat,lon by selecting the entry for 1t from one of the crescrlbed
menus. lriost applrcations requlre additicn;lI ITrcous or submenus throqgh
whlch the user interacts with the applicat,ion.
ISSUUS:

P/0S C0trCePTS Fu'lR APPTICA II0N ITEVELiJPER'S

Hor,r does appllcat ion developer
diskette-based P/05 n ain flr€Du?

Page 2-9

put appLlcation n6me on

2.4.2 HeIp Servl.ces
lnformatlon about the currenL actlvlEy at the
touch of the HELP key. The help lnformation is elther general
lnformatlon about the current appllcatl oD, or specific infornation
about a slngle command.
You can use P/OS help services to dlsplay help lnformatlon for your
appllcatlon.
HeIp is dlsplayed ln frames whlch can be organlzed ln
para]1eI to t,he aoplicaCion menus. That 1s, each menu for your
appllcation can have an assoclated Help frame. iihlle using your
menus, the end user can press the hELP key to dlsplay the associated
P/OS displays helpful

HeIp frame.

In acjdltion to naving a Help frame assoclated with each menuT you can
have a HeIp rnenu that Lists Ehe ciifferent. subjects for whj-cn on-line
HelD 1s available. A Help meou can have a hierarchlcaL structure,
using the PREV SCREEN and IiEXT SCREEIT i<eys to dlsplay the approprlate
HeIp frames.

If the user presses the RESUI-1E key while a Help menu or Help frame ls
belng displayeci, che screen reverts to tne state it was in before the
HELP key was presseci.
Applications that do not nave menus may use P/0S Serv 1ce routines to
display help frames dlrectly. In thls case, if the user presses the
displayed, Ehe
RESUHE Icey while a l--Jelp menu or !leIp frame Ls oeinq
aopllcation nust resEore Lhe screen to the st,ate it was in before the

HELP Key 'rras oressed.

If the applicacion uses PR0/FflS-11 forms, help may be provldeci through
tne FHS-11 help structure. The Fl'iS-11 Form Drlver of f ers tvro IeveIs
of help 1f the user reguests it: help for the form fleld !n whlch Ehe
crrrsor is Iocat.eo and nelp for the entire form. The former 1s
displayed the flrst time the user presses tne help key; the latter is
cisolayed the second time Ehe user presses the help Key. P./tJS help
services may be used in conjunction *ith Fl'15-11 helo' or it may be
used instead of Fl4S-11 heLp, Tne EBCIEAS=II DocuceDtalloD Supp.IetreDt
describes PR0/Fl{s-11 nelp 1n more cietail.
2.4.3

i.'l

essage Services

Your applicatlon can use P/OS Message Services to store and reErieve
These messages can De di:played on the screen during
text strings.
progtallr execut,lon or they may be used for lnter-tasK communlca!1on.

P/OS CONCFIPTS F0R APPITICATION DEVELOPERS

Paqe 2-L0

2.4.4 Message/Status Board
The Hessage/Status tsoard displays system status tnforrnation, such as
t'ne names of the volumes 1n the dual dlskette drlve, as a service to
the end user.
Your application can use the i(essage./Status Board during program
executlon to post messages dlrected to the end user. The P/os service
routlne to do thls 1s 1n the P/os services Llbrary, described in
Chapter ?

2.4.5 Functlon Keys
The Professlonal. KeyDoard 1s shown in Figure ? (Flgure ?

shows the
version of the Professlonal keyboard. Illustrations of Ehe
u.s.
other l<.eyboards supported by the Professlonal can be founci 1n the
0r+ner's 4anual. ) The keyboard has Ehe main typewriter keyboard, an
editlng keypad, a numerical keypad, ano keys that may be assigned a
speciflc function oy appllcatlon soft,Hare. These funct.ion Keys are on
the top rovl of tne keyboard anci 1n a cJuster bet.ween the main l<eyboard
and the nuinerlcal keypad. The IabeL strlp above the keys identifies
Eheir funct tons .

P/OS CONCEPTS FOR APPLICATIOfu DEVELOPERS

Figure ?:

PAqE 2-LI

Profes s lonaI Keyboarci

T trn[tr]
l tril8ilN
T trtrilun
trtrtrtrL1

!
I
o

:o o
c o
z

HHE

E EHtrtr

tr ililtr

z z
o

;!
fta

E EEF-n u=#u
f tr=fiE.-,

trHfitrI

HEFHI

= HEHHI

EHEHEH

L_iu

P/CS CONCEPTS T-OR APPLICAT'IOh DEVELCPEKS

Page 2-I2

2.4.6 operatlon 0f Functlon Keys In P/oS
T.abIe ? llsts the general oPeration of functlon keys in the P/0S
Jnvlronment ano gives at Ieast one example of how each Key 1s used ln
P/0s. This lnformatlon 1s not a conrPrete descrlPtlon of Ehe operatlon
of functlon Keys for P,/OS or for P/oS servlces. Rather, it 1s
lntended only as a gulde to help you determine the best usage for the
functlon keys when you deslgn and wr1t,e your appllcatlon. See the
User3s 6ulde for a compLete descriptlon of how an end user uses the
functlon keys to lnteract wlth P/cls and P/os servlces.

Paqe 2-13

P/OS CoNCEPTS FOR APPLICATI0TT DEvELOPeRS

Table ?:

General Descript.lon of Functlon Keys

ITEY

RESULTII'IG ACTION

ADDTIiL OPTlONS

A key used to displaY

additional optlons for the currenE menu.
If additional oPtions have been
deflned for the current slngIe-cholce
menu, pressing this keY dlsPIaYs
a separate menu with the acidltional
optlons.

Used in PROSE to offer oPtions for

formatting.

text

The up and do?n arrows are used
1n P/OS to move the selector on menus.

Arrow KeYs

by industry convent,lon, thls function key is
only used in comtnunications sofE.Hare to cause
a breaK conditlon on a communications
Ilne.
Used in all P/OS menus to dlscard anything
typed so far ano to reset the selecEion

BREAK

CAIi CEL

Proces s .

Indicates that a selection from a menu
has been made. The current P,/OS servi.ce
takes action if an unambiguous selection tr'as

made.

used by PROSE to display an Exlt menu, frorn which
the end user Ieaves the text editor and returns
to the P /os Maln l.1enu.

EXIT

Also used by ProBasic to Ieave the ProBasic
interFreter anci return to the main menu.
t'o search

FIND

Used in PIiCSF.' the text editor'
for part.icular text seqments.

HELP

A key used to display information
instruction to the eno user.

.
HoLD SCREEN

and

At the P/oS t"ialn {enu, ciisPlays a He}p frame
describinq hot{ to use the menu systen.
A subsequent. request for heIg resLllts in
a dlsplay of an P/0S FieIp menu. The Help
menu provlcjes access to HeLp for each
P/0S service ano f'tncElon KeY.
The screen lmage stays stiII so
1E can be read. 0utPut to the

Page 2-14

P/gS CONCEPTS FOR APPLICA ION DEVLTOFEI(S

screen conElnues when any key other tllan
PRITIT SCREEN j.s Pressed.
INSSRT HERE

INTERRUPT
|IAIN SCREEN

NEXT SCREEN

Numbered

function

USCd lN PROSE IO AI1OW IEXt tO
be lnserted raEher than overtyPed.
stops the current actlvity ln P/oS system
servlces if f oLlo'*ing by D0 l<ey. 0theruiise r
no actlon.
A function key used to return the
dlsptay t,o a cent.ral polnt 1n Ehe current
context.

In t.he P /OS menu tree r returns the
dlsplaY to the P/0S l'{ain Menu.
A funcEion key used to vlew
a cjlsplay that Logj.cally follows the
current oisoIaY.
Used in PR0SE to move tne cursor forward
one screenful in the text f11e to display
the next screenful of text..
In P/as, Ehese keys are not used.

keys

PREV SCREEN

A function key used to vlew
a cilsolay thaE Iogically preceoes the
current oisplay.
Used in PRCSE to move the cursor bacK

one screentul in the text file
the next. screenful of text.
PRINT SCREEN

R EI.lOVE

RESU14E

to display

The screen remalns still so the 1na9e can
De printed. If the printer supporls tnls
f eature ano 1s conDectecJ, in i*<lrking
order and is not, oeinq used, tlie

current screen is prlnted' preceded
by a fornr feerj, lf. Ehere is no prinEer
connected or if the prinEer is not
worKlng, an error message is displayed. lf
the printer is busy, a message reports thaE
to the end user. Input anci output' t'o lhe screen
continues iYnen any Key other than H0Ltj SClilEN
is Pressed.
used by PR0sE to erase text.
A functlon key used Eo resurne
an activit,y.

P/OS C0IiCEPTS FOR APPLICATI0h DEVEL0PERS

SELECT

SETUP

Paqe 2-L5

In P/OS, thls keY is used to ret,urn
to the current activitY after
use of tne HELP and ADDINIT OPTI0NS Keys.
iJsed in mu1Eiple-choice menus to cnoose
[rore than one ltem before pressing
the D0 key.
Used in PROSE to inark some section
of text for a subsequent operatlon.
Displays the SETUP menu if pressed when the
P/0s Main l'renu ls disp'layeci- The SETUP menu
aIlows you to change certain Professional
hardware characteristlcs.

2.5 P/OS SYSIEl'{ C0 j'{PONENTS
This secEion oriefly descrloes tne P/0s system componenLs: resldent,
lJ.braries, RSX/EXEC, and ProDisPatcher.
Figure ? illustrates the flow of control durlng system execution
bet'r{een application fasks and P/AS sof tware components. The main P,/0S
software cornponencs are clust.ered resident Iibrarles, ProDispatcher'
and RSX,/Exec.

Page 2-L6

P/OS CONCEPTS FOR APPLICATIOI{ DEVELOPERS

Flgure:

FIow of Control At Run-Tlme

\sL ;

. h?Q\.tryNsrr -\cg,kJ

-1-

/l\cql\9

CauuS

1qp4.yA(r€ OTS

\
'''
\\

'J)rr<|rrrJ

,\n

/,\rttq\rv?J

)q,. c-4,\rr< 3

f(sx \ €. '."
t Xf,O

\.,.i r

-196 ;t6'o

lv-"i.
Q rOs

;-\-

llt.;'1t---:i

es,rt
cs'l
lmrs\€{----.
i-

fu, +J crrs
o{\
Qro\rc+\,on
, t\
ql'tsL

1.r--.t I

\,J.

iQn\roll
-\r
I \CL\N\-

Kc1\o o r 6

P/OS CONCET-TS FUR APPLICATIOh DEVELOFERS

Paqe 2-17

2.5.1 Resicient Clustered Libraries
Resident llbraries provide a slngle copy of commonly used subroutines
in a tray whicn can De shared by several EasKs. Apolication t,asks may
be task built against these libraries on the host system" The
Librarles are not part of your application's Eask imaqe, The p,/0S
reslcient clustered lioraries are as follows:
1, Record 14anagement System (Rf"r S-11) provldlng record management
services

2. Language 0bject Tlme System (0TS) proviciinq language-speciflc
run-t,ime support to hign-leveI languages
3. Graphics Primj.tives providing subroutines for creatlng
graph i c s

P,/clS Service Rout.ines providing

ubroutines f or dlsplaying

menus, help t.ext, and messages on t.he screen f rom a data base
on disk or oisKeEte

Resicient clusterec Libraries have the following characteristics:

- 1. Prebuilt as an integral part of the o.Deratlng system. The
apolication oeveloper cannot add resldent libraries to t,he
system.

Cf usterecj so aII

acidress space.

.Llbraries are mapped into the same vlrtual

3. Not part of applicat.ion f,ask image but do use virtual
space

address

f ssues:

Define clustered from RSX TKB V2 manual--

Do Applications

tasl< bullci against RCL using command fi.Les?

2.5.2 ProDispatcner
The ProDlspatcher controls the P/OS main menu and user interface
services through which t.he encj user interacts ui Eh tne system services
anci ap'pl1cat. lons. The ProD j.spatcher perf orms tne f ollowing:
1.

Adds the name of the applicat.lon to the user-specified
menu
proqram ca1led IIJSTALL,/REliOVE. By
through an lnteractive
selecting the appllcation name from the ntenu, Ehe encl user
can run the application.

Page 2-LB

P,/OS CONCgPTS FOR APPTICAIION DEVELOPEi(S

Ehe application tasks to the 11st of
executable tasks, calIed tlre syster, task directory (STD).
Flgure ? shows ProDispatcher issuing cilrectlves to RSX/Exec
to accomplish thls Job.
Invokes, aborts, and removes tasks. Hhen the end user
selects an appllcatlon from a menu' ProDlspatcher starts the
first task for that applicatlon. lf the end user presses the
INTERRUPT key followed by the D0 key, ProDlspatcher aborts
the running appltcatlon and removes any tasKs Ieft runnlng.
Adds t.ne name of

ProDlspatcher uses the Appllcatlon InstaIIaclon file (through
the Install program) to record the name of the first task to
be invoked for thls application, and to keep track of a1l.
related Easks. lf the appllcatlon developer specified
default menu, heIp, and messaqe files in the insta]lation
fiIe, ProDispatcher lssues calls to the P/0S Servlces Llbrary
to open these files i{hen the appllcaton is lnvoked.
4.

2.5.3

Recovers the system after disabling errors have occurred in a
if a t,ask faiIs, control returns to
running appllcation.
ProDlspat.cher and tne main menu 1s displayed.

RSX/Exec

RSX/Exec is

the controlling program in the P/As operatlng systern.

maln cjutles are as f ollows:
1

Provides

incertasK
allowing
ProDlspatcher
applicatlon-related jobs

Its

cor,rmunlcatlon mechanlsm to
out
lts
to
carry
lt

2. Contains executlve oirectives rhich are accesslble throuqn
may be used by
macro calls,
Executlve directives
apollcatlons go obtain system informatlon, such as the date
and Elme, and to cont,rol. applicatlon execut, lon, such as f or
multit,asklng.

Provides access througn cievlce cirlvers
dlsKette drive and the RD50 haro disl<.

Ehe RX50 dual

Rsx /Lxec
ls
inserteo ln a drlve,
'rhen a diskette
adds lts narre to the Iist o f available volumes.
automatically
/h€n the dlsketEe 1s removed, tne name ls removeri. The end
user is not. regulred to perform devlce rTrount and olsmount.
P/OS DisK servlces provide access to the end user to media.

4. Provides the on-dlsk flle structure and record management
system (RllS-11). P/0S F1l.e, Dlsk, and Princ services Provlde
these facllitles to Ehe end user.

P/US COIiCEPIS FOR APPLICATIOh DEVELOPERS

Page 2-1.9

Provides access through tne termlnal drlver to the termlnal
control Eask. Tne terminal' control task cont.t oIs the vicieo
lmage and the keyboard. Applicatlons can use ProDlspatcher
servlces and P/OS Graphics to dlsplay images on the screen
and interpret keyboard input.

Provldes access through the terminal drlver to the prlnter.
The PRINT l(ey and P/oS prlnt servlces allow the end user to
prlnt flles on the prlnler.

ISSUES:

Add more 1nformatlon relatlng

acEivltles to t,he figure.

P/0s c0 rr crPTS FOR APPLICATlOII DEVELOPEFS'
PART II

APPLICATION DEVELOPMENT CYCLE

Chapters 3 to 9 descrlbe tl're program development cycle for P/OS
applicat,ions.
Tne sIeps ln P/0s appllcation development are as

follows:
1.

Identify the Professlonal software and hardware configuratlon
for your appllcatlon

Deslgn the application

Deslgn the appllcation's accompanylng cjocumentatlon

6.
7.
8.
o

iirite the appllca!ionr application user interface and,
optionally,,Software security Program
Task bui Id the AppLlcation on host
i/irite the applicat, lon lnstalIatlon file
Iransfer the application to the Professlonal
Instal I, execute, and debuq the application on P/0S
CreaIe a P/0S cilskette with the Applicatlon Diskette Euilcier

First, yoo must. decide whether to creaEe a diskette or ciisk-based P/0S
appllcation, or bot,h. The factors lnvolved 1n t.his decision are
presented ln tlre next chapter.
Next, you desi.gn the application and 1ts docuiitenEation. Ibe
Applj.cat'l.oa Desigo 6uide provicies insignts into design issues. It
lnctudes a sample application *nich illustrates the discussion.
To guide you 1n ltrit.ing documentation for your application, the Tool.
Kit lncludes Ehe Docunenlalioa Guideliaes.
Aft.er Oeciding which sys Lem you ivant Eo create your application for r
you can wrlte tne applicatlon and the apolicacion user interface.
Cbapter 4 descrioes all the tools you wiII neecj to accornpllsh tnis
stec. t'lany of the apolication ceveloprnent, tools are described in
beparate documents or docurnent sets. 0thers are fully descrioed in
Part III of this rnanual. Chapter 4 Iists ciocunentation references for
eacn fooI.
The TooI Ktt provides an optlonal mechanism wnich a.Llows Producers to
protect E,heir applications from unauthorized reDroduction. Ihe
producer can ouilC a subprogram int,o his appllcation 'rhicn wiIl
be caIIed by P/gS h'nen the end-user aEEelnpts t.o install
automat ically
or run the program. The subprocram 1s pas:ed the ilarci,r,are CPU ID
number as a parameter. The subprogram perforn' s an encryptlon on the
CPU ID whlch yields an aosolute Key. nhen the end-user instalLs the
appllcatlon, lre is required oy !he INSTALL program to enter a Key

P,/OS CONCEPTS FOR APPLICATIO}I IJEVf,LOPEKS

(called Ehe "t,entatlve key" ) which he has recelved from the vendor.
If the tentaclve key does not maEch the absolute key, t.lre appllcatlon
*rL1 not be installed.

If the keys match, then the tentative Key 1s stored 1n the appllcation
as it is inst,alled.
Each time the user attemDEs to run the
appllcatlon, the stgred lcey 1s retrleved and re-valloated against the
CPU ID. If the valldatlon falls r the appllcation 1s scratched from
Ehe pacKage. This
memory, and Che user 1s advlsed to re-lnstaIl
prevents a user from sharlng h1s dlskettes wlEh another user.
The Producer must provicie each authorized user with the Key wnlch w111
unlocK the appltcaClon so 1t may run on a gj.ven CPU. The Key may be
dlstrlbuted in many ',{ays. For mail-order business, the purchaser
should be requested Eo enclose his CPU ID number on his order form.
The resuLtlng l<ey can be prlnted on a labeI and sent wlth the
kit.
distrlbutl0n
For volume,/retail bus iness , a telephone
registration sysEem may be the best method for trac)<ing sales and
distribucinq keys. The vendor will call the registration center,
givlno Ehe nane and CPU ID of the purchaser. The Producer's cent,er
will record the customer lnfornatlon, and run t.he end-user's CPU ID
through the encrypt,ion al9orlthm. The result.ing key will be read to
the vendor, who can then give lE to the user.
Appllcatlon protecrlon is optional.
If you wlsh to distribute
unprotected copies of your appllcation, you neeci not. ''.jrite the
encryption prograrn, In tnis case, 1n the Apptlcat,ton 0i skette Build
phase of program development, ans\yer 'rNOrt to the guestion, "Is Key
Protection deslred?",
Before you 9o on, consider the termlnaL you wiII be using to create
rhe applj,caton. 0ne way to create a f11e that contains program
language source statenrents is to log on to t,he hos t f rom a termina I
and use a text. editor to create t.he ti Le. Another way to do this is
to use t.he Professional. You can either use Ehe Professional as a
workstaEion (as a terminal to the host) or as an inciependent, sysEem.
As a ltorkstation, through P/0S Communications Fac1llty you can log on
to the host and use any edltor to create source code, vlichouI Ieaving
the Professional, you can create, con'pi.Le, ano ouild the task image on
the host. To run and test, t'he applicaLion, vou can transfer it to Ehe
Professional using the P/0S File Transfer FaclIity,
As an independent system, you can use PR0SE (Ehe P/OS Editor) to
create your source file on t.he Professional ano store it in a dlsk
fiIe. You can examlne, delete, ano change it. until you are reaoy to
comolle and bulld the application. Then, use P/0S File Transfer to
move your tile lo the host and build the task lmage
To qetermine'wnetner to use the Professional or another terrninal to
creat,e the aoplicatlon, consider 'wnetner you want to use the 8-bit
characters frorn tne DEC MuICinat lona I Character SeE which the
Professional supports.
The trEc llultinatlonal ctraracter set, represents characters wiEh an

/AS C0NCEPTS FOR APPIJICA tI0N DEVELOPi!<S'

supijort 7-b1t
8-oit code. Tool Klt hosts anci their utilities
and utllit.les
the
aIl
of
languages
Hohever,
representation.
character
1n.- the TooI Kit support iJ-bit characters. (tiote Ehat l'{ACR0-11 does
not'support 6-bit characters as lnput in source programs.)
To generate 8-bit character codes' either 1n a flIe or as interactive
lnput to a Tool Kit utillty, you must use the Professional. It you
are uslng a VT100 or another termlnal to create appllcatlons on the
host r you cannot enter or dlsplay 8-blt characters on. 1 E. Chapter ?
descrlbes the DEC Multlnational Character Set ln more detail.
yJhen you are ready to create appllcatlon tasksr You must use Ehe host
Task Builder. Chapter 5 illust.rates t.he task build procedure.
To run the appllcation on P/OS I the appllcatlon must have an
Chapter 5 describes how to create one.
application lnstallation file.
To run and test the appllcatlon, cransfer it to the Professional using
P,/OS File Transf er. Chapter 7 illustrates this proceciure.
AfEer transfering tne appllcation tasks and installation fiIe, you can

execute, and debug the apPl ication on P/OS. ChapCer 8
descrlbes how to do this.
i(hen the applicatlon 1s cjebugged, you can create a P/0s disKeEt.e }Jith
the Appllcation Dlskett,e BuiIcier. Chapter 9 describes Ehis Procedure.
The followlng figure shows how to use tne ilorkstation to create a P/0s
appllcation progra'n.
ins taIl.,

/OS CUtTCEPTS F0R APPLICATI0Ir DEVUL0PEi(S

Page 2-23

Figure: Program Development. Cycle

WORKSTATION
HOST SYSTEM

Convert for

Application
Execution

Create Forms

Source Prooram
f ile.MAP

. memory
all ocati on

TASK BUILD
Creates -TSK

Symbol Tables
Language Libraries

map

Definition tiles

cREATE AiPLIcAJ
INSTALLATION FILE

DISK ETTE

CHAPl'ER 3
SELECTING SOFTWARE COHPONENTS FOR A PROFESIONAL APPLICATION

developer has in
lhis chapt.er presenLs options an appllcation
opEional
softt/are for any
with
and
required
application
an
combining
inoivldual harcjware conf lguratlon.
3.1

PROFESSIOI,JAL HARt,I*ARE CONFIGURATIONS

The Pro350
The pro325 hard*are supports the dlskecte drive on1y,
5l'1!i disk.
cjrive
optional
and
the
oual
disKette
the
hardware supports
The professional operatlng system (P/0S) may be configured as diskette
or disk-based to supporE the Professlonal hardware conflgurations.

3.2

Pii0FESSI0NAL S0FTxAR0 CoNFIGURATI0NS

Dlskette-based P/0S runs on bot.n Pro325 and Pro350.
runs on Pro350 if the optlonal haro oisk is adcjeo.

Dlsi<-based P,/0S

For dlskette-oased P/OS, the system and services reside on the base
d1s)<et,te. For most operatlons, the base or systerr oisKette nrust be
l'or otner
inserted and remain in t.he cirive v;hiIe ?/AS 1s runnlng.
sof
t',tare is
cogy
system
diskette-to-oiskette
f
l1e
as
operatlons, such
r
flxed 1n memory so tne base disKette nay be removeci ancj replaced by a
data dlsxetLe.
nppLlcation tasKs targeted for the dis<ette-Dased systetn must be
pre-lnstaIIed
on the base dlsKette with tne operating system. If a
user ivants to use an apol icat ion that, does not res ide on t.he base
diskette,
he selecEs RUrr APPLICATION F;t0i.t ANtiTHER DISKETTE from the
menu, To run tne aoplication, the second disKet,te must be inserted
and started.
To a1loiv use of a data olsketEe, an applicatlon tasK nay
fLx system soft,eare in rnemory or iE may sDa*n a Eask from che seconci
dis)<ette, aIl-owinq t.nat dlskette to be removed. The SysLeE Bef'ereace
and Parent /offs pring tasKlng 1n
Ataoual explalns the F IXS directive
detall.
For cjisK-Dased P/OS, the sysLem resloes on the ciisk so the dual
The ciisK in thls
cirlve is f ree f or use f or dat.a disKettes.
diskette

SELECTING S0FTwARE CiTMP0NgNTS F0R A PROFESI0NAL APPLICATION Page 3'2

tne disk 1s the
conflguratlon 1s equlvalenc to the base dlskette;
base or system disk. The disK-based syst.em has an InstaII Droqram to
As applications are
copy appllcatlons trom a oiskette to the dlsk.
in'sEallecj, the application name 1s entered on a nrenu. Thereafter, the
user invokes the applicatlon from the menu and saves tne dlsket,te as a
backup copy of the applicatlon.
Appllcatlon tasks targeted for dlskette-based P/0s must be bundled
wlth the syst,em on a dlskette. You may select one or more of the
callable P/OS services, one conflguratlon of RMS, and one 0TS to be
task built wlth t,he applicatlon tasK. AtI selected components must, be
copied to Ehe disKet,te.
appllcatlon tasKs targeted for dtsk-based P/0S may reference one or
more of Ehe callable P/os servlces and be bullE agalnst the requlred
0TS and full RflS. Hol{ever, except for Communicatlons, the target
system lncluoes these softfiare components. They are not bullt into
your appl.lcat,ion's task image. (Task Builder oetions to reference
these librarles are presenteci in Chapter ? )
Table 3-1 shows the possiole conflguratlons
meoia for dlsK and dlskette-baseci P/0s.

of software components

For diskette-based P/os, the not,ation 0n base dlsl<ette indicates thaE
a software component must reslcie on the base or system dlskette
For ciisi<-based P/OS, system sof t'dare components reside on the system
Tne not.ation 0n DisK incjicates that, a sof tware
or base disk.
conrponent is part ot t,he targeE system. The not,atj.on 0n nppllcatlon
Diskette indlcates that a softt{are component 1s part of the
applicaEion task rhj.cn 1s insEaIled into the system.
In t.he table, t,he Ief t.hand colunn lists t.he sof tiyare components which
can be comolneci to create an appl ication package, The righthand
columns llst the sysEems.

SeLEcTITJG SOFTdARi C0MP0tiEiiTS F0k A pRuFEsIoltAL AppLIcATlCil

TabIe 3-1:

Application

SOFTWARE

page 3-3

Pacraqes
DISKETTT'.BASED P/US

DISK-BAsED P/OS

C0l'1P0N EiY T

Apprication
task Lmage(s)

0n base dlskette
0n apprication dis)<ette
or on supplementary to be inst,alled on
dlskettes
dlsK

Applicatlon's
l{enu, herp,
message files

0n base disKette

Application's daEa
f 11es, form f 11es
P/OS

0n applicat,ion dlskette
to be installed on
dlsk

0n base diskette
0n apprlcatlon dlsicett.e
or on supplementary to be install_ed on
ciiskette
disk
on base dlskette

on disk

ResidenL Iibraries
Language Object
Time System

0n base dlskette

On dlsk

P/oS Servlces

0n base dlskette

0n di.sk

RhS Full

r-,rpEion on base

On ctlsl<

RT.S SUbSEI

0pt.ion on base
oiskette

fiot an option

(RSX/Exec)

(ProDispatcher )

disKette

CalIabLe p/OS Services
FiIe Services
Optional on disKeE,t,e 0n dlsk
Print Services
0pti.onal on diskette 0n disk
Disk Services
Optional on di.sKetCe 0n disk
Editor
Optional on cjisKette 0n drsk
comnrunications optional on disket.te 0ptionaL on epprication
facillties
oisKetre to be installed
on ciisr
CallaoIe Sort
dptional on oisket,te Optional on application
diskette to be installeo
on ciisK
If you are wrlting an applj.cation tor both tne cisl< and disKette-based
syst.ems, ttro versions of tlre applicat1on mu:.t be creat.ed.
ost of the
source code can be used for both versions; however, at a minimunr , the
Eask bulloing
process
is oifferent
for each verslon of the
application.
Chapter ? explalns how Eo use the TasK buil.oer to
|.1

SELECTING S0FTi{ARE C0llPouENTS FOR A PROFESI0NAIJ APPLICATION Page 3-4

rebutld an applicatlon to run on both systems
Tle appllcatlons may be packaged on diskettes accordlng to thelr slze.
If they flt, appllcatlons for both hardware conflgurations may reslde
on a slngle dlskette and be sold for one prlce.
ISSUES:

1, For dlskette-based P/0S, does the developer seIecE
language 0bject tlne system to lnclude on dlskett.e?
2. i{hat, 1s the Rl'tS subset?

3. Applicatlon Dlsi(ette BulIder has to ask whlch language 0TS
the application requires.
4. Are FlIe ano Disf services callable?
5. This table wiII show in-core slzes of P/OS llbraries
modules; disK layout.
5. Does dlsKette-based system have an IITSTAIJt program?
7. iihat else needs to be said here?

and

CHAPTER 4
TOOLS FOR hRITING THE APPLICATION

Thls chapter introduces the soft.rrare tools you w11l need to develop
Each software developmenE tool is eiCher fuIIy
P/OS appIlcatlons.
described 1n thls manual or 1t ls descrlbed 1n a separaEe manual or
manual set.
References are provided to complete documentation for
each softtlare tool. The lool Ki! DocuneDtatioo Direclorg contains
abst,racts for t,he separat,e manuals referenced here.
If you have never developeci a program on RSX-11r'{/H-PLUS or VAX/VHS,
the BSL=11.!1.21{=9LUS Gulde lo erog!aB OeuelopeeD! and liAX,=11.1&SX:11
Useris Gui.de provtrde orientatlon.
The Tool K1t. offers the follcwlng program development tools:
1. Programminq Languages
2. Forms :'ranagement System ( PRClF MS-11)
3. Record Fanaqement, Services ( PRO/RllS-1 1 )
4. PRO/Sort
5. P/OS Servlces Llbrary
5. PRO/Graphics Library
7. RSX acro Liorary and SYSLIii (Syste'n Object Liorary)
8. Frame Develooment TooI (FDT)
1,,!

4. 1

PROGRAI,iI'1I NG LANGUAGES

TooI Klt development Ianquaqes include
and PDP-11 F1ACR0-11.

PR0/3ASIC-PLUS-2, PRO/DIBUL,

TO0LS FOIi l{RITING THE APPLlCAI'IOrv

4.1.1

Page 4-2

PRO/BASIC-PLU5-2

PRo,/BASIC-PLUS-2 1s a programming Ianguege t,hat uses famitiar words 1n

SimpIe statements and famlllar

operations.

matherrratical notatlons to perforrn

rf your Tool Ktt host is vAX,/vf1s, use pR0/BASrc-pLus-? ln
Compatlbllity mode. The related documentation llsted at the end of
thls sectlon describes descrlbes operatlonal dlfferences bet.vJeen
BAsrC-PLUS-2 on RSX-1111 and BASIC-pLUs-2 on vAXlvHs in Comparlbtllty
mode.

The PRO/BASIC-PLUS-2 language processor is composeci of a compller and
an 0bject-Tlme System Library. In addition to the eLementary BASIC
statements, PR0/tsA.SIC-PLUs-2 features terrnlnal-format f11es,
arrays, RMS I/O, extensive strlng manlpulat,ion functions, Virtual
matrlx
package handllng operations, and Iong varlable names. Statement types
include IF...THEr{...ELSE combinations, 0r,l ERR0R condltion nandlers,
and the stateftent modifiers rl.', tiHrl,e, uNLEss, uNTrL, and F0R.
User-def ined f unctions are supported. HuItlpl-e stat.rr ents may be
lncluded on one J.1ne, ancj a statenent, may cover nuttipre rines.
rn
ado'1tion, external subprograms may be accessed through the SUB, CALL,
C0Fr MON s

tat,ements.

Docum en t.at 1on

P8,O./8ASIC=PLUS=2 Docutreolatj_on Suppl_etreD!
The PRO,/BASTC-PLUS-2 Documentat.ion supprement describes
f eatures of PR0/BASIC-piJUS-2.

the special

PoP:Il EASIG=PLUS=2 rnsrarJ.alioo GuidelBel,ease Lloles
RdCTC

Dof

aranaa

M:^rr51
Easgs4

EASIC Useris Gulde
BASIC oo 8SI:ILAJ!=PLUS Systetrs

4.1.2

PR0,/DIBOL

PR0/DIBtiL 1s DIGIIAL's Buslness tlrlented Language. lt 1s slmilar t.o
C0B0L in that is has a DATA DIVISI0N ancj 1E uses English-Iike
procedural statements. Drb0L enables data manipuraEionr BrithmeElc
expression evaluatlon, E,able subscripElng, record redeflnitlon,
external and internar calls
to other programs, lntert,ask
comllunlcatation, anci random, S€Quential, and indexed access to fiIes.
Additionally, DIB0L lncludes a comprefrenslve online debugging utility
wit.h which Ene program cieveloper can quicKly lsolate and correct

programmlng errors.
Documentatlon:

IolroduclioD to the gsolillB0l LaDguage

Page 4-3

TOOLS FOR'dRITING TTIE APPLICATION

PeLI./DIBOL LaDguage

cefereoce i{aDual

e8o./DlBoL rooL Klt

llseris Gui.rie

PEOIDISOL B,eJ.ease Uotes aoci Iostallalioo

4.1.3

Guide

PDP-11 r'1ACR0-11

processor supplled trlth the
MACRo-1 1 1s a PDP-1 1 assembly language
host system. The assembler processes source staEements seguential.Iy,
generatlng binary machine lnstructlons and data t{ords or performlno
assenrbly-Eime operations (such as macro expans lons ) for each
s t.atement .

Documentatlon:
PDE=l.l. {ACRO=l-l. IraDguage Aefer,eDce EaouaL

4.2

F0RhS MANAGE/,Er'iT SYSTEI'{ (PR0/Fl'tS-11)

used by programfirers to
for
handllng
forms
create
user lnqulry or response durlrrg appllcatlon
execution. PRO/Fl'tS-11 can be used to f ormat user lnput f or use by the
application,
and Eo dlsplay applicatlon output 1n an easily
understandable styIe. PRO/FMS-11 features include:
The ForrTrs lt{anagement System (PR0/FHS-11) is

o Forms can be designeci directly and lnteractively on the vldeo
screen, ellmlnat.inq Ehe need to Iay out tne form on paper,
code forn language statenr ents, compile, debug, enEer
corrections, and so forth.
o Forms can be modified wlthout having to recompile or reIinJ<
or reprocess collecteo data. Thls
the appllcation,
slmplifles modifications ancr reduces prograni maintenance
requirements.

o The storage of form Ilbraries on dlsk reduces program memory
reouirements.

o Tne complexities of t,ermlnal I/O are renroved from t.he
appllcatlon program. Each fj.eld 1n a form includes help,
dlsplay, protection, and valldation lnformatlon to ensure the
inE,egrity of daE,a returneci to the appllcation program.
PRO/FMS-11 includes the followin9 soft.rare conponents:
o The Form Edltor (FED) is useci to create and moolfy video
f orms. You create f orms by typlnr.r titem on the screen as they
are to appear to the appllcat lon user. The Form Edttor runs
on the host system only.

TO0LS F0R rdRlflrvG THE AppLICATI0r,r

page 4-4

The Forrn UtlllEy (FUT) ls a multlfunctlon uEility program for
creating form descrlption fi les wbich can be prlnted and form
Llbraries ( runs on the host system only).
The Form Drlver (FDV) 1s a set, of subroutlnes ca]Ied
app]lcatlon programs to display forms, perform lnput from
and
output. operatlons, respond to HELp requests, and so forth.
The Form Drlver runs on t.he professlonal,

calls for the professlonar termlnal are
dlfferent from Ftrs-11 calls for the vr1o0 terminar, changlng
the way Ln wnich an end user lnteracts wlth a form.
The Form Driver

The EESl,Pro DocuBeatatioa Suppleoeat descrlbes the speclal feaEures of
Fl,lS/Pro.

Docurnenta tl on :
Ej4S:11.48SX, BeLease,lgotes

EESIBSX:11 Sof!:gare eefeleoce yaoual,
EU,S.{PSI lioi=Eef er,eDce

E{S.1Pro DocuoeotatioD SuppLeoeot

4.3

PRO/RECORD HANAGEI,iET.IT SERVICES ( R'.1S-11)

Record ManaqemenE Servlces (Rlqs-f 1 ) provides a set of run-time service
routines and utlllties that eneble cilrect, seguenttal anC nrulti-keyed
access !o ciata files and that enable your program to definer populate,
update and maintain files on oirect access cievices. RhS-1 1 support,s
sequential and multi-DIe iceyeci access to data f ites.
Record 14anagement Services (RHS-11) provlde a record lnterface between
Ehe operatine sysIem and your appllcation Frogram, RHS-1 1 comprises a
set of run-time servj.ce routines and utilit.y prograns that enaole

keyeo access data files to De cjeflned, populated, updated, and
maintainect on dlrect access storage rievlces. The utlllty pro,?rams are
not part of the Tool Kil.
Documentatlon:
RSL:11!,./M=PLj]S RES:ll Prioer
Bs:"-l-1U.ZE:EL.LlS tsbS:ll Useris Guloe
8SX=11!.ZE=ELIJS .RES-11 gacros aDd Syebol-s
I SSUES :

TOOLS FOR FRITING THE APPLICATIOI''

4.4

Pase 4-5

If. uElliries are not, parE of TooI Kit l{e should puII t,he
manual from the set. ( BSI=1li!,1{=ELllS BES=11
Ilt'llj.l'ies )
R14S-11 UEiIities

PR0/S0RT

PRo/Sort 1s a general-purpose sortlng program for use by appllcatlons
on the ProfesslonaI. Apglicatlon Easks can use an RSX./Exec dlrectlve
(sPtiNs) to lnvoice PRO/Sort, passing the name of a file
contalnlng
sorting commands. PR0/Sort is not avallable to P/0S end users. IE
must be bundled wlth the appllcatlon when you create Ehe appllcation
tasl<s on the host system.
Document,atlon s

Chapter ?
4.5

P/OS SERVICES IJ}BRAIil

The P/OS Services . Library contalns subroutlnes for dlsplaylng menus,
he1p, and rnessage frames. 0ther routines provide facillties for
obt,aining input and output file nanres from the end user, and for
cranslating character sequences from keysErokes lnto meaningful
tokens. The P/0S Servlces liorary is one of the resldent clustered
Ilbrarles 1n the P/Cs system. Chapter ? lists the services ln the

llbrary.

Documentatlon:
Chapter
ISSUE.S:

1. ,,ihat are tne conEents of t,he t-l0s llbrary on the hosL?

4.6

GRAPHICS LIBRARY

P/0S Graphlcs 1s a Iibrary of graphlcs rouElnes for tne applicatlon
programner to use to create graphics. Features include:
1.

Graphlcs primitlves based on tne SIGGRAPH
callable fronr the TooI Kit larrguages

Graphics text

C0RE stanciard '

T0OLS i-0R vTRITI NG THE APPITICATI0N

3.
4.
5.
6.

Page 4-o

varlable character aEtrlbutes and user oeflnaole fonts
Plcture segmentat.ion
Hindow and vlewport functlons
Elght s imultaneous colors wlth the Extended Blt l.{ap 0pt1on

Documentatlon:
Gr,apblcs UaDual

4.7 RSX MACRO LIBRARY AND SYSLIB ( SYSTET'{ 08JECT ITIBRARY )
To be supplled.
Documentatlon:

g./os Systea gefeLeoce SaDuaI

4.8

FRAhE DEVELOPMENT fOOL (FDT)

The Frame Developrnent TooI (FDT) allows the application developer to
create a user interface for an appllcatlon. Through a serles of
formsr you specify the actua] text to be dlsplayed on {0enus and help
frames and information relatlnq to Ehe manner and t.lming of the frame

dlsolays.

DocumenEatl on :

Chapter ?

CHAPTER 5

TASK BUILDI NG THE APPLICATION Ot,I THE HOST

The RSx Task builder creat,es a tasK image f1]e that. can be loaded into
memory anci executed. I'he Task Builder perf orms ehe f oltowlng:

. IJlnks obJ ect, modu Ies
2. Resolves references to syst.ern or user libraries
1

norJules

of object

3. AIIocates virtual address space to the task
4. Produces an optional Task Builder inap that describes merrory
arrocation, object. modules, and globar symbor references
5. produces an optlonal SymuoI Deflnition File
5. Bu11ds an overlaici tasK
7. ,\{aps the task Eo shared regions of meniory
PRo/BAsrc-PLUs-2 generates its orrn tasK bui lder conrmand files.
lou
must edit tne SASIC-PLlJ.s-2 command files to reference the libraries
required to perform Ene tasK builci procedure,
Examples of Commands.
TO BE SUPPLIED.

Related Documentatlon
BSX-11elu.-PLUS last

Bulloer U,aoua]

CHAPTER 6

CREATING AN APPI,ICATION IfuSTALI,ATIOIi FILC

Before you can run an appllcatlon on the Professional, you must. creaEe
an applicatlon installation flIe. The application installation file
identifies all the application flIes and t,he hard$are conflguratlon
requireci by t he epPl tcat lon.
prograil
The lnstallation file is used by the dlsk-based P/OS Install
end
of
The
user
executabLe
tesks.
11st
to add the appl.icatlon to the
is glven the option of installing applicatlons into the Addltional
Applications Henu or lnto an open slot on the main menu on the
disk-based P/0S.
Chapter ? explalns how t,o use the lnstall program.
IE has the
The applicatlon installation flIe h6s a . Ih'S f11e type.
f ollowing f orinat:
lThis is t.he installation file
FILE filenane
FILE tilenanre/vaIue

NAME menu name
II\STALL f 1lCNAMC,/LItsRARY

Ii'JSTALL f ilename/TAsK
OPTIONS oPtion' o!,tioFl.. .
ASSIGTY i4EsU fiLename
ASSIGN T,lE.SSAGE filename
ASSIGTJ HELP fiICNAME
ASSIGN LOGICAL name strlng
RUh filename
Comrnands in

the Application lnstallation

FiIe must appear 1n the order

shown and eacn line rnust have the tollowlng synEax!

The exclamatlon point ( : ) precedes an opt ional

! Text

cornment..

FILE fllename
filename

A one to nine cnaracter file

name ldentitying each

flle to De cooieri to the diskette.

The installatlon

CREATT['G AN APPLICA'IION INSTALLATION FII,E

Page 6-2

f11e can contaln multlple lines of this type.
qiLE fi.l.ename/vaIue

/va1ue

There 1s no default for /value.
be one of Ehe following:

The vaLue must

/KEAP f""p this file if the appllcatlon
is re,moved
/DEIJ oelete thls f11e if the
appllcatlon 1s removed
NAME menu name

menu name

A 1 to 40 character applicatlon name as it wlll
appear tn the end user's menu. The end user
has the option of changing thls name tvhen

the application is installed.

INSTALL flIeName /LIERARY

fllename

A nine character flle name of a resident
llbrary assoelated wi.th this application.
The flIe may contaln nrultiple lines of this
type, all ot 11hlch must appear before l1nes
wiEh,/TASK. If your application uses the
callable services, each of Ehem must be

inst.alled rith this commanci line.

INSTALIJ fi]ename /TASK

filenanie
0ptionsroption,optlon

A one to nine character file name of an
aoplication task j.mage. The file may contain
ItipIe Iines of thls type.
0ptional. Specifies tne harciware options
requireci by this application. VaIid opt,ions
include: Tl'lS ( Ielephone anager,tent System)
F PP (Floatlng Point Processor)
LA100 (Grapnlcs output orinter)
VR21L (Color r''lonitor)
l',!

ASSIGIi 14El'jU f ilename

fltename

0pt1ona1. A one Eo nine characEer name
of the file containing your aoplication's menus.
Thls command may be used Eo assign a default
menu definltlon file to your appl'i.cation and
may replace use of the open nrenu flIe direcEive
ac application run-tlme"

ASSIGIT MESSAGE fIICNAMC

filename

0ptionaI.

A one to nine character

naine

CREATING AN APPLICAl IOil INSIALLATICIT FILE

Page 6-3

of the file corrtBining error and
status. messages for your applicaEion.
This conmand rnay be useo to assign a cefaul-t,
message definition file to your application and
may replace use of the open message file directive
at, application run-ti.me.
ASSIGN HELP fiICNAME

fllename

0ptiona]. A one to nine character name of
tne file containinq help information for your
appl1cat1on.
Tnls command may be useq to asslgn a default
help definitlon file t.o your applicat,ion anci
may replace use of the open help file directlve
at ap-oI lca Elon run-tine.

ASSIGN LoGICAL Iogical name Hstr1n9"

logical name

A name to De asslgned a st.rinq name. The
name could be a device or file name.

"string"

The name to be asslgned to the loglcal

name.

RUN filename

filename

A one to nlne character narie of the task lmage
file whi.ch should be executed first for Ehis

aopJ. lcation.

ISSUES:

ASSIGIi L0GICAL name in Installacion

vinat are val.io hard*are op'clons?

Insta.Ll f or disK-based P,/OS only?

What cioes the application

rthat are tne nairr es of tr)e caIIabIe services for con!mand Iine

for?

File

what is this used

Ceveloper do to creaEe a menu enE,ry
for disxette-based applicatlons?
INSTALTL f i Iename/'IASK?

CHAPTER 7
TRA'{SFERING THE TASK TO THE PROFESSIOIIAL

To execute the applicatlon on the Professlonal, use Professional
to transfer the file from the host to the
Communicatlons Facilities

target.

The Comnrunications Faci.littes ManuaI descrlbes how Eo use Professional
comnrunications for file transfer ln termlnal enulation mode. Tne file
transfer program provides an easy $ay to transfer the appLication tasK
and its associated files t.o Ehe Profess 1ona1.
l{hen the transfer'is comoLet,ed, the apptication task lmage (and any
oEfrer requested files) reslde on tne Professional ciisK.

During prograrn development, you can use the Terminal Emulation Program
to work on t.ne nost., then switch back to Iocal rnode to execute the
aoplicat.ion. The Ter;rlnaI EmuIatlon program enables the Professlonal
to behave 1ii<e a t.errninal to the host' software development system.
ExampLe of trans f errlng a tasi< lrnage to Prof ess ional .IO 8L SUPPLIED.

CHAPTER 8

INSTALLIIiG, EXECUTIT{G' A}iD DEBUGGING IHE APPLICATI0N

After you have transfered the tasK lma9e of your appllcation and the
file to tne Professional, you can use Ehe
applicatlon lnstallation
program
to install your application tasKs. The Fast
FasE InstaIl
program
is
similar to the Insta]-L program provicjed t.o enci
Install
users

Both Fast Install and lnst.all idenEify aII the executable images anC
application daca files to the system. As aoplicat.ions are lnstalleci,
the application name is placed on a menu. Afterward' the apPlicatlon
can be lnvolcerj f rom the menu.
The enci user lnstall- program instalLs applications from ciiskette;
Fast Inst6lI instalLs applicaEions from disk.

8.1

FAST Ir{STALL

The Instal] program performs the following:

1. Adds the name of tne applicatlon as an entry in ti'le specif ied
menu

assiqns Help, l'r€SSaQ€, anci I'renu file so Ehey can
0ptionally
be -Iocate,i durinq run time. If tnese fl1es are not assigned
when the applicat.ion is insta.ILed, tney are assigneci at. run
time.

Example of how to use Fast, InSTALL.
TO tsE SUPPLIED.
ISSUES:

what is tne user interf ace f or Fast Il'l STALL?

INSTALLII.JG, EXEC'tJTIIVG, AND DEiiUGGING THE APPLICATIOI,J

8.2

Page 8-2

EXECUTE THE APPLICATION

you have installed
t.ne appllcat. lon r
selecting iE from a menu.
Af ter

tou

can execut.e

ISSUES:

1. whlch menu does Fast TNSTALL put the applicatlon name on?
2. I'rhat optlons does Fast rNsrAIrL of f er f or placement
appllcation name on menu?

8.3

DEBUG THE APPLICATIUT'l

After you have located errors ln loglc or execution in the
applicat,ion, Vou can use the Terminal Emulatlon program and t iIe
Transf er to repeatedly edit, coinpi Le anci Lask bulld the appllcation on
the host, cransferring the task image back to Ehe professional when
you you want to retest, it.
The hlgh-Ievel languages provlde interactlve debugging commands to
hel-p you Iocate run-time errors in your grogram. These commands alIow
you to check program operation and maKe corrections.
The reference
documentatlon descrlbes these conrmands and t,heir use.
The Professional has a speclal feature that aIlows you to debug an
anplication using the Professiorral ano anotner terminal. To use a
t.erminal for debugging' attach it to the printer port on the back of
the Professional System Unlt.
You can redirect deDugger I/O away from the professi.onal to the other
t,erminal using Ianguage-specific commands. proqram I/O continues to
be displayed on the Professional. This allows qraphics or forms on
the Professlonal to De ciisplayed r.rithout ciisrupt.ion from debugger

messages and prompt,s.
ISSUES:
l.

BASlC-PLUS-2 has t,ne kEDIkECI comrnand

port,. lthat. do F0RTRATT and DI60t use?

E.0

use tne printer

CHAPTER 9
APPTJICATION DISKETTE BUIIJDER

After you have fuIIy debugged your aPplleatlon, you can create a P/OS
dlskette Hlth the Appllcatlon Dlskette Bu11der. The end user lnstalls
or runs the appllcatlon from the dlskette
The Appllcatlon Dlskette Bullder 1s an lnteractive program that runs
on t.he professlonal. The Dlskette Bullder coples the task lmage of
If you
your appllcatlon and related f1les to a fornatted dlskette.
have created more than one appllcat.lon or lf you have created a
diskette and dlsk-based verslon of your appl1catlon, each appllcatlon
may reslde on its o,dn dlskefte or together on one dlskette. The
packaglng of appllcatlons on disKettes 1s llmited only by thelr slze.
9.1 RUN THE APPLICATION DISKETTE EUILDER
rf the appltcatlon 1s error-free, run the Appllcatlon Dlskette

Bu1 lder -

The Appllcatlon Dlslcette BulIder perf orms the f ollowlnq tasl<s:

1. If the target syst,em ts the dlskette-based system' coPles the
ready-made bootable RX50 to the dlskette.
2. Coples the appllcatlon lnstalIatlon f11e to the dlskette
3. Coples the appllcatlon fll.es named 1n the lnstalIatlon f11e
to the d 1s ke t.te
Exahple of dlalogue:
TO BE SUPPLIED

rssuEs:

1. Is thls b'hat the AppIlcatl0n Dlsl(ette Bullder does?

APPLICATION DISKETTE tsUILDER

Page 9-2

2. rhat's the <iialogue/user lnterface for the Diskette Bullder?

9.2

LABEI, DISKETTES

l{hen your appllcatlon 1s error-free and you have created dlskettes,

put a label

on the dlskette lrlth a descrlptlon of the app}lcatlon.

The label shoulcj sEate a!" followlng:

1. Applicatlon TltIe
2. software IdenElflcatlon Number
3. l'1lnlmum hardware conf iguration requlred to run appllcatlon
4. Harcjn'are opti.ons requlred
5. Hedla space requlred by appllcatton.
ISSUES:

1. iihat needs to be said here?

t
I

APPTJICATIOI{ DISKETTE BUIIJDER

PARI III

Page 9-3

THE TARGEI SISTE}I AND SOFTIIARE TOOIJS

descrlbe programmlng conventlons f,or the P./OS
operatlng system (Chapter ?), callable P/0S and Tool Klt Servlces
(Chapter ?), the Frame Development Tool (Chapter ?) t and P/oS Servlces
Llbrary (Chapter ?).
The chapters ln Part III

CHAPTOR 1O
PROGRAI.lHING CONVENl'IONS FOR P/OS

This chapt,er descrioes the follo* ing topics:
o FuncEion Key usage
o Application 14u1ti.-tasKing
o DEC r'iult,inational Character Set

1 O.

FUNCTION KEY OPERA.TIOIi

Pressing a functlon Key passes a unlque key characLer sequence to Ehe
sof tware.
The Key character sequence ident.if,ies the key t,hat was
presseci, and the softttare performs soiTre acElon based on the Key's

setting.

10.1.1 Settlngs
There are cwo poss ible settings for functlon Keys:
1.

System functj.on: Tne key cnaracter sequences for tnese Keys
are nancjleq by tne sysEerr i therefore, the applicat,ion can
lgnore these Keys. The f ollowlng Keys have a syst,etn
f unction:
PRINT SCREbN, IliTLRiiUPT, and HULD SCRe EiJ.

rype-Ahead: The key character sequences for these Keys are
to the type-ahead butfer and tnen to t.he
Dassed first.
input buffer.
Keys not Iisted as system
application's
function keys are oassed to t.he application in tne type-ahead
huffer.

PROGRAMMlI.IG COI'IVEIJTIONS FOR P/OS

Page L0-2

l0-1.2 Asslgning Settings To The FuncEion Keys
To be suppIled.
Function Key 0Peratlon During Appticatlon Execution
Table ? shows now the Function Keys oPeraEe \{hen an apPllcation
uslng menu services during appllcatlon executlon.
10.1 '3

Table ?: ApPlication Executlon

KEY

Acrrod

ADDTNL OPTIONS

Displays an adqltlonal optlons menu.
If no aciditional optlons were deflned for
this menu, an error rnessage 1s dlsplayeci.

Arrow keys

Up and doi,Jn arrovis move the

BREA K

pointer up or down the Iist of options'
Passed Lo the applicatlon as type-ahead.

CANCEIJ

Cancels selection.

Passes conErol Eo the executlnq appllcatlon
inciicating that the user has made a seLecElon.

EXI T

Passed to the appllcat.ion as tyPe-anead.

FIND

Passed to the applicatlon as type-ahead.

HELP

If deflned in menu deflniEion file, menu
services ciisplays a help menu or help frame.

HOLD SCREEN

The screen rerrains stlII
until another KeY 1s pressed.

INSERT HERE

Passed to the applicatlon as type-aneacj.

I NI ERiIUPT

l'lAIN SCRUEI'l
NEXT SCREEI.J

llun'bered function
Key s

itegardless of Ehe context, j.f f ollowed by
the D0 Key, stops tne interactive appllcation
ancj displays the P/0S Hain menu.
If che D0 key is not pressed, tne IilITERkUPT
Key 1s ignored and the next key is used.
Passed t0 the applicatlon as type-anead.

If defined in help deflnition fife, menu
servlces disF,IaYs the next help screen.
Passed to the appticatlon as type-ahead.

PROGtiAP'HI t G C0tr VEtiTI0NS F'OR P/OS

Paqe 1o-3

PREV SCREEN

It defined in help deflnltion file, menu
services displays tne previous help screen.

pirNr ScREEN

The screen rerpains stationary

REHOV E

while lt is prlnted on printer.
Passed to Ehe appllcat.ion as type-ahead.

RES UM E

If defined, menu servlces handles while
menus are belng used.

SELECT

|iarks a selection from a multiple-cnoice menu.

SETUP

Passed to the appllcatlon as t.ype-ahead.

10.2 APPLICAIION'.lULTITASKING
Tasl<s can activate one anot,her using ane xecutlve servlce and through
features,
such as CHAIN ano CALL in
language-specific
PRO/BASIC.PLUS.2.
ISSUES:

For disKette-based P/OS, explain how the aoplicatlon can use
an RSX,/Exec dlrective to fix parts of t.he system in memory to
(Compare t'.;lEh
run witn t,he system disKeEEe out.
floppy-to-floppy file copy. ) Reference the

Chalning: use RPoI RSX Directive (alternative to exlt, see
iisx Exec Ref erence ManuaI). (PR0/BASIC-PLUS-2 anci PR0,/D1BOL)
3. Use SPviNS dlrective to activate tasks
4. Installation f11e n€mes all tasks t.o be inst.alled rlth tasi<;
services musL be narrred here. An option j.n
callable
instaLlation file irrdicates xhich tasks should be IefE active
af ter oarent tasi< exits.
2.

10.3 THE PR0FESSIUiIAL TL,RrlItrAL CiIARACIt"R SET
Character
The Professional Eerminal supports tne DEC Mult,inational
Set, nhich includes' tne ASCI I Graphlc Character set and t.he DEC
SupplemenE.el Grapnic set.. (Note tnat a grapnic character is cjef ined
as a noncont.rol cnardcter, hav j.nq a v]-suaI representetion normaIJ.y
handwrltten, printed, or oisplayed. )

cocie. The set of
The character set is representeo as an 8-i)it
cnaracter codes gainecj by uslnq tlre elghth bit supports alphaoet.lcs
used in major Eurooean Ianguages, but not commonly use.l in EnqI lsn.

PROGRAhI,{ING CON VENTIONS I'OR P./OS

Fage 1 u-4

For the ASCII subseE, the elghth b1t is set to 0. l-or the rema 1nlng
characters, the 8Eh blE 1s set to
Flgure ? shows tne Professlonal character set in a code tabIe. The
code table 1s a mat.rlx of 16 roHs and 8 columns for a seven-bit, code,
ancj 16 rows and 15 columns for an elght-btt, code. The rotvs correspnd
to the low four biEs of the character coder 6Dd the columns correspond
to the upper three or four blts of the code.
The DEC l{ultlnatlonaI Character Set, is 1n columns 0 to 15. The ASCII
Graphlc Character Set ls ln coLumns 0 to 7. The DEC Supplemental
Graphic Set ls ln columns 10 to 15.
The ASCI I control characters appear 1n columns 0 and L, the
aciditlona] control charact,er set is 1n columns I and o
1

Page 10-5

PROGRAM14ING COIvVENTIONS FOR P/OS

F19ure ?:

DEC Multinational

Character Sec

00 01 a2 03 o4io5 06 07 08 09 10 11 1? t5 14 15
0

NUL DLE

SOH DC1

STX DC2

ETX DC3

DCS

PU1

PU2

)

)t5

)

EOT

DU s

IND

)

E-tl,O

NAK

NEL kfw

ACK SYN

SSAI SPA

Eid

l.J

FS.1 EPA

as cAt{

(

Etl

)

HTJ

LF SUB

)

VTS

11i VT ts5L

12i rr

I't

lt+ Iso

ss2

DEL ss3 APC

lr p*.
10

It
t1

cclil
Y

€

o
o

t PLD cst <( ))

PLU

)

HTS

t/o

,/,
I

PROGRAI.{HING CONVENTIONS FOR P/OS

Page 1 0-5

AII of the TooI K1t softrlare support 8-b1t character codes. Appendlx
the DEc r,ultlnatl0nal Character Set codes and data
B llsts
representatlon.

CHAPTER 1 1

CALLABLE SERVICES

i.lhire your program is executlng, it can invoke some of the f aclllties
offered by P/OS to encj users. In adciltlon, the TooI Ktt lncludes a
calrable sort,lng utllity which is not avallabre to end users,
The callable
services lnclude File,
Disk, prlnt
services,
Communlcations, PR05E (the text editor) r and prosort.
The next
sections lntroduce these facilitles
and describ,e the caIIs your
applicatlon can use to invoke them.
11.

1 FILE, DISK, AND PRlNT SERVICES

The P,/0S Flle Services use Recorci Management, Services (RHS) to perform
f ire

ano disk n'anipulatlons.

using

RF,!

s-11 ,

your application can
it can

access these file and olsk servlces ciirectly, through Iit'lS, or
call on the p./0s File servlces f,o perform these oDerations.

FiIes are createo by applications'' 6nci aIl applications must follow
the system convenEions for f11e manipulation,
I 1 .1 .1

Conventions

The P/OS file

speclfication

is as follows:

device: IdirectoryJ f j.tenarie. typ; version
Each element of t.he file

specification 1s ctescrlbed in tnis section.
FlIe Name A P/CS file name is up to ni.ne characters tong. File
h3llies can contaln only the charact,ers A to Z and Che numerals 0 Co 9.
Uppercase anci Lo',{ercase Ietters
are valid ( Iowercase IeEters are
convert,ed to uppercase).
L:mbedoecj
spaces, punctuation. anc other
speciaL characters are not aIIor+ed 1n t. iIe nai'tres.
File Type A P./oS f11e type is a 3-clraracter extensions t,o Ehe file
narne. Ey convention, tlre tlle type descrioes the irrternal
organlzation of the file.
The lnternal oreanizaEion of a file

CALLABLE Sb.RVICES

Pase LI-2

determlnes which appltcation the end user can use to ilork wiEh 1t.
For example, the printer cannot prlnt an executable flle.
The end user chooses a file type from a rlst of rreanlngful namesr dod
FiIe Services translat.es the nane into an internal file type. The
meaningful name is displayed ln a f11e directory on t,he screen. If no
meanlngfur name 1s chosen, the 3-ret.ter flle type 1s dlsplayed.
Table ? shows the user-vlslble file types that are supporteci:
Table ?: User-vis1ble Fi le Types
FILE TYPE

I N TER NAL

USE

REPRESENTATION

BASIC Program
ciata
docunrent

t.ext

user/BASIC
user/8ASIC
user,/Edi tor

. BAS
. DAT
. D0c
. txt

user/Editor

Table ? shows a partlal list of f11e t,ypes that
used only by the system and by appllcetlons:
Table ?:

are

s uPPor

teci and

Syst,en/Appllcation Flle Types

FILE TYPE

INTERI{AL

USE

REPRESENTATIOi,J

forms Iibrary
system flIe

task lmege

converted help fi le
converted message fL Ie
converted [r€hu f11e
tsasic virtual array file
DIB0L dat,a file

. FLB

applicatlon

. TSK
. HLP
. h*sG

system/application
appllcation
appllcation
application

cvq

.H,NU

. VIR
. DDF

systerr'

ProBas ic
PRO/DI BOL

F11e Slze

fhe size of a file is ]imited by Ehe nedium on
1t
'{hich
resloes. F-iles cannot be spread over more t.han one mediur*,
except
when a file residing on the dlsl< is saved to a seE of disket.tes (fiIe
bacKup ) .

Hedla Files reslde elther on tne dlsK or on a diskecte. For
disKette-baseo P/0S, Ine base disl<eIte musI resi0e .in 0ne dlsKette
slot during system use" A storage ciiskette can be Ioaderi ln the otner
sIol.
Proqrarns cannot be executed fron, storage cjiskettes on

ciisK-based P/DS"

The disk
The P/OS sysEem software always reslces on the disk.
dis)<ettes can both be used for the user's data storage and f11es.

and

CALLABLE SERVICES

Page 11-3

I'led1a Names Each disk and dlskeEEe has a physicar, loglcal, ano
volume name. Physical and Ioglcal names are propertles of the meoia
and Eheir matching disK drives. By convention, a Iogical name is a

me'anlngful egulvalent of a ohysical device nafire. Physical anrl logical

names do not change. Your applicatlon can use eiEher the physical

Loglcal devlce name for a devlce ass ignment (device: ) in a file
speciflcatlon.
The end user asslgns a volume name to

a storage dtskette when the
dlsKette 1s flrst used. Volunre natnes are asslgned to system ciiskettes
and appllcatlon di,skettes by the P/OS or by an applicat,ion. The ciisk
has t,he volume name BIGVoLUME. System dlskettes produced by DIGITAIJ
begln t{lth the Ietters uDEC. " VoIume narnes of sc.orage diskettes can be
changed.

TabIe ? Iists physlca-L devlce names in the Ieft-hand column, p/oS
roglcal- names 1n the middle column, and harciware types in the
right-hanci coLumr!.
TabIe ?:

Physical and Logical Device I,l ames

Physical

Logical

Name

Front
Pane I

DZl

DISKETTE1
DISKETTE2

DZz I
D.d0:

BIGDISK

Herdware
1 ype
RX50 diskette
RX50 diskette
RD50 dlsk

Fl1e Dlrectory Files are organized in groups called directories,
Dlrectory names are one to nlne characters ln length anci may be
enclosed 1n brackets or 1n the signs < and
A dlrectory is an index of a group of files that belong t,oget.her.
Each dis!< contains at least one directory. The dlrectory contains an
entry for each file in that directory and malntains a recorrl of each
fire's name, type, size, protection status. Iocation, version number,
date created, oate of, l-ast change, ano date of rast backup.
Directory names can be asslsneo by the user. The preassigned
direcEory, usEilFILES, is a sEarcing pointi this directory can be
cieLeted or not. used. Initially,
t.his olrectory cont.ains the names of
aII the fiLes createo by the end user.
!ihen the end user starts working on Ehe syst.em, tiles createcj ciuring
the session are automat.ically assigned to the UsERFILES directoryr
unl-ess the def.ault oirectory has been cnangeq to a different
dlrecE.or!,. Thls assignment can be chanqed during the sesslon.
You nray creat,e a directory from your application. If your appllcation
creates files that serve no useful purpose af.ter the appticatlon
terminates, t.he epplicatlon should cjeleLe those files before exiting.
If your applicat,ion passes througn several p'rases, opening and closlng
f iles in the user's dlrectory to pEss cjata oet.,{een pDases, then Ehe
application shou.l.d provlde an easy r, ethod to Ehe user for eletlng
tnose files.
ci

CALLABLE SERVICES

Page tL-4

Verslon Numbers *hen a fi 1e is created. 1t is assigned verslon
number 1. hhen the file is subsequently modified, such as when it is
edited, a new version,2, of t.he f11e 1s created. Now verslon 1 and
vb'rslon 2 are on the dlsk, As verslons of a file are created, thelr
precjecessors renaln on dlsk untll the encj user or your applicatlon
deletes them.
The verslon number must De separated from t.he file
(;) or bY a geriod (.),

type by a semicolon

Defaults The system assumes certaln f11e characterlst.ics if the user
does not specify tnem. File Iocation (disi< name and file dlrectory),
protectlon code, and type are characteristlcs that can be assumed.
Changes to default characteristlcs can be saved and applied during
subsequent sess ions,

The defaults may oe overridden durlng each file

expllcit speciflcatlon by the application.
t7 .1 .2

manipulatlon through

Services

Copy flle

Dupticates a file on the dlsk or dlskette.
The current
dis)<, directory, end file names are the def aul t,s f or tne output. f i 1e.
The out.put file mus! be copied to a different version numoer.
Append flIe
Attacnes a copy of one file to the end of another file.
To be concaE,enat,ed in Ehis wEy, files must have sequentlal fj.le
organization and tne sarne file cype. In acidition, the di.sk on which
Ehe file being aDpendeo resides must, have enough space to contain both
fiIes.
Rename flIe or change flIe type
Changes tne name or file type of
fiIe. T'i)e disK and directory names cannot oe clranged.
Delete flIe

Erases a fiIe.

Set.s the prot,ection status of a ri1e.
Tne default
protection cocie glves a file a protectlorr st.aE,us tnat. aIIows change,
cielete, or cnange and delete.

ProtecE f1]e

Llst dlrecLory Dj.splays a Iist aDout aI] files 1n the specifieci
Tne Iist shows file name, flle type, flle size, daEe of
dlrectory.
creation, protect,ion code, and cjate of last backup. This comrnand can
of files, list of directories, and a fu11 directory of
sho.*, a list
fiIes.
prlnt
Initiates a print job by submittlng one or more flIe names to
Servlces.
Print

CALLABLE SERVICES

IT.2

Paqe 1 I -5

OVERVIEH OF P/OS COXMUNICATIONS FACILITY

P{.OS communications j.ncludes the f oI}owing f eatures:

Iermlnal Emulatlon

System-to-sysE,em file

Telephone Management System

transfer

Appllcation writers can use Communlcations run-t1me services as
bullding blocks for new communlcatlons applicatlons. A.ppIIcatlon
programs can access many of the communj.cations facilltles
through
system servlce routines. 0t.her facllitles rnay be lnvokeci as tasks by
the applicatlon durinq program execuEion. Comnrunications facllttfel
are fulIy ciescribed 1n the Concualcalioos Laoual.
Conrmunlcations facllitles

use the Phone BooK to establish connections
between systems fot file and data transfer, terminal emulatlon, and
voice telephone management..
The data base is availaoi.e to any application prograrn that supports
RMS lndexed flles.
For example, it is used by a communlcations
applicatlon to flncj the number of a person to dial.
The terminal

emulator uses
characteristics.

store

host

system phone

nUfrroefS and

The P/OS ccmmunications softHare lnt,erfaces described in Ehls sect.ion
are support.ed by the foIIowlng functlonal comoonents:
1.

comiTrunication services:

A library of routines vrhich may be
carled oirectly from an appricaf,i.on program to perform
comnunicati.ons services on Ehe professionaL. These services
grovide a set of services nearly equivalent to tnose
availaore through Ehe user lnterface rnenus for t.he
Comrnunicatlon Facll ity.
Communlcation Utility Task (CUT): A utL lity that, ' impl_ements
library servlce caIIs and hano Ies unsoliciteO. telephone
connect reoues t.s and f i Ie trans fer reguests.
Durnb 'Ierrni.nal Emulat.or (DIE): A program fhat
hancjles t.he
VT102/VTL25 flle ernulation.
l'i1e Transfer progranr s: A program that hancires the transfer
of files between the Professionat and a host or bet'rveen t''{,o
Professlonals-

CAI,LABLE SE RVICES

Page 1 1 -6

LI.2.1 GeneraL Descripclon
y{ith the excegtlon of those routines descrlDed in Ehe section on 'IHS
seii.vlces, aII cominunlcations servlces may be used to request functlons
on both tne communicatlons port and ThS Iines in a t.ransparent manner.
The user 1s flrst reguired to caII CCBALC to reguest the allocatlon of
a call control. olock, tne address of whlch is passed bacK by the
The call control blocK must be used 1n subseguent,
CCBALC routine.
calls to communlcat,lons service routines. An applicatlon prograin
uslng communlcations services musE incorporate t,he communications
lmpure area lnto the t,ask by Ilnklng the module "C0t{R0Tl' into the tas]<
root. A Iinkaqe t,o the lmpure area is set up v1a the SVEXT polnter.
An AST routlne 1s Iocatecj in the lmpure area. If the user wishes to
servlce unsollcited events on the communications 11ne r the CCATA
routine may be calleo to attach the 1ine. A11 unsolicited events are
not.ifled vla this AST rout.1ne. The AST rouEine saves tne event,
not if ication 1n a user-designat,ed word def lned 'rrhen tne CCATA routlne
1s ca11ed. In addition the unsoliclted event flaer wnich the user
specifled 1n the call to the CCATA routlne,1s set. The program may
wait on this evenc flag for an unsolicited event.
If you wanl to control more than one communicat.ions line
simultaneously, CCBA.LC must, be caIIed for each line belng used. The
address of a new CaII Control BlocK 1s returned each t,ime (maxlnrumn of
three). Tne tasK may wait, for unsollciEed event,s on one or more llnes
by uslng Ehe hTL0S directive.
The user may perform either synchronous or asynchronous I/O to the
comrnunicatlons Ilne driver.
The I/O type 1s indicated by the 'efn'
F'aranieter in Ehe CCTXD and CCRXD routlne call Ilnes. For asynchronous
I/O, the even! flaq sPeclfied by the user is set on completion of the
I/O t,rans f er. Note that because Ehe two-word stat.us reply 1s not set,
until completion ot I/o it should not, be tested until Ehe rerminatlon

event flag is set.
If you are uslng C0DEC lnput. orr a TMS Iine, note that, tne voice s19na1
is digitised at 4l(b per second. It ls only possible to avold Ioss of
voice data if asynchronous I/O is perforrneo and Ehe lnput requests are
double br.tffered. I! 1s recomended that each input request speclfies a
4l<b buffer.
This a1 Iows the user eopl icatlon I second to process the
buffer before tne second ouffer fiIls.

If the FTsNI), FTSiiD,{, FTGdT or FTGETtl routines are being used for file
transfer Ehen the conmunications Iine Dus! aot oe attached hecause Ehe
t,ransfer wlll never be sEarted.
Il -2.2 StaLus Returns
AII routines return a two-word s!atus, the status parameter 1s always
parameter in the call ljne. The first worci
pEssed as the first
The
contalns a code lndicatinq success, or tne source of any error.
second status *ord contains a code indicattng the specific error.

CALLABLE SERV ICES

Page 11-7

some services t,ranslate into

GI0 caIIs to the appropriat,e
while others' such as f11e transfer requests, use Ehe caIIaoIeciriver;
inrage
communication rouEines t,o reouest the communicatlons utillty
task
io
perform functions on behalf of the appllcation.
AII routlnes return sorne status lnformatlon that lndicate the degree
of success or failure.
Those routines that issue eI0 calls to Ehe
drlver return an I/0 Status Block (I0SB) the service routine checks
that the I/O has termlnated successfully and lndicates thls 1n the
flrst status viord as elther a success or error staCus. fn the case of
an elror, the second status word 1s loaded wlth the cont.ents
of the
flrst 'iord of the I0sB. The appllcatlon may check the first byte
of
thls word to deternrine the speclfic error.
If a service rout,ine can be called to issue ao asynchronous
the
appllcatlon must specify an addltional E,wo word area for Ehe eI0,
IoSB.
If
the servlce routine 1s useci 1n lts synchronous mode, Ehe terminatlon
status is slgnaled as cescrioed aDove. Hotvever, if tne service ls
usecj 1n 1ts asyncnronous mode the first
status word only indlcates
iehet.her t.he 010 nas been successfully issued. The program
test
the I0sB t.o determine 1f the L/o terminat.ed successfuIIy afternust
the
0I0
has complete.j. This is slgnaled by the setting oi an event flag
specifled in the origlonaJ. call to the service.
The status cocies returned are defined as globaI symbo]1c constants in
the communlcat.ions services Iiorary. For those languages that alro.*
the definition of external constant.s, the values wiLl be resolved
by
the tasK builder at build tlme. Thls document defines all the status
returns by thei syrrbolic nanes. AII success returns are positive
values, aII error returns are negat.ive values.
Lt -2 - 3

communicat,lons services carling

AI1 subroutines utilize
wlth:

the R5 calIlng

conventions

convenlion

and

are

entered

JSR PC, SUBR

The paramet,er pacK is point.ed to by R5 anrl has the followinq format:

n-0.00

Dyte 0 :
Dyte 1:

wD.01

Address

wIJ.NN

Adcjress of arg N

liumber of argument,s
Undefineo

of arg

Registers R0-t<5 are undefined on return, sp is restorecj to its state
at encry before exit fronr a routine.
AIt parameters are passeo Dy
reference anci daEa Eype converslon 1s performeci by the service
rouClne. Use the following format to call corrrmunications serVices:

CALLAtsLE SER V ICES

Pag e

CALL SUBR (parm1,parn2r...

11-8

rparmN)

0ptional parameters are shown 1n tJ ano may be dropped from tne caII
Iine of the service ciescribeci. LII routlnes return a E.wo-'rord sEatus
which lndlcates the success or fallure of the funct.ion belng
reguested.

file
transfer
11.2.3.1 File Transfer staElstlcs Buffer - The
buffer 1s a 36 byte array 1n wlrich t,he file transfer
statistlcs
statlst,lcs data is returneci.
The statlstlcs block nas the following fornat:
i{D.00
FlIe size in blocks when complete
hD.01
Current block betng written,/read from the flle
riD.02
Current file function
'rtD.03
Device mnemonic for the Ilne
lrD.04
Unit number
''{D.05
Bytes received, double ]engtn int.eger
tsyt.es sent / ciouble length inteqer
ljD.07
itD.09
Data blocks sent, douole lengtn int,eger
riD.11
Dat,a blocks recelved, double Iength integer
'rrD.13
Byt,e 0: Data errors inbound
Byte 1: Data errors outbound
''{tJ. 1 4
Byte 0: Remote reply tlmeout.s
tsyte 1: LocaI reply t,lmeout,s
riD. 1 5
LocaI buffer allocation failu res
nrJ.15
Elapsed t,ime for transfer in seconds as a
double lenqt,h lnt,eger

IL "2.4

CaIl ConErol Services

?he services descrlced in this section enable an application program
to setup anC cont,ro] a telepnone conrrection for t-he purpose of voice
or Cata communicatlon. Voice conrmunlcatlon 1s only avaliable via the
TIS option.

L1.2.4.I EnabIe/DisaoIe Communicat.ions 0ption (CCEI'JBL And CCDStsL) These tFo rouf,lnes are used to loacj anci unload t.he communlcation port
and TMS oevice drivers. Before you use eitner of these routlnes, you
the device drlver tasks lnto the systenr. The
rnust lnstall
corrrnunicatlons utility task actlvates or deactivates the designateo
driver. 0n accivatlon the drlver is given che default. characterlstics
deflneo for tne lines associated ldith it. 1t f11e transfer 1s enabLe.j
copy or recelve, the comrnunicatlons utllicy Easi<
f or remot,e f lIe
monitors unsoliclteci connects.
CaII:

CAttABLE SERV ICES
CALIJ CCEIiBL (statusroPt!on)

"n1
CALL CCDSBL ( st,atus , oPtlon)

Pararreters:

stat,us

CS.StiC Successful
CE. PRl,1 Servlce call parameter error
CE.DIR RSX Directlve er.ror
Second status word contalns the Dsl{
cE.DRV l'alled to load/unload drlver
C2.INS Drlver not lnstalled
C2.ACT Driver alredy actlve/not act,lve

optlon

speclfles the drlver co be loacjed or unloaded.
Valid values are:
1 communlcation port, Drlver
2 T,'ls Driver

Paqe Ll-9

CAT LABLE SERYICES

Page 11-10

LL.2.4.2 Call Control Block AIlocatlon (CCBAtC) - fhls
routlne
allocates a Ca11 Control Block (CCB) and lnltlallzes lt wlth the
parameters passed ln the call flne.
The communlcatlons llne 1s
asslgned to the speclfled lun. The CCB ls used to pass parameters
beEween the varlous communlcatlons servlces.

call:
CALL CCBALC ( s tatus , ccb , lun, dev , unlt )

Paraneters:

status
ecb
Iun
dev
unlt

Cs.sUC Successful
CE.PRl,l Servlce call parameter error
CE.DfR RSX Dlrectlve error
Second status rord contalns t,he DSli
An lnteger whlch ls used to return the address of
the call control block ln the lmpure data area
lroglcal unlt number f or the conrmunlcatlons llne.
lwo byte AscII string contalning the devlce mnemonlc.
Unlt number ln blnary.

CALLABLE SERVICES

Page 11-11

.2.4,3 Attach Line (ccATT And ccATA ) - tnese two routines provlde
to the communlcations
to the application tasK a mechanism t,o attach
'Ihe
routine at,taches
ccATA
Ilne. The CCATT rouCine attaches a line.
events.
for
unsollclted
used
De
to
AST
routine
a'Llne and declares an
$hen
lt is
area
impure
to
the
copled
CCATA
ls
used
by
The AST routlne
the
event
is
slgnaled'
event
an
unsollcisted
If
oeing init.iaIlzed.
uhich
lt
on
line
the
ccb
for
of
the
word
zero
wrltten
to
code is
occured and tbe event, flag specified by the user 1n the call to ccBINI
ls set.
11

CaIl!
cALL CCATT (stat,us rccb)
and

cALL CCAlA (sEat,us,ccb'ef n)
Parameters:

sEatus

ccb

efn

CS.SUC Successful
CE.PRH Service call para[reter error
CE.DIR RSX Directlve error
Second status word contains the DSi
CE.IER I/q TernrinaEion error
Second status word contains the
I0SB flrst word
An lnceger which cont,ains the address of the call
control bIocK.
An event f laq t,o signal unsol'icited events.

t:
i.
I

CALLAtsLE SSRVICgS

Page LL-t2

LL.2.4.4 Detatch tJine (CCDET) - The CCDET routlne detatches a Ilne
t,hat has been attached by t.he CCATT or CCATA rou Elnes .

cJrr:
CALL CCDEI (s tatus , ccb)

Parameter:

status

ccb

cs.suc successfu1
CE.PRl.l Servlce call parameter error
CE.DIR RSX Dlrectlve error
Second status word contalns the DSh
CE.IER I/O Termlnatlon error
second staEus word contains the
I0SB flrst worci
An lnteger whlch contalns the address of the caII
control bIock.

Page 1 1-13

CALLABLE SERVICES

I1.2.4.5 Set Line Charact,eristlcs (CCSHC) - This
Ilne characterlstlcs to f,he deslred seEtlngs.

routlne

cj-rr:
CALL CCsHC (status,ccb,ldb,slze)

Parameters;

status

ccb
ldb
stze

CS.SUC Successful
CE.PR,'t Service call paramet,er error
CE.DIR RSX Dlrective error
Second status word contalns tne DSld
CE.IER I/O Termlnation error
Second status word contalns the
I0SB first word
An inteqer whlch contalns the address of the caII
control bIocK,
Llne descriPtor blocK contalning the new line
characterlstlcs.
The size of the characterlstlcs buffer in bytes.

modifles

.'l

CALLAtsLE SERVICES

,
r

Page 11-14

t1.2.4.6 Get Llne Characterlstlcs (CCG14C) - Ihls routine returns the
current Ilne characterlstlcs for the speclfied Iine.
Caft,

cALL CCG14C (stat,us,ccDrLctb,size)
Parameter s :

staEus

CS.SUC Successful
CE.PRh Service call parameter error
CE.D-lR RSX Dlrect,lve error
second s tatus word contalns the Dsti
CE.ItR I/O Terminatlon error
Second st,atus r,ord contalns the
l0SB flrst word

ccb

An lnteger whlch contalns the address of the caII
control bIock.

Idb

A buffer into whlcn the llne characterlstics may be
teturned 1n ldb format.

sLze

The size of the characterlstlcs buffer in bytes.

i
I

CALLABLE SERVICES

Page 11-15

It.2.4.7 Get/Put Llne Configuratlon Fecord (CCLCRG And CCLCRp) These routlnes rnay be used to 'retrieve and modlfy Ehe rlne
gonfieuration record for the spectfied 11ne.
CaII:
CALL CCiJCRG (status tccD | 1cb, IttbIe] )
and

CALL CCLCRP (statusrccb,ldb, IEtbte] )

Parameters:

stat,us

ccb
Idb
ttble

CS.SUC Successful
CS.ITB Successful, no translate table deflned
CE.PRM Service caII parameter error
CE.DIR RSX Directlve error
Second status word contalns the DSl{
CE.RI'{S FiIe I/O error
RMS error code passed in second word
An lnteger which contalns the address of the carl
cont.rol bl.ocK.

Line descripcor bIock.
This optionar parameter contalns a translate t,able
for converting lnternal telephone numbers to thac
accepted by an autodial modem. Its prlmary use ls
for auto-ct16l modems attacheci to the communicat.ion port
anci editlng out format effectors in the teleohone
number.

CALLABLE SERVICES

,
j
1

Page 11-16

L.2.4.8 DlaI Ca11 (CCDIAL) - This routlne dlals a calI on the
communicatlon Iine types are
deslgnated comriunlcagions Iine.
deslgnat.eci with tne CCS!'lC communtcatlorls servlce, and detecceci by the
current 'data mode' of t,he devlce.
1

CAlI:
CATIJ CCDIAL (statusrccb,tel)

Parameters:

status

ccb
tel

CS.SUC Successful
CE.PRI't servlce caII parameter error
CE.DIR RSX 0lrect1ve error
second status word contalns the Dsi{
CE.IER l/O Termlnation error
second st.atus word contalns Ehe
l0SB flrst word
An integer whicn contalns the address of Ehe call
controL block
Telephone number '

CALLABIJE SEiTVICES

Page 11-17

1!.2.4.9 Answer CalI (CCANS) - Thls roullne ansi',iers a caII on the
speclfled tel.ephone Ilne. The call ls'answered 1n the current, n,ode of
tfr.e Ilne, elther voice or data.
For a Tt4S Ilne, for '{hlch the caII has already been established 1n
v0lcE mode, hen a change rnode (ccfi0DE) command is issued to place the
Ilne 1n ASYNC mode the Answer rout,lne causes THS to connect the
designated modem 1n answer mocie. The corresponding party must, have
To esEablish origlnat,e
establlshed tnelr modem ln'orlglnate'mode.
mode with P/OS Communlcation services, use the CCoRG routine.
'lY

Ca11:
CALL CCANS (status rccD)

Paramefers:

status

ccb

CS.SUC Successful
service ca}1 parameter error
CE.DIR RSX Directive error
Second status word contalns the DSii
CE.IER I/o Termlnat.ion error
Second status woro contalns the
ItlSts first \torci
A lnteger which contalns the address of the caIl
cont rol block.
CE. PRI{

CALLAtsLE SERVICES

Page I1-1I

11.2.4.10 Hangup A Ca11 (CCiiNG) - Thls routine dlsconnecEs a call
yrhlch has prevlously been established on a speclfled line.

carr:
cALL CCHNG ( status, ccb)
Parameters:

status

ccb

CS.SUC Successful
CE. PRl.l Service call parameter error
CE.DIR RsX Dlrectlve erlor
Second sf,atus irord contalns the DStd
CE.IER I/O Terminatlon errot
Second status word contalns the
l0SB flrst word
An integet rhich contalns t,he address of the call
control bIock.

CALLABLE SEsV ICT,S

Pase 11-19

11.2.4.11 Transriit Data (CCTX0) - this routine transmlts a data
buffer to tne destj.nation system at Llle other end of a conmunications
1i.ne. the data 1s dellvered to the remote syst,em as a character
st,rlng w1t.h no imtermeoiate Iine protocol.
Call:
CALL CCTXD (status,ccO, tefnl rstadd,slze)

Parameters:

status

ccb
efn

CS.StJC Successful
CE.PRI'l Service cal] paramet,er error
Cg.DIR RSx Directlve error
Second status worci contains the DSll
CE.IER L/O Termlnatlon error
Second status word contains the
IOSB first word
An integer which contains the address of the call
control b1ock.
An event flag to be set on completlon of the I/O
transfer. This 1s only required 1f asynchronous
I/O is being used. For synchronous I/O the
parameter may be absent or have a value of zero.

stadd

A string f,hat contains tne cjat.a to be transfered.

size

An int,eger specifylng t,he amount, of data to be
t,rans f ered.

Page Ll-20

CALLAiJLE SLRV ICES

iL.2.4 .12 . Receive DaEa (ccRxD) - Ihls routine reaos dat,a from a
communlcations tine. Tne user may either read all tne data currently
br:f f ered in tne dr iver or wait a specif ieC period of Einre anci read aII
tHe dat,a accumulateC up to that ooint.. Alternatlvely, the user may
read a flxed amount of data trorn the I1ne. Input w11I always
termlnate when the user's buffer becomes fuI1. L'he drlver has a
rimlted amount of buffer space (512 bytes ). rf xoN/x0FF support has
been specified, the drlves witl transrnit, an XOFF when the buffer
becomes three-quarters full and an XON when the buffer is emptied to
additional
the one-quarEer po1nt. If the buffer becomes full,
characters wlII be lost.
Ca11:
( status, ccb, Ief n] , stadd ,size

CALL CCRXD

' Itmo] )

Paranreters:
s

tatus

cs. suc

Successful

Service call paramet,er error
RSX Directlve error
Second status word contalns the DSt(
I/O Termlnation error
LL.1trK
second status t:orci contalns the
I0SB flrst word
An integer which contains lhe address of Ehe call
control bIocK
An ever)t flag to De set on completion of the I/O
transfer. This is only required 1f asynchronous
7/O is oeing used. For syncnronous I/a the
parameter nrsv be absent or have a value of zeto.
CE. PRH

CE.DIR

ccb

efn

stadci

size
t,mo

A strinq into which the data may be placed.
An inte?er specifylng the amount of daEa received.
An opcional timeout count in one-second intervalsTf zero is speclf ieo, no t.inreouf, occurs ano the
read request does not terminate until the ouffer 1s
fuIl. If tmo is Less than zero, the request returns

immediatety after transfering as many cnaracters as
are avaifaole. If tmo is greater tnan zero the request
wiII Eimeout af t.er t.mo seconos ( less tnan or equal to
L21 secs). Rgain the nunrber of characters available
is returned.

iil.
I

CAI,LABLE SURVICES

Page 1 1-21

11.2.4.13 FIush Input Buffer (CCFLSH) - Thls routlne r111 flush
lnput buffer for the speclfied communtrcatlons l1ne.
CaII:
CALL CCFLSH (statusrccb)

Parameters !

stacus

cs.suc successful
CE.PRU servlce caIl parameter error
CE.DIR RSX Dlrectlve error
second status wotd contalns the Dslt
CE.IER f/O Termlnatlon error
Second status r,ord contalns the
IOSB flrst rord

ccb

An lnteger whlch contalns the address of the call
control bloc,<.

the

CALLABLE SLRVICES

Page L1-22

LI.2-4.t4 Generat,e Break (CCBRK) - Thls routine generates a breaK or
a long space on the llne.
CaIIs
CALL CCBRK ( s tatus , ccb , brk )

Parameters:

status

CS.SUC Successful
CE.PRl.t Service call parameter error
CE,DIR RSX Dlrectlve error
Second'stat.us word contalns t,he DS!t
CE.IER I/0 Terminatlon error
Second status word contalns the
I0SB first word

ccb

An integer rhtch contalns the address of the call
control bIock.

brk

If lhts is zelo Ehen a break ls sent, lf thls has
the value one then a long space 1s sent.

CATLABLE SERVICUS

Page 1 1 -23

11.2.4.15 K1I1 1'ransfer (CCKILL) - This
routine
destroys
any
out.standlng transfers.
Thls can only be used with asynchronous I/o
transfers. The outstandlng transfer terminates 1n the normal rnanner
tti, set,tlng t.tre event flag speclfieo by the user at lnltlatlon.
CaIl:
CALJL CCKIIJIJ ( s tatus , ccb )

Parameters:
s

tatus

cs. suc
CE. DIR

ccD

SuccessfuI

Service call parameter error
RSX Directlve error
Second st,atus word contains t.he DSli
CE. I ER
f/O Termlnation error
Second st.atus r*ord contalns the
I0SB first word
An lnt,eger whlch contains Ehe address of the call
control block.
cE. PRl.l

CALLABLE SERVICES

Page 1L-24

LL.2.5 FiIe Transfer Services
The routines in this section are useci to lnlLlate and conErol file
t!.ansfer betiveen two Professionals. The actual f11e transfer 1s
performend by a file !ranster task running 1n the backqround. The
f11e transfer tasK handles the 11nK protocal and the flle transfer
protocol. The file t,ransfer t,asK ensures the correc! delivery of data
between the source and destlnatlon systems.
11.2.5.1 SeEup File Transfer 0ptions (FTOPTG And FTOPTP) - T}/o
routlnes are provided which allow the flle t,ransfer oplions to be
conflgured for automatlc flle transfer lnitlatea by a remote system.
The routine FToPTG returns the current option settings. The routine
FToPTP mociifies the current optlon settlngs,
CaII:
CALL FIOPTG (statusrccbrflaqs,pswrorvol,direc,maxflle)
an ci

CALL FT0PTP (status,ccbrflagsrps\{rdrvolrdirecrmaxflle)

Parameters:

status

CS.SUC Successful
CE. PRr,! Servlce call parameter error
CE. Rl'1S !-1Ie I/O error
RilS error code passed in second word

ccb

An integer *hicn contalns the adoress of the caIl
control oIock.

flags

0ption Flags
bit 0 = I Enabl.e renrote flle copy
0 Disable remote file cooy
bit 1 - 1 Enable renote file receive
0 Dlsable remote file copy
bitl
= I Superceeoexlstingfiles
0 Do not superceed existinq files
bits 4 Eo 15 Reserved

psl{'rd
voI

lilne charact,er password to be used oy a remote
Protessional. Space filled if password
security disaoleci.
Nine character narne of the volune Co which flIes
belng r.eceiveo from another Professional are placed.
OnIy used it no volurre speciflcation appears on the

CALLABLE SERVlCES

Page lL-25

incomnring f ile sPec.

trlne character name of the oirect,ory into wnich
flles belng received from another Professlonal are
placed.0nly used 1f no dlrectory speclficatlon appears
on the lncomminq flle sPec.
max-f1Le An unsignea lnteger specifytng the max slze local
file that can be created by the remote Professlonal.
Note a zeto value Lndlcates no 1lmlt. The flle slze ls in

cil.rec

fssues

blocks,

1. Status: To be decldeci-

Page LL-26

CALLABLE SURVICES

LI.2.5.2 Send A i'1Ie (l'TSND) - This routine is used to send a f ile to
The file transfer 1s initiated in the
anoCher Proesslonal.
bac,(ground. A messaqe is written to the message board when the
t.i.ansfer terminates.
Call:
CALIJ FTSt{D (st.atus rccb' f specl ' (f spec2J )
Pararlret ers:

status

CS.SUC Successful
CE. PRltl Servlce call paranieter error
CE. UN0 UnsupDorted message opt.lon
CE.14FE l.|essage format error
CE. IMU lnvalld message oPtion
es sage tYPe out of sYnc
CE. HSC
Cg. DDC DDC,4P error
Ce.llFS FiIe l/O error
.l{ord
RHS error code passed in second
CE.IUA lnterna] error aborE
An integer 'fhich contalns the address of the caII
control bIock.
The source file descrlptor string.
l'1

ccb
fspecl
fspec2

descripEor string ' lf not
file.
supplled t.hls witl be the same as the source

The desIination file

CAI,LABLE SERVICES

Page t7-27

11.2.5.3 Send A F11e And hialt (FTSNDt{) - Thls routlne ls used to send
a flIe to another Professlonal. The flle transfer ls lnltlated ln the
background and the program walts untll the transfer 1s complete before
continulng.
Call:
CAIJIJ FTSNDH (status ,ccb, f spec1, If spec2J ,bf stats )

Parameters:

status

ccb
fspecl
fspec2
bfstats

CS.SUC Successful
CE.PRl.{ Servlce cal. I parameter error
CE.UtiO Unsupported message optlon
CE,l.tFE l.{essage f ormat error
CE.IHO Invalld message optlon
CE.l.tSC Hessage type out ot sync
CE. DDC DDCI.{P error
CE.RI'{S FlIe L/O error
RtlS error code passed ln second word
CE.IEA Internal error abort
An lnteger whlch contalns the address of the call
control blocK
The source flle

descrlptor strlng.
The destlnatlon flle descrlptor strlng, lf not
supplled thls 1s the same as the source fl]e.
F11e transfer statlstlcs buffer, thls ls a 36 byte
array 1n wnlch the fll.e transfer statlstlcs data
1s returned.

CALLABt,E SERVICES

Pase 1 1-28

11.2.5.4 Retrleve A FiIe (FTGEI) - Thi.s routine 1s used to retrieve a
file from another Professional. Tne fi.le transfer is iniEiated in the
background. A message wlIl be written to the messaqe board irhen the
transfer terminates.
Ca11:

CALL FTGET (sEatus, ccb, tspecl r lfspec2i , Ipswrd] )

Parameters:

status

, CS.SUC Successful
CE.PRI Service call parameEer error
CE.UNO Unsupported message optlon
CE.MFE ilessage fornat error
CE. IMO Invalid message option
CE.t{SC Hessaqe type out of sync
CE.DDC DDCMP error
CE.RHS File I/O error
Rf{S error code passed 1n second worci
CE.lEA Internal error abort,
ccb
An lnteger which contalns the address of Ehe calI
cont,rol bIocK.
fspecl
The source fLIe descript.or string.
fspec2
The ciesti.natlon file descripcor strlng, 1f noE,
suoplled !his is the same as the Sor.1;ss fiIe,
psv,ro
A string contalning a password to be presented t,o the
remote Professional system.

CALLABLE SERVICgS

Paqe Ll-29

11.2.5.5 Get A F-11e And *ait (FTGETw) - This routlne 1s used to
retrieve a file from another Professional. The file transfer is
lnltiated 1n Ehe background anci the program walts untlt the transfer
1s complete before continulng.
Ca113

CALt FTGETti (status . ccb, f specl , If spec2] , Ips rrrd] , bf stats )
Parameters:

status

CS.SUC Successful
CE.PRI'! Service call pararret,er error
CE,UNO iJnsupported message option
CE.l'{FE t'lessa9e format, error
CE.It{0 InvaIld message option
CE.l,lSC Hessaqe type out of sync
cE. DDC DDCp,P error
CE.RMS File l/O error
R/,S error cocje passed 1n second l{ord
Cg.IEA Internal error abort
CE. Ph'E Passrorci error

ccb

An integer which cont,alns the address of the caIl
control .bIocK.

fspecl
fspec2

The source flte descriptor strlng.

pswrd

A string containing a password to be presented to tne
remote Professional system.

bfstats

FlIe transfer statistics buffer, Ehis is a 36 byte
array in which the fil-e transfer staEistics data
is returned.

The desElnatlon file

descrlptor string, 1f not
sr:oplied t.his ls the same as the source file.

CALLAtsLE SERV ICES

Page I1-30

returns the
routine
L1.2.5.6 GeE Transfer Status (FIsIs) -in rhis
Line.
speclfied
a
progress
on
status of a f11e transfer currently
been
nave
not
my
reported
oeing
transfer
Note tne st.atus of the
lnlttateC by the current applicatlon'
CaII:
CALL FTSTS (status tccbtbfstaEs)

Parameters:

status

CS. SUC Success fu I
CE. PRt't Service caII Paramet er error

CE.UNO Unsupoorteci message option
CE.i'1FE I'lessage format' error
CE. IM0 lnvalid message oPtlon
cE. t'{sc r'1es sage cYpe out of sync
CE. DDC DDCTIP error
CE.Rr'1S File I/0 error
tl14S error code passed 1n second word
CE' IEA lnternal error abort'

ccb

bfstats

An lnteqer which contains the address of t,he call
control blocK.
36 byte
File transfer st,atisEics buffer. This is a ciata
stat'istics
array ln '{h1ch the file f,ransfer
is re turned.

CALLABLE SERVICES

Page 11-31

11.2.5.7 Abort Current Transfer (FIABT) - Tnis routine stops Lhe
current, file transfer ln ptogress on a given conimunj.caEions Iine. The
tr.ansfer 1s terminated regarciless of hhet.her or not 1E was lnitiated
by'this program.
Ca11:

cALL FTABT (statuS,ccb,bfstats)
Parameters:

status

ccb
bfstats

cs.suc successful
CE.PRt{ Servlce caII Parameter error
CE.UIl0 Unsupported message optlon
CE.l'l FE Message forrnat error
CE.ItO Invalid messaqe oPtlon
CE. MsC l.tes sage EYPe out of sYnc
CE.DDC DDCMP error
CE. RtlS l-i1e I/0 error
RMS error code passed 1n second worci
CE.IEA lnternal error abort
An inte.ler llhich contalns the address of Ehe call
control block.
FlIe transfer statisEics buffer. Thls is a 36 byte
array ltr which the flle transfer statistics data
is returned.

Page LL-32

CALLABLE SLRVICES

Lt.2.6

lMS servlces

The services descrlDed 1n thls

section are specific

Eo the

Tl.ls

harcjware and may return an error stat,us if attempted for the KernaI
Communlcations Port,.

tt.2.6.1 change I'tode (cctloDE) - Thls servlce changes the current, mode
of the llne.
CaIIs
CALL CCM0DE (status rccbrmode)

Parameters:

status

ccb
mode

CS.SUC Successful
CE.PRM Service call parameter error
CE,DIR RsX Directlve error
Second status word contalns the DSH
CE.IER I/O ?ermlnation error
Second sEatus hord contalns the
IOSB flrst'r,oro
An integer phlch contalns Ehe address of the caII
control bIock.

Ihe following mocie settlnqs are available
Q = vOlCE
I = ASYNC (l'todem)
| = CUDEC
J = DTrrF Keypad ('t'ouchtone pass aII keys )
4 = DTlt- Block (Touchtone with il as CR)

CALLABLE SERVICES

Pase 1 1-33

Lt.2.6.2 0riqlnate CaII (CCURG) - Thls routine 1s t,he converse of
CCANS for a Tl'{S line which 1s currently in voice r'ode and about to go
lnto ASYNC mode. when t,ne cnanqe mode command is lssueci, the
d'e.sl9nateci modem is pi.aceo 1n'origlnate'mode.
l,ote that one party
shourd be 1n 'ans''{er' mode and the other party in 'orlqlnate' mode.
CaI}:
CALL CC0RG ( s tatus , ccb )
Paramet,ers:

status

CS. SUC

cE. PRI'!
CE. DIR
CE. I ER

ccb

Success fuI

Servlce call parameter error
RSX Dlrectlve error
Second status word contalns the DStr
I/O Terminatlon error
Second status worci contalns the
I0SB first, sord

An lnteger which contalns the address of the call
control trlock.

Page 1 1-34

CALLABLE SERVICUS

routine
11.2.5.3 AuxiIlary Keyboard EnabIe,/DisabIe (ccAiJXK) - This
enables or disabtes the auxlliary keyboard for t,he specifted Tl'{S llne.
CAII:
CALL CCAiiXK (status rccbrflag)

Parameters:

status

ccb
flag

CS.SUC Successful
CE.PRh Service call parameter error
CE.DIR RSx Directive error
Second status word contains the DSii
CE.IER I/o Termination error
Second status word contains the
IosB flrst word
An integer whicn contains the adoress of the call
conErol bloci<.
This flag indlcates t{hether the keyboaro is belng
enab] ed/ d

i sabI ed.

0 1 -

Disaoled
EnaDled

Page 11-35

CALLAbLE SERVICES

L1.2.6.4 Turn SpeaKer On/fJff (CCSPKR) - This
speaker 0N or OFF for the speclfled TUS llne.

routlne

turns

Catl:
CALL CCSPKR (status rccb, flag)

Parameters:

status

ccb
flag

CS.SUC successful
CE.PRI{ Service call parameter error
CE.DIR R.SX Directlve error
second status worci contalns the Dsh
CE.IER I/O Termination error
second status word cont,alns the
IOSB first word
An lnteger which contains the address of the call
control block.
Thls flag lndlcat,es whether the speaker is being
turned 0i,l or oFF.

O-OFF
1 -'0N

the

CALLABLE SEIiV ICLS

Pase 11-36

1 1 .2.6.5
Prepare To Go volce (ccpTGV ) - This routine
warns the
specif ieci TxS line rhat 1t 1s about, to qo lnto VOICE mode. i{hen !he
place the call is not cjisconneceed.
:hanSe mode Cakes

CaII:
CALL CCPTGV (status,ccb, flag)

Parameters:

staEus

CS.SUC successful
cE. pRl'i servlce calI parameter error
CE.DIR RSX Directlve error
Second status *ord contains the DSh
CE. ISR
I/O Terminatlon error
Second staEus word contalns the
I0sB flrst word

ccb

An lnteger which contains the address of the carl
control bIock.

frag

This frag indlcat.es whether ts 'prepare to go voice.
command is bei.ng issueci or a previous one ls being

cancei..l_ed.

0 1 -

Cancel

Issue 'Prepare To Go Voice.

11.2.5.6 Set DII'iF Escape sequence (CCDTI'1F) - Thls routlne seEs a DTHF
escape sequence on the specified TMS line. An unsollcited evenE
AST
trap is returned
the sequence in encount,ered. This is reported
"rnen
by setting an event fLag if CCATA has t-reen useci lo atLach the line.
Ca]1:
CALL CCDTI'rF ( sEatus , ccb, otmf )

Paran,eters:

status

CS.SUC Successful
CE-PFr'i Service ca1l. parameter error
CE.DIR i(SX Directive error
Second staLus woro contalns the DSl+
CE.1tsR L/O lermination error
Second stat,us word cont,ains the
I(iSB flrsc
'{ord

ccb

An integer whicn contains the address ot the call
cont,rol bIock.

dtmf

A sErlng t,erminated by a zero byte tnat contains Ehe
DT|,tF escape sequence.

CALLABLE SERVICES

Page 1 1-37

I TEXT EDITOR
The P,/OS text edltor 1s called PR0SE. PROSE offers faclllties
for
enterlng and ed1t1n9 text, to create ciocuments, BASIC programs, memos
or slmllar text f11es. T€n edltlng keys on the professlonal keyooard
allow text, manlpulatlon uhlle lt ls belng entered. The end user
documentatlon describes pRosE features and user lnterface,
The edltor can be part of a larger appllcatlon.
For exampler 3rt
electronlc ma11 appllcatlon mlght use the edltor to provlde edltlng
servlces for message creatlon or modlflcatlon. In thls form, pRosE 1s
caIled the caIlaOIe edltor task. All of the edltor functlons offered
to the end user are avallablc ln the callable form of the edllor.
11

PROSE

1.3.1 Callable Editor Task
To use the cal.IEble edltor, appllcatlon tasks lnvoke lt as a separate
task by ca11lng the CET subroutlne. parameters co the CET subroutlne
deflne Ehe lnput. and output flre name, a .temporary work flIe name,
format optlons, maxlmum Ilne Ilne length for text entry, and Ieft and
r1ght margln values.
The lnput file name ls:he flle to be edtted. An empty or new file
can also be created. After ed1tln9, the caIIabIe edltor opens the
output file wlEh the speclfted name to create the edlted verslon of
the f11e. Your aPpIlcatlon performs lnltlal ano flnal operatlons
before and after the edltor 1s lnvoked.
The CET subroutlne passes the parameters to the caIIabIe edltor by
spawnlng 1t as a task. The subroutlne walts untlI the edltor task
ternr inat,es before returnlng control to the calllng appl1cat, 1on.
l.Jhen
the callable edltor task exlt.s, 1t returns a status word lndicatlng
the results of the edltlng sesslon.
CaII:
CALL CET (1nf1I , 1nl.en, outf 11, outlen, wkf 1L, wklen.
fofmat,maxllne, lnltIef t, 1n1tr1st, Iun, status )
Parameters must be speclfled ln the order shown:
1

Parameters:

lnfll

The lnput f11e name. Speclfy 1n
the format dev: Id1r] flIename.typ.
The devlce and dlrectory are supplled
by default tf you don't speclfy them.

ln1en

the length of the tnput flle name,
The outpu'i: f lle name. Speclf y 1n the
format dev: IdlrJ f11ename.typ. The
devlce and dlrectory are supplled

outfll

Page 11-38

CALLAbLE SiRVICES

by default if you don't speclfy thernThe ouEPut file name naY be
the same as the inPut file namet
In which case a new verslon is created"

outlen
wkfil

The length of Ehe output file

wKLen

The length of the CET ternporary worK
f 1l.e name.

formaE

Thls parameter determines whether
escape sequences are retained in the
output f11e.
To retain the formattinq datar
use a non-zero value for this paratneter.
To dlscard the formatting data,
use a zero value for thls parameter.
Durlng tne editing sesslon' t,he user can
define marglns settlngs for oifferent
regions of text' The marqin settings
result in the lncl.uslon of nonprlntlng
characters ' called escape sequences,
in the fi1e. Al.though the format of
t.he file is unaffected and rnarqins
are properIY set' the escaPe

name'

The CET temPorary t{ork file narne'
The caIIabIe editor deletes Ehls file
when the tasK exlts.

sequences inay be exclucied from the

outPut fiIe.

The presence of escape sequences in
files rnaY ProvoKe errors if the
file j.s used with hosE sYSEem

rttil.ities.

maxLine

The maxlmum number of characters on
a line that maY De entered DY a user.
VaIici values are in the range 2 to 231.

initleft

The initial

lnirrishr

left nrrrrgin val'ue'
Thls secting is used for text entered
riurlng the current edlting session.

l:ii"enrere,i
;l;,'l::l;lr'l:":,:;':;l
cluring Et)e currenC editing session.

lun

The loqical unit number required for

Status

The parameter to wlrlch is returned

r/o.

Page 1 1 -39

CAI,LABLE SI.RVICES

the results of the editlng session.
Signlf icant. bits are:

Bir 0

Bit

Lf t,his bit is set on
return, lt lndicates that,
a fatal processlng
error occurred during t,he
editing sesslon. The
output f11e is probably corrupt.
Lf thls bit is set on
reEurn, tt indicates that the
output f11e contalns escape
sequences indicaElng

some lnternal formatting
lnformatlon. For example,
marqin seEtlngs are

present.

Bir 15

If this biE is set, iE
indlcates that. tne calIabIe
editor tasK could not be
invoked. For examole, Lf
the task 1s no! installed
the Spawn wl11 f ai1. Not,e
that the oEher bits in the
status word are not
meaningful if thls bit
is set.
If this b1t 1s cIear, 1t,
rreans the calIabl.e editor
task. was involceci.

Example CaIIing Sequences

I 1 .3.2

Io be suPPlied.
I SSUES:

1. Ine paraneters to the CET subrouElne are Passeci in accordance
*ith che cTAB Parameter Passing Specifieation for character
strings and rnt,eqers.

r 1 .4

CALLABLE SIJRT PROGRAM ( PRO/SOKT )

Pit0/Sort 1s a general-purpose sorting uti.lity wnich runs on P/uS.
AppIlcatlon tasks can use the Spawn dlrect ive (SPwNs) to invoke
PRtJ,/Sort, passing Ehe name of a flIe in !he MCR command Iine buffer
conta inlnq t ne sort commands to PROISort. 0n1y a ferr sorting commands

Page 1 1-40

CALLABLE SERVICES

are needed to provlde a wlde range of sort processing. These cornmands
are descrlbed tn t,he followlng sectlons.
i ssues :

INCLUDE EXAXPITES,RNO T0 ILLUSTRATE PR0/Sort

.4. 1 PRO./Sort Commands

PRO./Sort commands are puE 1n a PRO/Sort Command flIe.
During program
execution, the command flle is passed to the sort, program and the sort
1s performed.

PRo/Sort, supports Ehe folloslng conmands:
!Comr'ent statenrent

icomment statement

I (1nd1rect command fllespec>
COIJLATE <val) AS <val> {,
<val) AS <va}) }
DEFA ULT

FIELD <name> (datatype> <start> <end>
F0RCE <narne> T0 <val> ( If'<vaI)

INCLUDE <nAmE>

)

tE0 l= l
tNut<>l
LT I < J (name>l 'tconstantrr {r<another condition)}
LEI(=l
GTI> ]
GEI)=l

INPUT <fllespec>
0UTPUT (flIespec)
SORT +l- <name> {

hRITE (name) t,

, +l- <name> }
<name> l

Def lrrltlons:

<var>

:;:,::.:,3"il3:[ :: :":?;:::'"''

in cjouble quotes o- aDostrophes.

<st,art,>, (end> ilust be a number.

Page 11-41

CALLAtsLE SERVICgS
<name>

11 .4.2

Must be a character string.

Coniment St.atement

Comment, st,atements 1n a command f11e are lndlcated by

polnt (!) or semi-colon (;) as their flrst character.
t{ith these symbols are ignored by PRO/Sort.

an exclamation

Llnes beqinnlng

L1.4.3 Incilrect Command FiIe Command
A PR0/Sort, inoirect commanci file

1s executed when an at sign (g)
precedes Ehe lndlrect command fite name. The file must have a ,CMD
file type. Indirect command files may be nested.
Files may be nested 10 IeveIs deep.
11

.4.4

C0LLATE Command

The COLLATE command may be used to change the logical
orderlng of a
character
set.
Ihe purpose of
this command is to enable
country-speclfic collating sequences. see also the Default command.
Format:
COLLA TE AS
COLLA TE

B EFOR E

COLLATE

AF'I ER

11 .4.5

DEFAULT Conrmano

The DLI'AtJLT commanci rnay De useo to set up tt)e oefault cotlating
seguence for a variety of national languaoes, The DEFAULT command
supports the foli.owing natlonal languages: Basgue, French, riorweglan,
and Engli.sh. If a C0LLATE conrmand is used prlor to a DTFAULT command.
the coIlatlng seguence speclfled in the C0LLATE commano is supersedeo
by the DEFAULT cornmand.
ISSULS:
I

Ithich nat, lonaI Ianguages are supported?

Page Lt-42

CALLABLg SLRVICES

11.4.6

FIELD Comrnand

The FIELD command aIIows you to ldentj.fy

tnultiple

fields

of an input

record.

!iith the FIETD conmand ' a symbollc name maY be gi.ven to a positional
range of a record. For example Ehe "ZIP" field could be assigned to
columns five through nine in each record.
The only valld data type for the FIELD command is CHAR. A maximum of
3O fields may be deflned ' Hhen subsequent references are made, chey
reference fleld names only. A fleld must De cjeflned before tt 1s
referenced, fot example wlth the INCLUDE statement.
ISSUES:

1. Does an upoer Iinlt
be deflned?

7t .4.7

restrj-ct the numoer of fields

wnich may

F0RCE Cornmand

record is
a
ordered. This differs frorrr the C0LLAl'E command wnich affects alI
flelds equaIIy.
For example, Ehe field uzIP,t could be sorted sucn that aI1 zip codes
The
beglnning with 5 are placed at the bottom (or top) of the Iist.
the
specified
of
on
first
character
oDerates
the
only
command
F0RCE
fieId.

The FORCE commano allows you to cnange now one field of

Lt .4.8

I NCLUDE Command

The INCLUDg commanci aIlows you to sort and wrj.te to
only t,hose recorcis rrat,ching certain concjitions.

t,he output file

For exarnple, the IIICLUDE command could match aIl records of emp.Ioyees
maKing Iess tnan s100 cioll-ars per heeK.
rihen more than one condition is specified 1n a single IhCLU0E command'
the condltlons are IoqlcaLlv combinecj (wiEn AND). A record is
lncluded only j.f it rnet aIt concjltlons in t.he II'iCLUDE commanci. !ihen
more than one ITTCLUiJE conmand is used, recorcjs need only mdtch one of
the Ilnes i.n an Ir.{ctuDE command to be incluued. up to 30 conditions
may be specifled *itn INCITUDE comrrands in a fiIe.

Page I l-43

CALLABLE SEKVICLS

I 1 .4.9

INPUT command

I:he IIiPUT commano specifies the input file
sorted,

contalning tne data

11.4.10 0UTPUT Command
The 0UTpUT command specifles the f11e that the sorted records are to
be \rritten to.
1

1.4. 1 1 S0RT Command

The SORT comnrano specifies whaE fields are Pertinent to t,he sorC
process. Data fields (as opposed to key flelds) are not Ehe target of
the sort process ano are not specified in the S0RT command. The S0RT
commano also speclfies the oroer of slqniflcance of fields to be
sorted, that is, orimary k€y' seconoary l<ey, etc.

Hore Ehan one SOFT coinmand is permltE,eci or the successive Key fields
nay be comblned on one I1ne. Up to l5 fields may be speclfied with

a file
A teaoing plus (+) or rninus (-) slgn may be speclfied before the field
name to control !he order of the sort for tnls fieId.
It
A leading plus sign is the default 1f no sign 1s specifled.
lncilcates that t.he sort should be performed in ascendlng order.
A Ieariing minus ( - ) s ign lndlcates that the sort should be performed
in descending order.
SORT commands in

TI.4.L2

#RITE Com,land'

The hRITE coiTrmano creates outPut records wit.h a di.tferent arrangement
of fields f rom Ehe input records . tjs inq the v;RITE cornmanci, a f ield 1n
the input records could oe omitteci from the output recorcis, for
example, or aII the fielos could be retained in a new order.

11.4.13

ComF'arison 0f PFt0/SorE And PDP-1 1 S0RT- I I

If you are familiar l{lth PDP-11 sORT-11 ' you ml-ght ll/ish to comPare 1t.
gain
uncierstanding of PR0/Sort
a betEer
wiEn PRO/Sort to
functionallty.
Thls section lllust,rates the olfferences bet.ween the command sYnEax
For
each PR0/Sort command ' the
f or
SfIRT-11 and PRolSort.
corresponcilno SUkl'-11 soecif icat,ion Iine 1s descrioed. Ihls shors how

CALLAbLE SEI(V ICLS

Page LI-44

PRO/Sort can oe useo to perform fan'iliar

S0RT-11 operations.

comnent in
11.4.13.1 Comment St,at.ement - In S0RT-11, a
a
speclficatlon t11e is indicated by an asterisK characEer (t) in colunrn
seven. Comment Ilnes 1n S0RT-11 and PR0/Sort foIlow as examples:
SoRT- 1 1 3

+Th1s 1s a IIne ivlth a comment in 1t.

PR0/Sort

lThls 1s a Ilne nlth a comment in 1t.
;Th1s 1s an alternate form of a comment Iine.

1L.4.t3.2 C0LLATE Command Con,pared wltn ALTSEQ Records - SoRI-11
aIIows alternat,e sequencing of recorcis in a speclficacion file t.hrough
the ALTSE0 ( ALT'ernat,e SE0uence ) comrnano. The c0tl,ATE command prov ides
a superset of tne same function in Pt{0/sort.
For example, the format. of an ALTSE0 record in S0RT-11 is:
il ALTSEQ

aaabobxxxyyy. . . ':

The val.ue aaa is the octa] vaLue of a character.
value of the character to use 1n the sorE.
The value xxx is a character.

Tne value yyy is

charact,er to use in tne sort, etc.

he value bbb is the

tne value of the

The following examples show the forrnat for boEh SCRT-11 and PROlSort
for sortlng at signs (G) as ASCIl zero (0) characters:
SORT- 1 1 :

ALTSE0 10005U
PR0/Sor t:
c0LLATE ueu AS tr0.

PR0lSort:

C0LLATE 100 as o0

F0tiCE Con,mand Compared 'r i th F Command - The PR0/Sort F0RCE
1 1 . 4. 13 .3
commancj is functionally based on tne S0RT-11 rrFrr field
record
speciflcatlon,.in wnicn !he user specifies t,he colurirn to De forced,
Ehe character to force tf'at colurnn to-. and optlonally a'triqger'
character. Tne triqger cnaracter specifies t.hat. Ehe force should not
occur unless tne lndlcated colun,n cont,ains tne trigger charact.er. For
example, aII uX'cnaraccers j.n column 50 could be sorted as if they

Page 1 1-45

CALLAALE SERV ICES

were 'rY"s. The trigger character in this case is ,'Xu.
The SORT-11 rrFil fielo specifler can also Iogically combine conditions
'fhrough
a F0RCE command. For example, if column 50 contains an rX,r
then force it fo a rrYtr. rf it does not contain an "xil then force 1t
to a ttZtt . PR0/Sort ooes not do this.
Examples:
s0RT-1 1 :

5OXY

PR0./Sort

FIELD NAME CHAR 50 59
FORCE NAME TO IIYII IF

IIXtr

11.4.13.4 ltyCLiJDE Commanci Compared rith O'And I Specificat,lons
SoRT-11 aLlows you omit or i.nclude porE,ions of the input f ile to be
sorteci. PRO,/Sort provioes one way to achieve eltner result through an
INCLUDE command.

tsoth s0RT-11 ancj PR0/Sort use the same logical relatlonship test,s to
deterrnine if a given record will actually be omltted or includecj fronr
t.he ouEput f11e.

For exarnple, to omlt. all
,,

X!ZZ! "

records wlEh column 10 t,o L4 equal to

SORT- 1 1 :

0 c 10 I4EQXYZZY

PR0,/Sort:
FIELD PLUGH CHAR 1O 14.

INCLUDE PLtTGH hE nXYZZY"

Pit0/Sort:

IIiCLUDE PLTJGH

11.4.13.5 INPUI, OUIPUT Commanci Compared kiE,h Comn'and Llne Format SURT-11 uses the stanoard PDP-11 commano 11ne format "lnput=ortt['uE" to
speclfy the input anrj output flIes. In contrast to tnls. PRO/Sort has
the user speclfy E,he tnput and output flles ln separate free form
commanos.
For exampl e:
soRT-11:

CALLABLE SEr(VICES

Page lL-46

SiIT NEI{. DAT = OLD. DA I
PR0/Sor t :
I ti PUT OI,D. DAT
OUTPUT NEW. DAT

11.4.13.6 S0RT Cornmand ComPared lilth N And O Fleld Specifications
Both SORT-11 and PR0/Sort permlt Ehe sarne KincJ of key structures
(prlmary, secondary, etc. ). S0RT-11 1s Iimlted to a maximum of I 0
leveIs of keys. PRO/Sort 1s Ilmltecj to 15 levels.

pR0/Sort uses the plus (+) and rnlnus (-) signs to indicate ascendlng
or descendlng sort per Key. SORT-11 uses N ("normaI") and 0
The fol.lowing
("opposite,') in column 7 of the specificaEion file.
5
1
to
primary
i<ey
columns
f
rom
Ehe
examp).e sorts
' secondary
34
37:
to
from
descending
SORT.1 1 :
Fll c

FOC

PRO/Sort.:
FIELD PRII'lARY CHAR 15

FIELD SECONDARY CHAR 34 37
SORT +PRII'lARY

.SECONDARY

ISSUES:

1. Interpret thls examPIe.

11.4.13.? IiRITE Command Compareci Hit.h l-1 FleId specif icatlons - Both
sort programs pernit creating outc'ut files rhose records dlffer in
field order from tne input f11e. For exanrple, 1f the lnput conslsts
of a name in colurnns I to 19, address ln 20 to 39, and zip in 40 Eo
in tne orcier
44, the output recorcis could be rearranged
<zip>, <address> <natne>:
'

soRT- 1 1 :

FDC 1
FDC 20

rDc 40

L9
39

PR0/Sor f :
F I ELD hAi4E CHAR 1 1 9
I-IELD ADDRESS CriAR.2V 39

FIELD ZIP CHAR 40 44
|{RITE ZIP I lDDt<e SS ' N/.\14E

CHAPTER L2
FRATiE DEVETOPHENT TOOL (FDT)

The Frame Development Tool (FDT) in the TooI KIE 1s a speclal-purpose

utility
for creating lnteract,ive displays for your P/OS applicatlon.
l{iEh the Frame Development TooI, you can create:
o Single-cholce menus through whlcn the end user lnteracts ivith
your appllcation
Help rnenus tnat
aval IabIe

llsc

subject,s for

0n-line help text, t,hat 1s avalIabIe
pres ses t.he HELP )<ey
A f11e of messages

ivhlch on-Ilne
whenever

help is

tne end us er

An appllcatlon may nave many tnenus thet allow lnt,eraction between 1t
and the end user. In addlt.lon, you nay rrlte on-Iine instructions to
help the user perform complex operatlons anrl Eo display error Frr€ssEe€s
if the user does someEhlng lncorreccly. You may also want to post
messagei -Lo conflrm complet.ion of operatlons. Each menu, dLsptay of
Help text, and message is dlsprayed separat.ely, one aE a t,irne. The
tern frarne denot.es any slngle-screen display.
Frames are stored on <ilsi< wlth other frames of Ehe same type in a
deflnltlon f1l.e. Thus, your appllcation menus wltl aIl be stored
Eogether i.n a Henu Def lnltion F ite;
Ehe help f rames wlII be in a Hel.p
Definition Fire; messages wirr be in a Message DefiniEion Flre.
You can create frames on the host wlth the Frame Development TooI
elther Dy using a vT100 or the Protessional 1n t,ermlnal emulation
mode. It You wanf,, co nave 8-bit characters 1n your frames, you must
use the Professional in E,erminal emulation rnode.
FDT error messaqes are Iistecj at the end of tnis cnapter.

f'RAt,rE 0gvEL0Pr{ENT ',IOOL (FDT)

Pase I2-z

L2.t PLAI'JNING'IHE FRAMES
Before you start. Ene Frame Development TooI, determine bhat, type of
frames you want, to create for your appIlcat,lon. For example, you can
creaEe slngIe-choice menus for full or short-form, HeIp text, frames,
and message texE frames,
L2.t.1

There are three tyPes of menus:
1.

2.
3.

Slngle-cholce: The end user chooses one item from a 11st of
up to L2 items. SlngIe-choice menus allor* end user to
perform appllcation-related activltles.
Slngle-choice menus
can oe full or shorc-form.
Help menus: HeIp menus list subjects about whicn help texE
frames are available.
MuIClple-cholce: The end user chooses one or more items from
The lls E iTray be of any Iength r poss j.bly coverlng
a llst.
multiple screens. HuItlpIe-cholce menus are not created wlth
tlultlple-choice menus can be
the Frame Development IooI.
creat,ed only uncier program control during executlon using
menu servlce routlnes descrlCeO in Chapcer ?

Each appllcatlon you *rite

may have a file of menus which can be used
to interact with tne apolicatlon. You specify the exact wording and
order of it,ems on a menu. You can elcner use menu service routines to
dlsolay the menus and frames or you can display them direcEly from
your application. If you use menu servlces Eo display tnem, P/0S
convenCions for visual layout. and funcE,ion Key usage appIy.

Every menu has the following fleIds:
A menu tlEle.

A fe.Ji lines of lntroductory or explanatory Eext.

A list

of optlons
the cornmand interface
Eo your
The maximum number of options is L'2. At, your
dlrecElon, sorne number of characters ln eacn opt,ion are 1n
bolotace, incilcatlng the ones the user musE, type to maKe an
unarrbiguous cholce. The bolded charact,ers are caIIed the
Keyword for Ehe option"
A polnt,er which points to one or more options or (wnen not 1n
use ) is at the rest posttlon j us t above tne opclons.
appl lcation.

FRAi'tE DEVELOPiiEI! I

Page t2-3

UUL ( FD1.)

A prompt Iine requesting user response.

Iwo cursor llnes on which user responses are t.yped.

An error and lnformatlon 11ne rrhere messages may
displayed.

A flag

lndicatlng

the presence of Additional

accessed by pressing Ehe ADDTNiT OP1.'I0NS key.

0ptions,

An lndicatlon of unread messages on the Hessage./Status Board

S1n91s-sholce menus may be defined elther 1n a I'ienu Definition File
created with the Frame Development, Too] or c!ynamically (durlng program
execuElon) using menu servlce routines. Chapter 13 explalns ho|/ to
use menu service routines to create dynamic slngIe-choice menus.

Figure ? is an example of a singl-e-choice rnenu.
above are pointed out 1n this figure.

The fields

llsted

Flgure ?: A Slngle-choice l,tenu
Explanatory

Title

Text

Thj-s application offers eJ-enentary education ln seven
fieICs of studv. Select one of the courses listed here:
Pointer Rest
Po i nter

Position

BIOLOGY
COMPUTER SCIENCE

Options

GEOGRAPHY

GOVERNI'1!NT

HISTORY
LTTERATURE
TI.IF[lATTAC

Prompt
Line

ction anc press the DO key:

Cursor
L ines

Error and
lnf ormation Lines
Line

Keyword

Additional
Options Flag

FRAFE DEVELOPi'lEhT TOUIJ (FDT)

Page I2-4

end user
Flgure ? sho"s tne i'telp menu E,hat i'as displayed when thepolnter
rdas
pressed'
was
the
!,'hen
key.
key
tne HELP
gressed the HELP
positloned at the rest, positlon on the slnqIe-cholce menu shown 1n
Flgure ?.
F j.gure ?:
A Hel-p Menu

You can display helpful information about the subjects listed below.
Select an option then press the DO key. press t.he RESUME key to reeurn
eo the main menu.
SELECTING COURSES
USING THE I.IAP
CO}'IPLETING ?ESTS AND QUIZZES
READING TTiE REPORT CARD

se Iec tion

press the DO k,ey:

HELP ]'IENU
ELEI,IENT.!.RY EDUCATION APPLTCATION

Paqe 12-5

FRAI'lE DEvEL0P'''tENT T0UL (l'DT)

t{u1t1p1e-cholce menus can be created only under program cont.rol durlng
executlon uslng menu servlce rouEines ciescribed in Chapter ? Figt:re ?
f.i- an exampLe of a multiple-choice rr€ou-

Figure ?z A l-tulE1pIe-choice l*ienu

This course covers rivers, lakes, and mountains. Our first topic is
mountains. The mountains listed below are located in different parts
the worId. Select alL the mountains located i-n North America:
MT. RUSHMORE

MT. IdASHINGTON
1.1T. HOOD
GRAND TETON
[tT

PLT\]TFP

MT, F'UJI
KILIJ,IANJARO
MT

UFT T\lq

MT. I4CKINLEY

Choose one or more options with the SELECT key and press the DO key:

Page L2-6

FRAME DEVELOPMET'JT TOUL ( FOT )

Short-form menus abbreviateci slngle-cholce menus
are deriveo
from full slngle-cholce menu text. ilosever, snort-forrn menus cover
four Iines, rather than 24.
To dlsplay a slngle-choice menu in short form, use the menu service
routlne cjescrlbed 1n Chapter ?. Flgure ? shows t.he short-form of the
slngle-choice menu snown 1n Figure ?
An short-form menu has the following forrnat:

o A menu tltle
o A two-line Ilst of optlons 1n up to six columns, only Ehe
boldeci cnaracters are rilsplayed. Up to ten characters for
each option are ciispLayed.
o A prompt and echo Ilne n ith three fieLds for a prompt,,
display of typed characters, and a message
o A flag Lndicatlng the presence of Aodltional 0ptions,
accesseo by pressing the ADDTNL 0PTIONS key
Flgure ? z A Short-f orm t'l enu

COURSES FOR ELEMENTARY EDUCATION APPLICATTON

BIO
HTST

SELECTION:

COI"IP GEO
LIT
I.IATH

GOV

Pase L2-1

FRAY.E DEVELOPhEI\T TOOL ( I-DT )

The end user selects options from rnenus

wlth functlon Keys.

and corrects

cyping errors

Pi'essing the delet,e Key ereses typed characters.

Presslng Ehe CAiiCEL key restart,s the select.ion process.
Any
charact,ers typed tnus far on the response Iine are cleared, and t,he
pointer returns to the rest position.
To make a selectlon, fhe user positj.ons the polnter wlth the arrow
keys so lt points to an oDtlon. The user presses Ehe D0 Key to
indicate t,hat a selection has been made. Any othef functlon key
termlnates the selectlon process with no seLection made.
Any user error result,s in a beep or a snort explanatory message.
The user selects opEions in the fuII single-cholce menu by positioning
Che pointer or by typing the option keyword on the response Iine. The
polnter r0oves only {nen t,he characters identlfy a unique choice. The
oointer 1s one Iine high ancJ never covers multiple cholces. when t.he
user presses tne DO Key r t,be selection ls complet.ed.
In the mulElple-cnoice menu, the user selects options by positioning
tne polnter or by typinq ihe optlon Keyword on t,he response line and
tnen pressing the SeLECf key, The options rnay reside on the currenE
screen or on related screens not currently belng ciisplayeci. (The
pointer cjoes not move in response to Eyoed characters since the
matchlng options may not currently be on Lhe screen.) hnen optlons are
chosen with Ehe SELECT key, multiple pointers point to aIl the
selections.
If necessary, the oisplay on che screen 1s scrolled t.o
select the option. Pressing the SELECT key for a previously sel.ect.ed
option refiroves that. opt.ion from the group of selected options,
In the short.-form nrenu, no pointer is used. Tne user makes a
selection by Eyping cnaracters on Lhe response Iine. Thls type of
menu enables apolication writers to provide a comrnand interface
slmilar to a commanC Ianguaqe for an application.
ISSUES:
1

,,lhat is the flag for adciitiona.L opctons?

what is tne flag for message/status boari unread messages?

FRAME DEV ELOPHEi.IT

TUOL (FDT)

Page 1 Z-B

12.1.2 Help And Message Text Frames
Help text frames provide on-I1ne instructlon while the end user 1s
Your on-Iine lnstruction may be up to 1D
uSlng your apolicat.ion.
llnes of texE. Help t.ext frarnes can De cjisplayed on the screen as
f oLlows:

o FuIl coverlng up to 16 llnes
o Top half coverlng up to 8 llnes
o Botton half covering up to I lines
o [,ast Iine (on the error and lnformatlon messaqe Iine)
Frames dlsplayeci on half

of the screen,

the screen do not, alter Ehe current contents

l,ihen you creat,e a single-choice menu, you can assoclate a help f rame
or help menu wiEh iE. !.ihen the single-cholce menu 1s displayed and

t,he end user presses the HELP Key, the itelp text frame or

Help menu
whlch are assoclated wlth the menu are dlsplayed. rrhen Ehe end user
presses the RaSUHii Key, the menu system refreshes t!a screen.
If the appllcat,ion cioes noI have menus, He]p text and HeIp frames may
be displayed direcEly uslng Helg Servlce Routines. In thls case, the
appllcaElon rnust restore the screen after Ehe end user presses the
RESUHE Key.

Flg'ure ? shows Che rlelp text frame displayed on the bottom half of
the screen when the user pressed Ehe HELP Key. When Ehe HgrJP Key 'lvas
pressed, the polnter was positioneo on the optlon "Readlng t.he Report
Card" in Flgure ?

FRAHE DEVELOPME:'IT TOOI, (FDT)

Page L2-9

Flgure ?: A Help Text Frame

helpful infornaci.on about the subjects Iisted bel-ow.
Select an option then press the DO key. Press the RESUI,IE key to return
eo the main menu.
You can display

SELECTING COURSES

USING THE MAP
CO}.{,PLETING TESTS AND QUTZZES

-> READING THE RTPORT CARD

The Report Card presents an objective evaluation of your work in courses
offered by the Elementary Education Application. The Report Card Iists
all the courses you have taken. Por each course, it indicates the nrmber of correct and incorrect answers given on tests and quizzes, the
nunber of times the course was taken, the date of the last quiz and lest
taken, and, if the course was compleced, the passing or failing grade.

Page L2-10

FRAHL DEVEL0P;\EiJT T001, ( FD'I )

The Frame
of text.
Development looI provldes an orderly way of Storlnq messages;
however , your applicaIion must retrieve and display a message frame.
Figure ? shows tne message text frar:e dlsplayeci when the end user
seLected Kilimanjaro from Lhe nrultiple-cholce rrenu in Figure ?
Flgure ?: A essage Text Frame

Message teXt frames can contain up to 20 lines

i'1

Thi.s course covers rive rs, lakes, and mountains. Our first topic is
mountains. The mountain s li.sted below are located in different parts
the vrorld. Select all t he mountai-ns located in North Amer ica:
E MT. P.usHl,loRE

I1r. l'iAsHrNGroN
L:j
l- >l I'1T. I{OOD
I->I

tr
F
t-

I->I

GRAND TETON

r.1?. R\rNrER
MT

TT] TT

KrLn'IANJARo

T1T. ST. HELENS

i:21 ]rr. i'lcKINLEY

the Do key:
Kilimanjaro is not in North America. It is in Tanzania, Africa.
At I9 , 34 0 feet, it is the highest point in .Af rica.
Choose one or more options with the SELECT key and press

FRAME DEVELOPHEIiT TOOIJ (FDT )

Page t2-lt

t2.2 DEVEIJ0PING THE FRAI'tES
After you have pl.anned the frame6, vou can start the Frame Development
TooI and create them. The followlng sectlons glve an overvlew of the
FDT command proCedure and lllustrates
the procedure wlth a sample
termlnal sesslon. Subsequent sectlons provlde reference mat,erlal on

FDT commands.

L2.2 . t

Overv 1 e r

To develop frames, follow these steps:
1.

Start the Frame Development TooI (FDT) and enter a flle name
for the frame deflnltlon f1Ie. The deflnlEion f1l.e 1s opened
and 1t becomes the current frame deflnltlon flle.
FDT dlsplays a prompt requestlng the type of frames you rant
to create. You can respond wlth an H f or HeIp, an l,l f or
message, or an S for slngIe-cholce, After asslgnlng a flle
type, you can create frames of that type and store them ln
1t. For example, 1f the file 1s asslgneci single-qholce
menusr You can create as many menus as you need. You can
then close the flle and open another flle called HEIJP for
help frames.
You can store frames of one type only ln the current
deflnltlon flIe.
For example, 1f you speclfy menus as the
frame type, only menus can be placed ln the current frame
definltlon f11e, To create help frames after creatlng menus,
save the current deflnltlon flle and open a new one.
FDT dlsplays a prompt reguestlng what you want to do with a
frame. You can add, delete, modify, or convert a frame for
executlon wlth t.he appllcatlon. You can also get reports
about frames 1n the current deflnltlon flIe.
the flrst step
1s to create a frame.
Frames are created ln an lnteractlve sesslon uslng forms. To
create a new frame, f1I1 out a Proflle, Dlsplay, and, for
menus only, one Actlon form for each optlon on the menu to
deflne the frame and 1!'s operatlon.
1. A Proflle form contalns operatlonal lnformatlon about the
frame. Informatlon recorded on the Proflle form provldes
dlrectlon to menu servlces and t,o your appllcatlon about
the purpose and operatlon of the frame when lt Is
dlsplayed. Thls lnformatj.on 1s no! dliplayed on the
f rame .

2. A Dlsplay form contalns the text to be dlspLayed on t,he
screen for thls frame, For example, user lnstructlon and
a Ilst of optlons are recorded on a DIsplay form. t{hen
thls frame 1s needed by the appllcatlon, the lnformatlon

FRAI'tE DEVELOPT'IENT TOUL (FDT)

Page L2-t2

recorded on the Dlsplay iorni 1s displayed on the screen.
An AcElon form specifles Ehe actions to be taken for an

optlon 1f the end user selects that optlon. Menus
requlte one Actlon forrn for each optlon because for each
relat.ed action rnay be taken. F or
optlon on the menu, atCreate
a F1ler'- l{hen the user
rnight
be
one
example,
creates the f11e. The
appllcatlon
the
t,hls
selects
'
to the executlng appllcatlon what
actlon form lndlcates
act,lon to take based uPon Ehe optlon selected.

ldhen
flIe.
4. Save the frane 1n the current frame definitlon
yOU save the framer YoU are save Ehe t$jo to fourteen forms
out.
For example, 1f you created a
that you fllled
you
are saving a Proflle and DlsPIay
single-cholce menu then
form, and one Action form for each optlon on the menu. The
forms deflne the dlsplay and the context,ln whlch lt 1s used.
5. Use the ADD comrnand t,o create remalnlng f rames f or thls
deflnlElon f1te.
6. Use the T{EPORT command to maKe that sure the frames are
correct; use the l.{oDIFY command to alEer Ehem' Lf necessary.
The REpORT.command complles lnformatlon about frames you have
created. You can use the report to check the frames before
you use t,hem with your appllcat,lon. If you f!nd an error ln
a frane, moolfy Ehe frame by changing Ene approprlate form.
You may have to change the Prof1le, the Dlsplay, or one of
the Action forms t,o correct tne error.
7. Afeer creating aI1 required frames, use the CONVERT command
After formattingr a
t,o format your deflnlElon f1]es '
definltton file is ready co install and run with your
applicatlon on P/AS.

FRA}/.E DEVELOPI'1EhT TuOL (FDT)

Page L2-t3

L2.2.2 San'pIe Terninal Sesslon
Tfi.e folIo*1ng is

a sample of a termlnal session using the

Development TooI on a termina] set to DCL.

Frame

S RUN FDT
FDT s tarts .
FDT prompts for

a flle
file is specified,

name and, ln thls example, a new

F!lename: FTENUS
FDT prompts for

the file type.
creat,e (H)e1p, (M)essage, or (S)ingle-cholce menu flIe? s
The letter rrSrr $'as enEered. this definition file wiII
contain single-choice rnenus.
No$ FDT prompts for a command.
Flle Command: ADD FRAj'l91
Tne Adci command is entered to create a ney, frame call.ed
FRAllE1.

Since no information is known about the frame,
FDT ciisolays a Profile form and Lne user filIs iE in.
To signal tnaC the Prof ile f orm is cornpl.ete, the user presses
the EXIT CUeiTENT F0Rll key on tne F'DT keirpad.
FDT prornpts for anothet corrrmEDd to ,#ork lrith FRAMEl.

Frarne Command :

DISPLA I

The Display command is entered to create a dlsplay for the
neh f rame FRAI'1E1.
FDT displays a tacsimile

of a menu. Using the FDT
editing keypad, the user flIIs in tne Display form with the
text for thi.s frarre.

Tne user presses the EXIT CLiRREN'I F0R/i key on the edicor
keypao anq control returns to frame editing
commanci ]evel..
FDT pronpts f or another cor'ilanci to '*ork w1t h FPAMEl.

Frame Cor,mand: ACTION

The Action command is entered to asslqn acti.ons for eacrl
optlon on the display form for FRAHEl.

FRAME DEV gtOP!'I ENT TOOL ( FDT )

Page 12-I4

A series of Actlon formsr oDe for eacn optj-on
on the DlspIay form, are cjlsplayedThe EXIT CURREIiT F0RM KeY is used
to proceed from one Action form Eo Ehe next.
l,{hen actions have been asslgned to alI options, control
reEurns to frame editlng command leveI.

Frame Command: ACTI0N 3

The Actlon command specifies the acElon form for option 3.
The user wants to correct a rnistake on the formThe action form for optlon 3 is displayed. '/lnen the user
exlts from the forrn, controL returns to frame edlting
commanci Ievel.

Frame Command: SAVE
FRA14El is saved on disx and a message 1s dlsplayed confirming

it -

File commanci: SAVg
The current frame deflnltion file, v,ENUS' is saved witn Ihe
new f rarne, FRAI'1 El , in it.
Ihe user
Control returns to host system command IeveI.
y
or
f
orm
f
FRAMEl.
rnodif
ile
t.ne
Prof
to
oecldes
S RUII FDT

Filename: FEI'JUS

FiIe CommANd: MODIFY FRAf,IEI
F DT obtains FRAilEl and cjisplays a message conf irming that
FRAI'1E1 1s available for nrodification. The user n:ust sPeclfy
.*Jhether he '.iant,s to work on tne Proflle, DispIay, or Action
forms for FFAdil.
!'rame Cornna nd : PR0F I tE
The profile command is entered. The exiscing Profile form
is dlsplayed, and changes are made to it.
Frame Command: SA/U

FRAr'tE1 is

saveo wit.h tne ne..J Profile forn.

FiIe Cornmdnd: 0UI I
The user Cec j.oed not to save tlre new FRA,ri E1. The cnanqes are noC
saved. Control returns to host sytem comrnal)d Ievel

FRAhE DEVELOPXEI,JT TUUL ( I'DT )

I2.2.3

Page t2-15

!'rame Development TooI Commands

Frame Development Tool commands are presented 1n Sect.ions ?

Fill nas been insr,alled on your systenr, to start type:

and ?

SFDT fil.ename

FDT has not been instalted

on your system, to starL type:

SRUN FDT

Lf you don'c sPecify the file name or if you use the Run command to
start FDT, the Frame Development rool prompts for the nane of the
frame deflnltion file to open. The openeci flIe is referrecj to as the
current frame definlt.ion f11e, The defaurt flre type is.DAT.
For new fiLes, Ehe Frame Development Tool then pronrpts for the type of
frame definicion file you'*ant to create. va11d flle types are heIp,
messaqe' and slngle-cltoice menu f11e. HeIp frame oefinition fites may
contain help menus or nel.p text frames.
Create (H)eIp, (M)essag€r or (S) ingle-choice menu flIe?

section ? l1scs commands used to selecE a particular file anci frame
after you starE, the Frame Development Iool.. Tnese commands are typed
to the Frame Developinent Tool prompt FlIe Command:.
Sect,ion ? lists

commands tnat. are useci to worK on forms
that define
frane contents and frame operation. rhese commancis are typed to the

Frame DeveloFrnenE TooI pron'pt Frame Command: .

The following general-purpose commands can De typeci 1n
e it her pronpt,.

response to

Ex1 t

The EXrT corrrn'and saves the current worJ<, and returns corrtrol

previous command Ieve I.

Lo the

l{hen typed to t.he FiIe Command prompt, tne EXIT coritrrrdr-ld saves the
current fran'e definit, lon file on dlsk; it perfornr s tne same tunction
as tne SAil.. corr'nand. Atter tycinE EXIT, control returns to host
sysEern corrrmanrj Ievel_.

hhen typed to the Frame Command pron:ptr t,ne gXIT command saves the
cl)rrent franr e on cilsk 1n the currenL fiIe.
rJnly t.ne current frame,
noE the fiIe,
is saved. If you oo noL save tne current file when you
Ieave t,he Program, none of tire changes macje in tne session wiIl be
saved. Aft,er typinq trXIT, the frame is saved, and control returns to
flle editlnq command level.
After saving a frame or file,
FIJT dlsolays a confirmetion nessage
nanring the fran'e or flte saved.

FRAI'IE DEVELgPi'lEN1 TOOIJ ( FDT )

Page 12-16

HeIp

Tl." HELP command dlsplays a Iist of Frame Developmerrt. TooI commancis.
If you type HgLP to tne Frame Commanci prompt irnile you are *'orKing on
a text frame, tne ACTI0N command wlII not be Ilsted.
OUIT

The 0UIT command dlscards the current work and returns conEroL to

prevlous command level.

Ehe

lrhen typed to the trile Command prompt, the 0UIT command returns
control Eo host system command Ievel wlthout saving the current f11e.
Any changes maoe to any frar,re 1n the file are discardeci.
vihen t.yped to the Fran' e Command prompt, the 0UIT command returns
control to file edi Eing command Ievel without saving the current
frame. Any changes made t,o the frame are discaroed.
Save

The SAvE commanci preserves tne current work End reEurns control. t.o the
previous command 1eveI.
when typed to the FlIe Conmand prompt, the SAVe command saves the
current file on disk.
If the file 1s new, it is assigned Ehe nexE
nlgher version number, If lhe file already exisred, iE is assigned
the next nigner version nurnDer
Hhen typed Eo the Frame Ccnr mano prompt, the sAvE command saves Ehe
current frame on oisK in tne current file.
0nly the current frame,
not the file,1s saved, If you oo not seve the file when you stop the
Frarne Development lool, all the changes made in this session witl De
discarcieo. After you type SAvE, cor)trol returns to file editing
corTrlidod level
After saving a frame or fiIe, FUT displays
confirmation nes sage
naming the franre or file saved.

FRAIlE DL.VELOPNTITT TOOL (I'DT)

Page 12-I7

In the f oLlowing sect.ions, each commancj is int.roduced 1n d cofirrrood
line in boldface type. The cornmand Iine shows Ehe command name as it
mu.st be typed ano Ehe correct placement of paranieE,ers. The foltowing
documentation convenfions are useci to define synt.ax for Franre
Development Tool commands and parameters:
UPPERCASE In commands, must be typedi the
mlnimum abbrevlatlon of a command.
Iowercase
characEers

fn commands and corrrrlroDd options,
not requlred.
In command parameEers, a varlable for
which you nust supply a vaIue.
If required parafireters are not specif leci, Ehe

Frame Development TooI oisplays a prompt
requestinq the required parameter.

[]

Enclose opt,ional parameters

lnclude or omit the iten in bracKets.
Separates rnultiple parameters. Use only
one from a series of parameters separated by
vertlca I bars .

paqe 12-lB

FRAi{E DTVELOP{ENT IOUL (I.DT)

12.2.3.1 F11e EorIing - FiIe editing conrmands allow you to select tne
frame def init,ion fi-le and frame Er)at you want to create or ivork eithr
to save the file and franie, anci Eo oFen another frane ciefinition file.
F1.Ie edlEing commands can be typed in response to the prompt:
FlIe

Command:

l{hen you are'*orklng at tnis command 1eve1, tne current file type and
file name are oisplayed 1n a message at the top of yoltr screen.
Add frame-ldentlfler
The ADD command al]ows you to create a new frame, which can be addeci
,,then you cype ADD, the
co a new or exlsting frame definiti on file.
Frame Development 'Iool <iisplays a Prof i Ie form. The Proflle
form ls
the flrst form you nust fiIl out ''then you are creating a ne9'l frame.
Parameters:

frame-i,lentifier
It you specify H, for

Tlre 8-cnaract,er identifier
new frame.

heJ.p file,

Ehe

a furLher prompt is displayeci:

HeIp (il )enu or (T)ext?
Type lt, f or HeIp rrenu and T f or heJ.p teXt f rame.
frames reside in a help definition fiIe.

Both types

of nelp

The frame-iCencifier is useci in P/uS service routines to display tne
frame. It is also useci f,o establish relatlonshlps between frames.

For example, a main enu for an appllcation may list.
the
frame-identifier of a help frame tnat describes r)ow to select an
option from a menu.
ril

If you cio not specify the franie-ioentifler,
displays a prompt requesLing it.

the Frame Developnent TooI

Convert output-fllename

The coNvERT co[rmdDd creates a formatted tile from your franre
Af ter
f ile.
using the CLr t,rVEFiT command, you can transf er
your frame definitlon file to ttre P/iiS tor apolicaclon execrltion. Tne
C0NVURT cor'mand renroves extraneous inf orrnation, such as comment.s, f rom
the frame definition flle to create the forlnat.ted executabLe fiIe.
AfEer formatt,inq, a frame oetinition file can be read ciirectly by lr,€ou
servlces ciurlng program execution.
def inltion

Parameters:

the name o! tlre executable fran,e
definition file "

output-filename
I f you do not. sDeci f y

t.ne

file

DBFrer the

!'ranre {Jeveloprnent 1'ooI

Page L2-19

FRAiIE DEVEL0P,qEiiT IIJtJL (t'D1')

dlsplays d prorrct reques tlng it.
fiLes are as follows:

The cjefault. file

FreIp Cefinition file
Messege definit.ion fll.e
f,enu definition file

types tor converted

. HLP
.l,! SG

. r'lri U

AII requlred fielos on franes must be filIed in before the frame ls
converE,ed. lf a frame Iacks requireo information, an error message ls
dlsplayed when you type CtlliVERT, ahd the f rame is noE converted.
After conversion, FDT cilsplays a message lndicatlng the nuniber of
frames converted and the number of frames not convert.ed.
DeIete frame-identlfler
The DELETa comriand allows you Co delete tne specifieci frame from the
current fiIe.
Parameter:

The lcientifier

fran'e-idenEifier

oeleted.

of the frame to be

Before cielet.ing the frame, tne Frarne Development Tool
Display form for the sDecltle(1 t rame and proirpts:

sr)ov"s

the

Delete t.his frane?

It you type Yes, the frame is oiscarded; if you type fuo7 it is not.
After you respond Eo the prompt' controL returns to the File Command
prompt..

F11e filename
The file.Command aIIows you t,o open another frame oeflnition

file.

Parameters:

'Ihe rrarne of tne tranre ciefinition

filenarne
If you do not scecify a file

nai'rr

file.

e, the Frame r-revelopment Tool prompt.s:

I ilenatne:

the Frame Develooment Tool
If you are creating a new frame file,
promDts for Ene Eype of file !'ou '*'arrt to create:
Creace (H)elp, ($)essaqe, or (S)ingj-e-choice menu flle?
Valid frane flIe types are nel-p, message, ar-:o single-cholce IIrenu f11e.
Type a carriaqe return it you hant E.o return to Ehe F'ilename: Dronlirt..
If you dicj not save Ene currenE file

oefore specifying

anotner

f11e,

Page I2-20

FRAIlE DEVELOPiILiIT TOOL (TD1)

the Frame Development Tool prompts;
Save currenE. file?

Type Yes to save iE or ho to dlscard 1t-

Llst
of the frames in Ehe
by fr-ame lcientlfer. The identifier is the
name which was asslgned to the frame when it was creat,ed with the ADD
The LIST command dlsplays an alphacetized list

current deflnition

file

command.

Report fllename

about, speclfleo frames in Ehe
speclfy the frames you want a
flle.
You
detinit,ion
current frame
from a list.
indivioually
thent
by
on
selecting
report
Para[i eter:
The name of the outpuE fil.e that l{ill
filename
cont.ain tne rePort.
If you do noE specify tne output file name, the Frame Developatent, TooI

The REp0RT command creat.es a file

pronpts:

Output. flle

narne?

The cjefaulE fiLe type for the rePort file

is.RPT.

Modify frame-identlfier
Tne l,i0DIFy corr,ir:ano finds the specified frame in the frame oefinition
After you nave. specified tne frame-identifier, the Frame
fi]e.
Comnrand prornpt. is dlsplayecj, and you select. the f orm You want to
modify for t.nis frame. valid responses are lisEed Section ?
Parenreters:

frame-identifier

The i.dentifler for the frame Lo be

modified.

IooI
If you do not soecify the franre-identifier, the Frame Development,
ioentifier,
a
frame
specifyinq
After
it.
prompt
requescins
oispleys a
t'i)T displays a rressaqe indlcating tne franre is available for
moditi.cation.
ISSULS:

FRAI.lE DEVELOPI',,EIVT

.IOiJL (FDT)

How nrany frames can be placeo

Page 12-2L

1n a menu definition

Development TooI prompt for thls ? 80 0R 1 00?

file?

FRA14E DEVELOPiilgNT TOI]L ( FDT)

Page l2-22

12.2.3.2 L'rame Eciiting - t'rame Eciiting comnands, whlch a]1ow you
create and save franres, can be Uyped in response to the prompt:

Frarne Conrirand:

Proflle
The Profile command displays a form that you can use to record
informatlon about t,he operation of Lhe frame. Informatlon on a
Profile form directs menu servlces when the frame is dlsplayeci. Thls
information 1s not, olsplayed on the screen 'rlth the frame.
A Profile form contalns flelds, both requlred and optlonal, you must
in. If you do not fiII 1n a reguired field, an error message ls
fiIl
displayed $hen you try to convert the fratne cjefinltlon file for
execution; frames IacKing requlred lnformation are not convertecj.
sinqle-choice menus r H€1p menus anci Help frames r and messages have
different Protlle forms r sho*n in Sectlon ?
The Frame DevelopmenE TooI offers a simple screen eciitor for entering
and manipulaLing text on a Profile form. The screen eciitor is
describeo at the end of this section.
Dtsplay
The Display command aI.Iows you to recorci on a form Ehe text
displayed on the screen.

Information about tne frame you record on a Profile or Actlon form may
have an effect on vJnaE a menu Iooks IiKe when it is displayed. For
example, by assigninE xeywords t,o options, you cause those characters
to appear in bolciface in the display.
A Display forrn contains fleLds, both required ancj optional", you must
1n. The fields on a l-,ispIay form correspond to Ene fielcis on a
fiIl
menu. These fields are illustraLed 1n t.his chapter in Figure ? If
you do not filf
in a requireci fielo, an error rT'essage is displayecj
flIe for executioni
\ahen you try to convert the frame cieflnltion
frames lacking required inforrnation are not converted. Single-cnoice
menus, el.p menus anri help f rames, and message f rames have dif f erent
Display fornrs. These forms are snorn 1n Sectlon ?
The !'rame Lievelopinen! Tool offers a simple screen editor for entering
anci manioulating cext on a l,/isplay f orm. The screen edit.or is
described at the end ot t.his section.
Fi

Actlon tAlI I New

optlon-numberl

The ACTION command displays a form reguesting the action to be taken
when an optlon is select,ed from the rrr€DU. Each option on a menu must

truring appticatlon execuEion' action
be assigned an action.
passed
bacK to the applicat ion progran or used
either
information is
to display a delp frame for the option. This lnfornration 1s not

Page 12-23

FRAHE DEVE[,OPI'1LN1 TUOL ( i.DT )

dlsplayeo on the screen with the freme.

Ng!e that actlon inforn,ation can be asslgned only to menus. iielp ano
message text frames cannot be asslgned actions. Every menu must. have
at least t'*o optionsi each option must be assigned an actlon.
The ACTI0lv command paramet,ers slrecify

action lnformatlon.

the options to be assignecj

ParameLers:
ALL

The ALL optlon refers to all options

currently specifled. The default optlon
f or ACTIO!,i is ALL.
The tlEk parameter refers only Eo those options
E',i
for which you have not en tered information on
an act, lon f orm .
option-number
The optiorr-nunrber is the ordinal positlon,
1 to 12, of this option in the list of opEions.
If the Action parameter specifies an opLion that, has already been
assigned actlon information, the currenE description is displayed on
the Action form. You can theg ent,er new action information or change
existing action informat,ion.
An Action form cont.ains f1e1ds, iroth required and optional, you must
in. If you do not fill 1n a reguired fleIci, an error message 1s
fiIl
displayed l{hen you try to convert eire franre definition file for
execuLionr' frani es Iacring required informat. lon are not converted.
SinqIe-choice menus and help rnenus have <iif f erent. Action f orms. These
forms are shor+n in Section ?
Tne Frame Development lool offers a sin'ple screen ecjitor for entering
ano manipulating text on an Action form. lne screen editor is
N

described next -

FRAME DEVEI,OPfiI.ItI IOOL (FD,i )

Page 12-24

Frame Development, Tool - Edltlng Keypad
t{hen you flll

in the Profil,e, Display, and Actlon forms to create a
fi'aner You can use the Frame Development TooL's editirtg Keypad to
manlPulate text. The eciltlng Keypad for the Frame Development TooI
conslsts of t,he Keys on the eqiting keypad on the V1.'100 family of
Eermlnals, or tne numerical keypad on the Professlonal. All text
enterlng 1s done in insert rnocie. Figure ? shows the layout of the
screen edltor keyoad.

DtrT@
@B@@

trBtr@
DDD[-j

NDL
Figure ?:

Screen Edltor Keypad

FRAHE DEVELOPT/ri.ftT 1'0UIJ (i'DT)

Page 12-25

The screen editor keys operate as follows:
Arrovr

kevs

:il;':':
:l:;:: ::i-i::'":i;:::'li"l3l."',1!'1,,o"
keys on the P/0S eoiEing Keypad can also
De

usecj for Ehe same purpose' as weII as Ihe arro,'v

keys on a \tT100-compatible termlnal.

Dlsplays a description of the field the cursor
currenily points to. If pressed again' dtsplays
a descrlpt,ion of the keyPad KeYs.
DELETE CURRENT LINE DEIETCS fTOM CUTSOT IO CNd Of IiNC.

HELP

Deletes from cursor to next word.
DELETE CHAF.ACTER DeLet,es the cnaract,er the cursor is on.
Positiorrs the cursor at the beginning of
NEXT FIELD
the next field on the form.
pRgvlous FIELD
PoslEions the cursor at the beginning of
the previot:s tield on the form.
EXIT CURRENT l-0RH Returns controJ to frame eciiting command
IeveI (to the prompt Fratrre Conrmano:).
lf you are tllling out Action forms
eno you press this Key, the next AcEion form
for the menu (if there is one) 1s displayed.

DELETE viORD

ili.
i

Page L2'26

FRAME De vELOP14ElvT '100L ( t DT )

T2.3 CREATII'iG A SINGLE-CHOICE I'1LIIU
Th.eflrststepincreatingaslngle.cholcemenulstofl}rlna
proflle form (see Flgure ?).
Figure?:ProflleFormforSingle-cholceMenu

profi.le for Single choice Menu [TDENTTFTER]
Frame Description

Global HeIp Frame I
Default Option t

Globa1 Action String

FRAiIE DEVELOPYEiiT TUOL (FDT)

Page t2-27

The fields on a Protile forn for a slngle-cnoice menu are defj.ned as

follows:

Frame Descr lpEion

Global Help
Frame

0ptionaL fie1d.
Enter 4 Iines of 72 characters.
use thls field to document the
overall operatlon of the
menu for Iater reference.
0ptlonat fleld. EnEer 8 alphanumeric
characters. Enter the frame ldentifler
of the heIP frame that, wilI provide helP
about the entire menu. i{hen t,he
menu ls dlsplayeci, 1f the polnEer ls in the
rest posltlon and the HELP key 1s pressedr the
help frame ldent.lfied in this field is displayed-

Default option

0ptional flelcj. Enter a one or
ttvo-d1g1t nutnber. Thls field designates an
option as the default option for tnis mentlEnter Ehe ordinal numoer of the opEion
that 1s Eo be ghe defeult for tnis menuIf you oesignat,e a oeiault oPtion'
when the menu is displayed the pointer
utomatically point's to the defaulE option.

GlobaI action string

optional f1e1o.
Enter 1 line of 12 characters. lire
gtobal act.ion string is returned to
t,he application lthen the menu is displayedExample uses: set flags before menu
oisplaYs or set function KeYs.

Page L2-28

FRAHE DEVELOPir,t tiT T0OL (FDT)

ln a Display form (see Flgure ?).
Figure ?z Dtsplay Forn for Single-choice nenu

NexE, flrl

Display for Sin91e Choice Menu IIDENTIFIER]
TTTLE TEXT
EXPLANATORY TEXT

OPTION DESCRIPTION

Paoe t2-29

FRAIiE DCVETOPMEIiT }UUI, (FDT)

The fields on a Dlsplay form for a sil:gIe-choice menu are deflneo
f oIlows:

ticfe

Enter
Required field.
up t,o 40 alphanumerlc characters.
The title is displayed on the flrst

of the menu.
.

Explanat,ory text

optional f ielci. Enter
3 lines of 72 characters.
The texE lntroduces lhe end user to
the optlons listed on the menu.

Option descrlPtion

Requireo f1eId.

Prompt

Enter

Ilne

at least tho options wlth uP
to 54 characters. The optiorrs are the
command lnterface to the application.
OPtional field. Enter
up Eo 12 alphanumerlc characters'
Enter a messaqe to tne encj user
prompting for a met)u selection.

FRAP.E DEVgLOPMENT TOOL (FDT)

Page 12-30

Thlrci, fllI 1n one Action form for each optlon on the roenu (see Flgure
?). The message 11ne at tne Eop of tne form snol.is the ordinal number
of the option for wtiicn acE,lon is oeing asslgneci. It also shorrs the
of the menu on whlch the optlon is displayed. You must
lbentlfier
fiII ln an Acclon form for each optlon on the menu.
Figure ?: Actlon Form for single-Cholce Menu

Action Nurnber [*J for Single Choice Menu IIDENTIFIER]
Descrj.ption: IOPTION DESCRIPTION]
Action Description
option Keyword I

Option Help Frame t

Option Action String

FRAr.rL DUVe LOpI{nN.t T00r (FDT)

Page 12-31

Tne fietds on an Action torm for a single-cnoice menu are defined

follows:
Actlon Descriptlon

0ption keyword

0ptional fieId. Enter 2 Iines of 12
characters. Use thls fleld to document
the overall operatlon of Ehe
menu for later reference.
Required fieId. Enter 1 to 30 cnaracters.
Some nun,ber of cont. lguous cnaracters in t.ne

option must be deslgnated the key'..ord.
You must cieslgnate one keyword for eacn opt, 1on.
An end user vrho types cnaracters rather
t.han moves the pointer must type Ehe keyword
to rnake a selectlon. l{hen the rnenu is
ciisplayed, the keyword appears 1n boldface.
At least 1 character must appear in
boldface; alI characters may be 1n boldface.
The k.eylVord must be unique; no Keyilorcj
can be a subset, of anotner Keyl{ord.
For exarnple, the nurnber 1 is a subset of
t.he number 10. These two numbers would
not be val1d xeyworcis 1f they were Eoget,her
on the sane menu.
'ilhen a short-f orrn menu is displayed,
a maxlmum of 10 characE,ers in boldf ace
are displayeo for each iterr.
A verb is often appropriate as

the keyurorci, as f or comnancis.
The Key\+ord may he at the beginnirig of an
ogLion, or 1t nay be tne whole
option, as in tfle following exarnple:
Delete a f11e
Copy a flle
However, the keyhoro may appear any*lrere in tne

scrirtq, as in tne following exar-,'ple:
iIe delete
i'i Ie copy
F

If you canDot easily cjifferentiate
your menu entries, you may use nunrberecj
entries, althouqh, tnis is nof. recon:men,Jed.
For examp;1e:

Uption Help Frarr,e

1 ,rrite checi:s
2 irrite oalar)ce
Optiona] fieId. Hnter I alpharrunieric

FRAME IJEVLLOPME:'IT IUIJL ( FDT )

Page 12-32

cnaracters of tne help frame for this optlon.
ilhen the menu on which tlrls option appears 1s
oisplayed, if the end user presses the

0ption Action string

optionr !he hel,p text frame 1s displayed.
optlonal fleld. Encer up Eo 72 characters,
The optlon actlon string 1s returned
to the appl.lcatlon when the optlon
1s select,ed.

FRAME IJEVELOP"Ii,Nl TOOI, (FD1)

Page 12-33

12.4 CI(EAtING.hEtrP l,rLltUS AND HELP TEXT FRAilES
T.be flrst step ln creatlng a help menu 1s to flll
( see Flgure ? ) .

ln a Proflle

Flgure ?: Proflle Form for HeIp Menu

Profile for Help Menu [IDENrrpreni
Frame Description

Previous Help Frame I

Default Option t

form

FRAtIE IJEVEIJ0Pr.,lEtiT T0rJL (FDI)

The fletds

lrame

on a Proflle

Page L2-34

form for a help menu are defined as follows:

DescrlPtlon :fi:i::;:,ll"i3; .;?:";r"*rltl3'031"13".
the overall oPeratlon of tne
later reference.
0pt1onal f1e1d. Enter 8 alphanumerlc
characEers. Enter the ldentifler
of the previous heIP frame.
menu for

Previous i{elp frame
DefaulE optlon

optlonal fleld. Tnls field deslgnates an
optlon as the defaulE for tnls menu.
Enter the ordinal number of Ehe optionwhen a menu 1s dlsplayed, the pointer
automatlcally points t,o the default oPtlon.

F'RA}IE DHVULCPi.{EI.iT TOOL (F'DT)

Page I 2-35

The next, step in creating a help menu 1s t,o ftlr
( see Fl9ure ? ) .

in a Display

form

Flgure ?z Display form for Help Menu

Display for Help Menu IIDENTIFTER]
TITLE TEXT

EXPLANATORY TEXT

OPTION DESCRIPIION

FRAP.E DEVELOP14ENT TOOL (FDT)

Page I 2-3b

The fields on a Display form for a help nenu are defined as follows:

Tlt.Le
'.

Ent,er up to 40 alphanumeric
Requlred fleld.
characters. The Eltle is displayed on
t.he f lrst Ilne ot the menu.

ExplanaEory texE,

0ptlonal fleld. Enter 3 Ilnes of 72
characters. The text lntroduces
the end user to the opElons l1sted
on the menu.

Optlon descrlptlon

itequireo field. Enter at least two optlons
with up to 64 characters each.
The options are the cofllnrdnd interface
to the appIlcatlon.

Prompt

0ptlonal fleLd. Enter
up to 72 alphanumeric characters.
Enter a message t,o the end user
promptlng for a menu selection.

Page 12-3'l

FRA'.1U DEVELOPMENT TOOL (I'DT)

Thlrd, tot a help menu fllt
Figune ?).

ln one Acclon form for

eacn option

(see

Action Number [*] for Help Menu [IDENTIFIER]
Description: IOPTION DESCRIPTION]

Action Description
Option Keyword I
Option HeIp Frane I

FRAHL DEVELUPi{ENT TOOi/ ( FDT )

Page 12-38

The fieLds on an Action form for a heLp menu are deflneci as foIIows:

Action Description

tJptional field.
dnter 2llnes of 72
characters. tJse this f ielci to document
the overall operatlon of the
meI)u for Iater reference.

0ption keyword

Required fieId.

Enter 1 to 30 characters

Some number of contlguous characters in t.he

option must be deslgnated the keyword.
You must oesignate one keyr#ord for each option.
An end useLdho types characters rather Ehan
moves the pointer inust type the keyword.
i{hen tne menu 1s displayeci, the
keyworo appears 1n ooldface.
At Ieast 1 character must appear 1n boldface;
aI1 characters may be in boldface.
The lceyword mus t, be unique i no keyword
can be a subset of anoEher keykord.
For example, t.he number 1 1s a subset of
the numoer 10. Ihese ryio numbers woulo
not be vaIl<j Keywords 1f they Eere together

on t.he sanre menu.

When a short-form menu is displayed,
a maximum of 10 characters in boldface
are displayed for each lCem.

A verb is often appropriate as
tne Key\{ord, such as for commands.
The l<eyworci may be dt the beginning of an
opt ion, or it may be tne whole

option, as in the foIIo*ing

example:

DeIet,e a file
Copy a f lle
Ho1{ever. t,he Keyword may appear anywhere
in Ehe strlng, as in the followinq example:
l.
F

1Ie delet,e
iIe copy

Lf you cannot easily differentiate
your menu entries, you rnay use numbered
entries, aILnoLlqh r this is not recornmended.
F or example:

0ption HeIp frame

t hrite chec)<s
2 write oa.l,al-:ce
Optional fiel,l . Enter 8 alpl)anumeric
characters of the help franr e for this option.

FRAHE DEVaL0PrvlEhT TOt"rl, (FDT)

Paqe 12-39

khen t.lre nenu on which tnis opt.ion appears 1s
oisolayed, if the end user presses Lne
HELP Key while the pointer is on this
optlon, Ehe irelp text frame is ctisplayed.

Page L2-40

FRAI/.E DEVELOPI.IEiiI, TOUL (FDT)

step Jn creating a help fext frame ls to fiII
(see
Fl9ure
?),
form

The flrst

Flgure ?: Profl}e Form for HeIp Text Frame

Profile for Help Text IIDENTIFIERI
Frame Description

Frame Location IFULL]

Previous Help Frame I
Next Help Frame t

out a Profile

FRAIlE DLVULOPY.EIJT TOOL (I'D'r)

Page L2-41

The fields on a Profile form for a nelp texE franre are tjefineo
f olloh's:

F'rame Descriptlon

0pEionar field.
Enter 4 Lines of 't2
characLers. tJSe tnts f leIci t,o document

tne overall operation of the
later reference.

menu for

Frame Iocatlon

Required fleId.
VaIici entries in thls field
are FUITL, TOp, B0TTUH, and IrIhg. A fuII frame
has L6 lines, A Eop or botE,om nalf frame has
I llnes. A line frame has one lIne. 0ne
Ilne franes have no tit1e. To enter a value
ot,her than FULL, posltion the cursor on the
ilFtr in FULL and press the DeLETE *0RD key
on the f'DT Keypad. Enter one of the otner
values.

Previous Herp frame

optional field. Enter ti alphanumeric
characEers. Enter the ioentifier
of fhe previous help frame.

Iiext Help F'rame

0ptlonal fierd. Lnter 8 alphanumeric
charact,ers. Enter the ici entif ier
of the next nelp frame.

Pase L2-42

FRAIlE DEVELOPt"iLTTT T00L (FDT)

FulI screen, top or Dott.om half nelp t€Xtr and single Iine heIP text
have dlfferent Dlsplay forms represenfing tne difference in the number
of Ilnes 1n tne frame. Fiowever, they aIl share the same flelos and
tiie full. screen nelp text frame 1s representaElve.
Figure ? shows a Dlsplay fornr for a fuII screen nelp text frame.
Flgure '!z Display Form for Help Text Frame

oisptay for Help Text ITDENUFIER]
E

TTTLE TEXT

Help Text

FRAF,E DEVELOPI'rgriT T00L (FDT)

The fields on a Dlsplay form for a help text

follows:
T.itle

Help Eext

Page 72-43

frarne are deflned as

Required tleld.

Enter up to 40 alpnanumerlc
cnaracters. the tltIe 1s ctisplayed on
the first llne of the menu.

Optional fleld, Enter 15 llnes ot 12
characters. The text explains hofl to
perform an appllcatlon-related
activlty, such as supplylng a command
in t,he proper format or displaylng
or us ing da t,a .

FRAYE DEVELCPTlENT TOOL (FDT)
r2.5

Page 12-44

CREATI hG I{gSSAGE TEXT FRAI,lES

Flrst, to create a message text frame fill

F'igure ?).

Figure ?: Profile

in a proflle

F'orm for Message F'rame

Profile for Message IIDENTIFIER]
Frame Description

fonn

(see

FRAI"E U,UVr.LrJPi'rEirT T0UL (FDT)

Pag e L'2- 45

The fielos on a Proflle torrn for a message text frame are oefineo

folloits:

Fi'ame Descrlpclon

Optional flelcl. Enter 2I lines of 19
characters. use this fleld to ciocument
the overall operatlon of the
menu for Iater reference.

FRAi',E DEVT,LDP14EITT TOOL (F'DT)

Page I2-46

for a tiressage text t rdme fill j.n a fJisF, 1aY form. i4essage t.ext
for
frames are disPlaYed wirn no boroer or prompt. The Display form
message
witn
usual
the
blank
screen
a
this type of frame is simPIY
I1'ne at. the toP ident,ltYlng the current frame.

Second t

FRAl'1E DEVEL0p!rLiil t0OL (iD1.')

12.6 RES0LVITTG ERRUk C0NDl?'I0i,lS
AII user errors occurrlng with FtJT produce
kclyboard.

Page l2-47

short oeep from the

Hhile you are flIIlnq in forms, if a key that ls not on t,he FDT keypad
is pressed or if you at,tempt to type over field boundarles 7 the
Keyboarci beeps and tne Key act,lon 1s lgnoreo.
AI1 other user errors produce a descriptlve error messsage following
the Keyboard beep. FDT Error messages are desgrlbed here.
L2.5.1 Format 0f Messages
In lhis section, eacn FDT error message appears in the sane forfir as on
your display terminal. fne messages eppear in the 1s11ewin9 form:
Message text.
or

Hessage text about (frame or flle

or name>,
In the iocumentatron, left anci rj.ght angle brackets (< and >) enclose
a synbol. The symDol represents a reference to a value that FDT
copies from your commands or retrieves frbm stored lnformat,ion. The
references are to field names or to file or frame specifications.
Tnese references may appear as the first, midcile, or Iast element in
an error messaqe.
iihen you receive a message, Iook it. up in tne follotlinE
alpnabeElzed
section, reao the snort explanation about che reason for the message,
and apply the remedies that are described.
'ihe symools in angle
bracket.s are not, used Lo aphabetize messages.
Some error messages repoft error conoitions f,Ila t, cannot be resolved Dy
you. These error messages inoicate that a ser I ous err.or has occurred
in FDl processing- 1n mosL cases, Ene errors are Ene result of a
failed file operatr.on. Ihese errors apDear 1n tne following form:
FDTxxxryyy - Hessage text.
The values xxx and yyy represent. t(l'rS-11 error staEUs numoers. 'Inese
nurnbers correlate to a specific error whicn j.s generally described by
t.ne message text. Tnese tl.'o values rnay be positive or negatlve.
r,he.n you receive a message of thls type, you shoulcj submit, a Software
Perforrrance Renort (SPR) to IJIGITAt,. An SPR is a forrn t.hat rr ost,
custcmers (.f,no are in-rarranty or riave purcnased supporE, services) can
use to report f.aults in the soft*are and slJq.lest proouct improvements.
Tnese nressaqes are Iisced E,ogether in rseet.j.on ?

Page 12-48

i.i{Ar'.8 DgV iLUp:,ieNT TOOt ( FDT )

12.6.2

LJSer Error l'lessaqes

Action form deleted.
An option ciescripti.on Iine was deleteo or t,ne Keyieord in an option
descrlption
line was divided onto tt'o lines on a Display form. The
ect.i.on fornr for tne option descriptlon Iine vlas de.l.eted by FlJl'. An
AcCion fornr 1s deleted if tne option it. describes no longer exlsts.

It you deleted t,he option ciescripLlon I ine, create anot.her one. trhen
you create the ne}{ one, an act,ion form will be set up f.or it.
If you
divideci a Keyworcj onto t'ilo llnes on the Display form, enter it on only
one Iine" A new action form wlIL be seE up for 1t.

(Frame-id> already exlsts - no new frame created,
The frame identifier of an exlsting frarne Has specified in an Acio
command. Use the,todify command to alter the existing frame or enEer

a unique frame ident.rfier.
(fllename> already saved.

'{as not changed, so no new copy of the
createci. Control returns to hosE. system command leveI.
The current file

flIe

Current flIe fuII - frame not addeo.
An attempt was nade tc acid arrother frame to Ehe current file with the
Add command but' the file contalns the maximum number of fraines.
DeIeEe a frame in the current file

start a ne'r file.

fo make room for Ehe nevi frame or

Default option 1s not 1n the range 0 to xx
Tne defaul! option field on a Profile forn nas a value outside the
valid range. 'Ine valid rar)qe is () co xx, lrnere xx is the cotal nunloer
of ootion ciescrir;cion Iines on the !;isplay forni. This error condit.ion
is detecteo after Lne Convert. co[rmdDcj'*as used Lo convert a oetinicion
file.
iJse t.he lc0L/IFY corilmanci to alter
the range.

tne Profil e form to contain a val.ue in

Default opt lon speci f ied with no optl ons.
A value was specitieo in tne iefault o!,tion f ielo on the Profile foriir
but. no optlons were Iisted on tt)e Di splay form. This error condition
is Cetecteo after cne Cor)vert conlril6nd has used t.o convert a oef rniEion
flIe.

FRAHE DEVgl,r)Pv,U,rI TOUL (FDT)

Page L2-49

Creat,e tho or more options in a L)isplay forin. Cneck to make sure

ciefault option fielci on the Profile form is correct.

the

(frame-ld> does not ex1st.
A frame ldentlfier was specifled wlth tne l,iodlfy or DeIete command but
it does not, exlst 1n the current, fiIe.
Check for

typograhical errors 1n the frame ident ifier.
To display t,he
Iist of frames contatned in the current deflnitlon f11e, type a
carriage return. Then use the List command to display the frame
icientif iers.
Enter (H)elp, (l.l)essage, or (S)lnsle-cholee to select a flle type,
A characEer other than d, 14t or S was entered in response to the
previous prorflp, t.
To select, a f iIe t.ype, respond to Ehe pror'rpt by enterlng tne single
cnaracter in parentheses 1n the message. The file type cjeEermines the
type of frarres that. may be created and stored in tne current
oefinition fiIe.
To specify a ne!/ ciefinltion file, enler a carriage
ret.urn. The prornpt, Filename: wiLl be ciisplayed.
FleId <name> lnvaIld

in act,lon form <number>.

the indlcated
The nameo f ielcj, rhich is on tne Action form iith
nu[l ber,
ooeS not, cont.ain va Lici inf orfiration. Tnis error is detected
after the Convert cofrrfiaDCi was used to convert a definltion file.
Ihe most Ilkely
Use che h0DIFY coinnrand t.o fix tne speclfied fielcl.
reason for Enis error nlessaqe is a bIanK value for a reguired fleld.
Fleld <name> lnvalld

ln display form.

The named fielcj,',vhicn is on a DisPlay formr cjoes not concain valici
inf ormaE,ion. .lhi.s error is dececce.i af cer the Convert conmand,iias
useo to convert a definiti.on file.

'Ihe mos t Iikely
Use the I,iODIFY coinihdDo to fix tne specifieo field.
reason for this error message is a blank value for a required fielci.
Fleld <name> lnvalld

1n proflle

form.

The named tield, whicn is on the Profile fo5m, cjoes not contair) valici
inforn'aclon.
ll,is error is oetected afcer tl)e ConverL coiflflrand was
file.
useci to convert. a deflnition

The mos t li re Iy
Use the M0DIFY commat)d to tix the specifiecl field.
reason for t.nis error nressage 1s a clanK value for a requireo fieId.

FRAiaL t/EVl"lLOP,'11:N1''IUUL (l'DI)

Pase i2-50

FlIe <flLename) 1s empty. F11e not wrltten.
Tlre fi. le is
An attetitpt was made to save a file rtith no frames in it.
no.t saved and control returns to host. system command Ievel.
MaKe sure the correcE file was speclfi.eci or use t.he 0U1T command to
leave FDT after opening an empty fiIe.
FlIe (fl1ename) not found.
flle or the
The specified file is either not a valio FDT definition
file does not exist.
create a ne{ FDT definitlon file using t,he specified neme or enter a
carriage ret,urn to enE,er a cjifferent tile name.
File not llriEEen - no frames to wr1te.
but it contains no
The Convert cornmand speclfied a definition.file
valio frarnes t.haE nay be converted. Any frames in the current
definition file contain errors.
Ftx E,he errors in Ehe ftames, and !hen use the Corrvert command to
converf, Ene fiIe.
Frame (frame-i.d) noE converted.

The named frame iuas not converteci b,ecause it contained invalid
inf orrnalion or it Iaciced required inf ormalion in one or more f ieIds.
Use Ehe 14odify command Eo f1x t.he IisteO errors.
commanq t,o convert tne f rar'res.

Then use the Convert

Invalld command. Enter HELP for a Llst of cotnmands.
You entereci an invatio command in response to tne file

frame

CO[rlnSOd pfOmPE..

of valid commands in tne FDT documentation or type
ilelp to oisplay tne lisE of valid commands.
RevieH tne ]ist

Invalid flIe speclficatlon <filename).
An error was rnaoe in che fortnat of the ftle
ChecK for

specification.

typographical errors in the file specificatlon. Verify !hat
tne dev:f1lename.cyp file specifrcat.ion fcrmat was used. HeEype t.he
flle sFecificaEion.

!.RAY.L DTVELOP}1EhT 1'IJIJL (i'DT)

Page l2-51

Invalld ldentlfier.
A..frame ldentifier

,vas specified r+1th rrore than 8 characters.

Enter a frane ldentifier

with no more than 8 characters.

Keyword deleted.

The Keyword for tne opt.lon cjescription Iine tnat was Just altered was
deleted. Keywords are cieleEed whenever Ehe Key''{ord no Ionqer maE,ches

tne opcion descript.ion 11ne.
Enter a new Keyword for Ehe new option ciescription line.
Keyvrord does not match descrlptlon I1ne.

The value entereo in the keyworci field on a!) Action form is invalid.
It does noE rnatch ar)y segn'ent of contiguous characters in the opt.ion
descript,ion lj.ne on the Display form.
You must eitner ]eave E,he option l<eyword field
unique, rriatching keyword in Lhe keyword f ieLd.

blanx or enter

Keytrords not unlque for options xx and yy.

Iwo matching Keyworos here specifieo for t,he named options.
Eit,her
keyw:ord xx is a subseE of )<ey*ord yy or vice versa. or they are
identica].
For example, "caE't is a subset of "catcn" and the number 1
is a subset of tne nurnber 10. This error condit.ion is detecEeci after
the Convert, command ;{as used to convert a cief init j.on f i1e.
Alter tne keyword for one or boEh of the specified options.
rf you
ciecide to alter an opEior) description Iine on the tisplay form, cio not
derece t.he line Decause the actlon form for the option wilr be
cielet,ed.

No actlon form found for option xx.

An actiori form was r)ot, fiIIed in fot tne named option.
Tnis error
cono'ition i.s oetecEed aiter the Convert coiniTlanci was useo to convert a
def i.niEion f iIe.
Use the h0DIr'Y comrrrand to tilI

ouc tne Action form.

No frames to report,.

A report. on tne current ,lefinition
contains no franes.
MaKe sure t,nat ti'Ie correct

file

fi Ie was requested but
is open.

the

file

Pag e l2-5'2

I RAI'1E. DEVELOP}'1E!T 1'OUL (i'DT)

No mat,chlng optlon f ound.

A_-nonexlstent option was specifieo in tne Action comrtand-

typograhical errors in the command Iine.
options on the DisplaY form.

ChecK for

Review the list

No new optlons found.

The Action New command has speclfled

assigned actlons.

but all

options have been

use the Action All or Actlon optlon-number commands to modlfy the

des ired act, lons.

tio optton Iines defined
The Actlon co[rlnand l{as useo out no opt.ion description lines nave been
speclfied.
Use the Display command Eo enEer the optiorr descrlption Iines, and
then use the Action command to assign acEions Eo each option.
No vaLue entered for

requlred f1eId.
Thls is a warning message indicating tnat the previous fleld reguires
a value rref ore this f rame can be convert.ed.
Determlne Hhat, the va.Lue should be for Ehe previous field ano enter
that value in the field before atte['pE1nq to converf the fiIe.
NoE enough opt,lons deflned -

at, least two are requlred.

A r'enu frame with Iess than t.wo opLions cannot, be convert,eci.
Add at least ti{o options to the rT,enu.

Not enough room to lnsert a I1ne.
1'nere is not enough room in the fleld to open a neh Iine.
Use the arrow Keys, tne next and previous field Keys, or the exlt
on the FDT editor Keyca"J to achieve the desired result.

Key

Please answer Yes or No.
You have respondeo incorrec[1y to a prompt, requirirrg
res ponse.

a Yes or

'{o

FRAI/'E DEVgL,OPil!.{rI f0UL (FDT)

Page 12-53

Responcj with a f for yes, or an fr tor lio.

Pl-ease enter FULL, TOp, 80TTOM, LfNE.

rhe value entered for Lne field !s not one of the vaIld values llsted.
You cannot proceed to the next fleId trlthouE, entering a correct
response. Enter Fu11, Top, tsottom, or f,ine to specify the
rocation of a help text frame. rnitially, rur.l is the vatue display
1n Ehe
Iocation fieId.
To repl.ace FULL or an entered va1ue, use the arrow
keys to position the cursor on the F, then press the DETEIE rroRD key
on the FDT keypaci. Enter a correct vaIue.
PIease fespOnd wlth an rrMn of rTil.
Before you can aod a frame in a nelp definition fi 1e, you rnust specify
whether you are acjding a hel_p menu or a help text f rarne.
Enter an ul',| . to add a menu, a ilTn to aod a texE. tramer or carriage
return to display the file commanci prompt.
Value must be between 0 and L2.
A value was entered for che cjefaulE option fielcj but the val ue is
an inE.eger beEiveen O and L2, or a bIanK.

not

you cannot proceec to t.lre next. tield
withouc entering a correct
response.
The naxlmunr number of options on a rnenu i s L2. you can
assi.gn any one of the 12 options to oe the defau 1t optlon.
If you
assign an option E,o be a oefaulr, woen the menu is Cisplayed
tne
polnter will rest by the cjefault, opElon. Enter a valid numerlc value
f or the f ield or Ieave it bl.ank.
12.6.3

F0T Int.ernal, Lrrors

For aIl of the follobing error iTressagesf the remeoy is as foIIoh,s:
AcEerI'pt to exit F0T. If ttre error oion't occur $/hen you were saving d
oefinition file, acEernpt co save it.
0bcain a haro copy ]isting
of
r.ne flle r:sing the ktp0iiT coftrrr3f.ra. submit an spR to DIGIrAL. Include
wich tlre sPR a detailed descrLption of the user-FDT oialogue precedinq
the error nessage, anci a listine of the qefinition file.
hecorcl on
the sPR the error rnessage exactly as iE was displayeo on your
terminal, lnclucilng tne varues representeo here as <xxx,yyy>.
FDT<xxx,yyy) - Cannot create output fiIe.
The out.put file specitleo
to a processrltg error

ilt Ehe Convert. comrndr)d cannot be..ritten

ciue

FRATTE t/EVEL0pr,1Eri1 TrJ0L ( F uI )

Page L2-54

FDT<xxxryyy) - Cannot create temPorary f1Ie.

fhe file specified cannot be openeo because of a processing error
Ene file manager.

FDT<xxxryyY) - Cannot dlsplay graphics frame.

A processlng error occurred whil.e F-DT i{as attempting Eo display
form.

FDT<xxxryyy) - Cannot read frame <frame-1d).
An atternpt, to reao che specifled frane failed.
FDT<xxxryyy) - Cannot read frame from t,emporary fiIe.

This error lndicates that, a record is

inaccessible from the

M0DIFY

command.

FDT<xxxrYYY) - Cannot read recorci,

A record in tne current. file

canrrot be accessed for conversion.

FDT(xxxryyy) - Cannot read record <frame-1d) f,rom temporary fiIe.
The Da[r€ci frarne c6nnot oe converted due to a processi.ng error.
cont.lnues t.o convert the remaining records in the file.

FDT

FDT<xxxrVVy) - Cannot wrlt,e lndex'of converEed file.

Ine ouEput file trom tne Convert process nes been corrupteo. Unqer no
circunistances snould tne output flIe be usel on Ene professional.
FDT<xxxryyy) - Cannot wrlte record <frame-1d).
The nameo f rame cannot be converE.ed due to a process in<l error.
contlnues to convert t,he reinaining records in tne tiIe.
FDT<xxx,yVy) - Closing original file
The file

the f iIe

l'DT

after copy.

specifieO cannot be o[jeneo because of a processing error

firanager.

FDT<xxxryyy) - Frame (frame-1d) unreadable.

.he specifteci fra,ne exlsts in Lne fire but 1t cannot oe read.

FRAI.lL DEVELOPIII,Iil'IUOL (T'DT)

Page 1 2-55

FDT<xxxryyy) - Index not wrltten to data flIe.

T ': current file cannot be saved 1n a permanent file
pl.,,cessing error.

due to

FDT<Xxxryyy) - New flIe cannot be created.
The current file

processlng error.

cannot be saved in a permanent file

FDT<xxxryyy) - Read fzz durlng lnitial.
The speclfieci file

the fiIe

manager.

copy.

cannot be opened because of a processing error

FDT<xxx ryyy) - Record (f rame-1d> coulci not be wrltt,en to data f ii.e.

Tne narned frame cannoE be saved in
process ing error.

the permanent file

cjue E,o a

FDT<xxxryyy) - Record (frame-ld) unreadable from temporary file.
The named fratne cannot be saved in

processing error.

the permanent file

due to

FDT<xxxryyy) - UnabIe to rrit,e record.
The frame eciitor cannot write tne last record to E,lre fi1e.
FDT<xxxryyy) - drite tzz durlng in1t1a] copy.

The fll.e specified cannot De opene,J because of a processing error
Ehe flIe

rnar)ager.

CHAPTER 13

P,/OS SERVICES ITIERARY

tor displaying and operatlng
P/oS menu servlces provicjes facilities
the menu, help r anrl message frames that you create hitn the Frame
Development Tool, fhese facilitles r caIIed servlce routlnes, are
provided ln a shared resident llbrary caIIed f,he P/OS Services
Library. They are used for dlsplaying frames fronr the prevlously
defined frame definit.ion
high-IeveI Ianguages.

13.1 DETAILED OVERVIE',{
To be supplied.

flIes.

Lhese'services can be caIled from

Fage I 3-2

P/OS SLRVICES IJIbiARY
L3 .2

CON VLITTIIJNS

Certain documentatlon conventions are used itr tnis chapEer.

Routine names shorn are the actual global symbol n6mes as knosn by tne
tasK-bul1der (TKts).
Parameter names are for illustration purposes onIy. The exact names
are defined by the appIlcat.lon developer, subJect, to t.he restrictlons
ot the language oeing used.
Parameters shown lnsicie square brackets (t and l) are optional and may
be onitted. ParameEers may only De omitted from the right, so that if
paramet,er (n) 1s omitt,eo, then parameter (n+1) must also be on,itted.

Each programming Ianguage may call tne routines in
appropriate to the language.
Fortran snoulo use the sEandard CALL sEatement.

manner

tsasic-PIus-2 shoulci use CALL xxx BY REF. parameters.

In aIl cases r r€9!st,ers are fvOT preserved by the calleci routine excepE
for the stacK pointer which is preserved.
13.3 MUIiU SEKVICE R0UTINES
This sectlon descrlbes Ene servlce rouElnes used for displaying slngle

ano niultlple-choice menus.

i4erru and nelp services use internal buffers for
menu frarnes. Tnere are three cuffers for menus

t,enpor6ry storage of
3

1. Stat.lc butfer for static sinqle-choice menus
2. Dynanr1c buffer for oynamic slngle-choice nienus
3. 11uICl ouffer for multi-cnoice inenus

P/OS SERVICES IJIBRARI

Faqe 1 3-3

OPEN PIENU FItE

0pens tne specifieo menu ceflnition

flIe. 0nIy one rnenu file can be
open at any t1ne. If another menu file ras open, it is closed before
the reguested flle is opened,
Instead of lssulng this caII wiren Ehe applicatlon executes, a default
menu definltion flle may be specifieo in the application insta.Llacion
file.
hhen the end user lnstells the appIlcatlorr, the default menu
file 1s asslgned to the appllcation anci autor'aticaIIy opened when t,he
appllcatlon 1s lnvoxed.
Ca

l.l :

CALL MFILE (status'f1]enamerriaxlen)

Parameters:

status

A two-word integer field used to return a code
lndicatlng Ehe resuIE,s of the requested operation.
Values for stat,us are Iisted at tne enci of this
sect,ion.

fllename

A string variabLe or Iiteral of any
length sliecifyirrg tne nenu definition file name
anri Eype. The directory used for the menu file is the
ciireccory in wnlch the application resides.

maxlen

lnteger variable or constant. This is t,he nraximum
length of che lmn,eoiately preceoing buffer or string
paraiTrecer. For reacj-onIy parani et,ers, this may be
the Lenqch of Ehe significant data oni.y.

P/uS SLRVICES LIbRAtiY

Page l.3-4

CLOSE MENU FIIJI.

To read another menu fran,e lnto the buffer,
CIoses an open rnenu fiIe.
use the OPEIi EtrU t'ILe service routine.
r'1

Call:
CALL MCLoSF. ( sEatus )

Parameters:

none

Status return codes:
See sectlon ?
Errors:
none

P/AS SERVICES LIEItARY

Page 1 3-5

READ IlENU FI?AI'tE

Reacis the specified menu frame into toe stacic menu buffer.
using
of tne display or pack rout,lnesr Ehe frame in the statlc buffer mayone
be
displayed or tnodlfled. Ihe gtobaL action string associated t.,,ith tne
franr e, if present, 1s returned to Llre applicatlon.
CaIl:

CAi,L MFRAME

( s Ea

tus, f rame ici, mex 1en, gI obat s tr 1ng, max J_en tength )

Parameters:

status

A t,vro-horC inteqer field used to
return a code lnoicatinq the resul.ts of
t,he reguest.ed operatlon. Values f or status are
Iisted at the end of this sectlon.

frameio

p.n 8-charact er s tring conta ining the frame identifier

maxlen

globalstring

maxlen

Iength

of the desireo nenu franre. Arr characters in frameid
musE be in uppercase let.ters.
Integer variable or constant. This is the maximum
lengtn of tire imnieciiately preceding buffer or
paran,eter. For read-only parameters, Lnis maystring
be
the length of the slgniflcant dara only.
An optional string variable of any Iength.
This parameter is usecl to return tlie gIobaI
action string associat,ed with the rr €tru frame, if
present. If Ehe buffer supplieo is snorter t.nan Ehe
global act,ion sEring., the string is t.runcated
to fit; if ttre buffer is Iongerr it is blan(-fillecj.
If this paTameter is not specifred, the glooal
action string is not returnerl. even if it
is present, in llre menu frame.
Inteqer variable or constant. T.'nis is tl.|e maxinrura
iengtn of Elie inrrrreciietely prececjng buffer or string
p\ararrreter. !or reao-onIy paramet.ers, rrlis may be
!he Lengch of rhe si,lnificanc ciaLa onIy.
An integer variaore. This parameter is a ret,urned vaLue
indicating how rrrucn of the ouffer or string pararneter
'das actually useo r,y- t.ir€ operation.

P/CS SL:RVICES LIbRARY

Fage 1 3-b

SHOi{ SINGLE.CHOICE }'tENU

Dlsplays a frame trom the current stalic iTiorlu buffer, and accepts the
Keystrokes entered 1n response by the end user. lienu interactlon is
t,erminated when tne user presses the DO key or a function key that
does noE have meanlnq withln a menu. l'he menu service ret'urns the
user's response to tne applicatlon ln the status pararfleter.
If t,he end user presses t,he HELP key while a menu is beinq dlsplayed,
the current help frame 1s reao from tne nelp ciefinition flle and
dlsplayed. If the Hl'RAME service routine was not used to oeflne the
current nelp frame, no help frame 1s dlsplayed. If ot,her help frames
are oefined for olsplay from tfle current HF RAHE, t.hey are displayed
when the end user presses t.he hELP key aqain. The application should
change tne current franr e cjesiEnation y;ith tiFRAME each tine a oifferent,
menu 1s oisplayeo. the slngle-cholce menu is redisplayeci wnen Ihe enct
user presses the RESU,lE key.
Before using this service routine to show the nenu, the appli.cat,ion
must use OpE fi Jv'dNU FILE, and iiEAD ME lrlJ FILE to place the f rane inEo tne
'renu Dutfer. (A ciefault menu file asslgned when the application was
installed rrray have been useo insteao of 0PEIJ 14Ef\iU FILE.)
Durlng the execution of this routine, r,enu services handl.es the
f ollorring f unction Keys:
CANCEL

00
ADDTTJL

OPTNS

Hc.LP

arrox keys

Tt tne itULP Key is pressed, the follor.ing keys are handlecj:
RES U J'l9

PRE'J SCREEN
NEXT SCPEEN

If tne executing program hacj assiclned f unction Key ASTs to Ehese )<eys,
the AST rouEines are overrloden. The state of the apfrlicaEion at the
time of llre call j.s saveo ancj restored bef ore conLrol returns to it.
0ther function keys terrtinate the rnenu c!1spIay, ar)o return a flag to
the executing apf,Ilcation lnoicating hhicn fur)ct.ion key ras pressed.
CaII:
CALL I,(ENU ( status,action, nax1en r length, dlsplayf lag, aodoptf lag,
. br
ms g 1

, ma x L e n I ms g 2 , ma x 1 e n )

Parameters:

status

A two-r,ord integer fielO used to return
a cooe inoic6tiriE tne results of

/AS SEK! ICE.S LIBRARY

acEion

maxlen

Iengt,h
displayflag

eddoptflag

f'a9 e t 3-7

the requested operation. Values for s!at,us
are Iiste,l in SecEion ?
A string varlaole ot any length. Thls
paratr'reE,er is useo t,o recurn the action string
for tne selected optlon.
Lf tne action strlng 1s Longer
than Che string provided, 1t 1s
cruncated; Lf 1t 1s shorter, the buffer
is blank-flIled.
Integer variable or constant. This ls the maxlmum
lengtn of the lmmeoiately precedinq buffer or st,ring
paramet,er. t'or read-onl.y parameters, this nray be
tne Iengt.h ot che slgnlflcanc daca only.
An lnteger varlable. Thls parameter is a returned value
indicating how mucn of che buffer or string parameter
was actually useo Dy the operation.
An inceger variable or constant. Thls paratneter
lnoicates what !ype of menu to show:
0 = fulL screen menu dlsplay
t = 6obreviated menu at top of screen
2 = aooreviated rnenu aE oo!,t,om of screen
An int.eger varlable or consEant. this paramter
indicates whether Eo sno* an Additional OpLions
flag or) the screen. VdIues are:
0 = rrio flag
I = r)isplay Adctitional Options flaq

msgl

A sEring variable or Literal of any lengtn.
1'his paramecer contains the text. to be
dlsplayed ds a ri'essage aE, tne botEom of the
screen oelow the nienu Dorder.

maxlen

lnteger variable or constant,. lnis is t,ne maxinun
length of the inrmediately preceoing ouffer or sEring
'riarameter. i or read-onIy F.aramecers, tnis may be
tne ]er)gE,h of crle siqnificanc ciata ottIy.

msg2

A string variable or liEeral of any length.
Ihls parameEer contains the text, to be
dlsolayeci as a message ac the bottom of tne
screen belo}J the menu border.

ISSL'ES:

*haE happens it HFRAIIE not used to specify current help frame
and HETJP is presseo?

Pase 13-8

P/OS ST-PVICE.S LIbRAKI
UNPACK MENU BUFFSR

Tne MU|lpK routlne unpacKs the S'IATIC buf f er into its corrponent, parts.
The parEs n'ay be modified tfrer) put inEo tne DYI'iAl'1 IC buffer using
DPACK.

l,iUlrPK accepts any nunr ber of parameter groups, plus an

status
initial
paraneter. Tne general case 1s that fielciid is follolved by some
number of assoctat,ed parameters. This group may then be follo'led by
another group sEalting "ith another fielci1d. special-case paramet.ers
nray appear anywhere in the caII.

CaIl:
CALL HUHPK ( munstatus, fieJdld, maxlen, buff, maxlen, length

.br

Irfie]oid,maxlenrbuffrmaxlen, lengtn ...1 )

Parameters:

munstatus

fieldid

A txo-ldoro integer field used to return
a cooe inolcacing t.he results of
the reguesEeo operation. VaIues for status

are llsted !n Sectlon ?
A strrng variable or Iiteral of 6 characters.
The freldio specifies wneE field is to be
filled or reEurned to paci: or urrpack a menu
bufter.
Valid fieldici
TITL

values are:

Eit.le field

::11"" ;i:::?":::1":"::,i:3"
g1oD61

t' 2 0r

heIP franre 1d
6htP
DFLInn oefault optlon number
PRI{T prorT,pt texL line
0PTNnn option t.exE for optlon nn (01-12)
ACT*nn Eccion st.rlng for optlon nn (01-12)
udLPnn heLp, franre id toi option nn (01-12)
KUyFnn soecification of key porIion ot option
nn (01-12) text

maxlen

ouff
max I

Integer variaole or constant. this is the maximuirr
Iengcn of che lnmeoiately prececilng buffer or string
parameter. I or read-onIy parameter s r t.his nray be
Lne Ier)gtn of the signlficant data only.
A st.rin\l variable af any lenqth. this paranieter
specifies the value of a flelo to be filleo
or returneci to pack or unpack a menu butfer.
Same as previous maxlen

P/OS SERVICES LIiJRARI

renqth

Pase 1 3-9

An inEeger varlable.

This parameter ls a returned vaLue
lndicatlnc how mucn of the buffer or string paraneter
was acrually useo by the operat,ion.

The followlng speclaL cases are deflned:
tDFLT, maxlen,defoptJ

Gets the default. opElon number.
defopt, is an integer varlaole rhlch

returns the default option number
(L-12) for tne menu belng unpacked.
IKl,Yhnn, maxlen, offset, lengthJ Gets the offse! and length

for the key portlon of optlon nn.

Page 13-10

P/0S SERVICES LIts'tARY
PACK DYNAHIC SINGLE CHOICE I'{ENU

CALL DPACK ( s tatus , f 1eId1d, IIr€XIen, bu f f , max Ien
i , r i e I d i o , m a x I e n , D u f f , fir a x I e n . . . I )

using specif ieo conrponents.
This rout.ine packs the DYNATIC menu buffer
groups
sEaE.us
parari'eter
of
any
number
t plus an initiel
accepts
DPACK
paranieter. 'fhe general case is thaL the fielcjicj parameEer is followed
lnls group may then be
by some number of associated parameters.
tieldid.
grouP
wlth
another
startinq
followed by anoEher
Parameters:

status

A two-word integer fleld used to return
a coie lnolcaEing the results ot
the requested operatlon. VaIues for status
are Listed in Sectlon ?

fieldlci

A string varlable or ]iteral of 6 characEers.
Tne fieldid specifles whaE field ls to be
t11Ied or returned to pack or unpack a nenu

buffer.

VaLid fieldlo

va.Iues are:

title fleLci
explanatory text, 11ne L, 2 or 3
global acLion s cring
GACT
glooaI neli: f.rarne io
GJJLP
oetault opt.ion number
Lr-L-t'nn
prompt t.exE line
PRJi f
option Eext for optlon nn (01-12)
0Pl'Nnn
accion strinq for oDtion nn (0i-12)
A C'f N;i n
nej.p franre io for opEion nn (01'12)
0HLPnn
KEYyJNN
speclficatlon of key portion of opEion
nn (01-12) texr
InEe,ler'variacle or constant. Tnis 1s the rrdXrFru;It
len'lth of Ehe immeoiatery prececiintt ouffer or stririq
pararnet.er. r or reaci-only parameters , tnis rnay be
the Iength of Ehe significant cjata only'

TITI,
l f,X Inn

maxlen

buff

maxl"en

A srring variable of any length.

This parameEer
be filled
to
value
of
a
fleId
tne
specifies
or reEurned to pacK or unpack a menu buffer.
Same as prevlous maxlen.

The follorring special-case parameters are defined:
IDF'Ltnn, maxlenl

Sets tlre cjefaulE optlon
r)uIDer t,o option nn.

IKL lrinn, maxlen, of f set,, Iengtn]

Sets tne of fset ancj lengtn for
the keY PorElon of oPtion nr)-

P/AS SERVICES LIERARY

Page 1 3-1 1

If sta'tus Is the only pararreter
or lt a fieldid ot CLRB
1s encountered, t,hen clear
tne dynamic buffer.
Note that only one menu may be pacKeo at a time because there ls only
one dynanlc buffer. 'Ihe oynarnlc buffer must be cleared before pacKing
oeglns. the order of supplylng f1elos with fteldid
1s not
slgnlficant.
ICLRBI

Page I3- Lz

P/T]S SERVICES LIBRARY
DISPLAY DYNAI.IIC IlENU FRAME

Disolays a single-choice nenu constructed from Ehe oynamic buffer.
the same as f or t,he MEt\U routlne.

f he operation is

Before using this service rouLlne to show the menu, Ene applicatlon
musE use OPUti MEiiU FILE and READ MENU FILE to place the frame int,o the
(A default menu file asslgned ilhen Ene appllcation was
menu buffer.
j.nstalled may nave been used instead of 0PgN MEr\{J r-ILE. ) Af ter f 11l1ng
tne buffer, use the'JilPACK f,,ENU tsUFFtR to access and modify t,he fielos
in the buffer.
dse the riisplay routlne to sholr the resulting rnenu.
These dynamlc menus are created under pro-orari cont,rol durlng
applicatlon executlon.
If the user pressed the HELP key, the help dispLay is initiated,
and
this rnerlu 1s reciisplayed when the user presses tne RESU|{E }<ey.
During the execution of this rouElne, the following function Keys are
nandled:

CANCEIJ

riELp
DO

ADDTNL OP IIONS

arroi{ keys

If the HELP key is pressed, the following

keys are also handleci:

RESUHE

PREV SCREEIT
NEXT 5Cr(EiN

If the executing apPlication had assigned function Key ASIs co these
keys, they are overrldcjen. The apFlicatlon state at the time of the
cai-I is saved anci rest.ored before return.
Call:
CALL DMEIvU ( s tatus , act lon, n'axlen, length, dis play, adcjoptt lau,
. Dr

msq1, maxlen, ns92, maxlen )

Parameters:

status

A t*o-*ord integer f ield r:sed to return
a cooe j.ncjicaEing tf.e resulIs ot
!he requesteo operation. Values for status

are Listed ln Sectlon ?
actlon

A strrnq inCo'*hictr 1s returneo
Lhe act ion string associared ritn

Ene option selecteo. If Lne
act,ion slring is longer than the
s cring provioed. it 1s
truncateo; it iE is shorter, fhe

P,/0S STRVJCES LIoRARY

Page 13-13

maxlen

buffer is blank-fi11ed.
r'axirnum Iength of an actlon
string 1s E0 cnaracters.
Integer variable or constant,. Thls 1s the maxlmum
length of t.he lmmedlately precedlng buffer or string
parameter. For read-only parameters, thls may be
the lengtn of Ehe slgnlflcant data only.

length

An integer variable.

dlsplay

aoooptflag

msgl

Thls parameter 1s a returned value
lndicating how mucn of the ouffer or strlng parameEer
was act,ually useo by t,he operation.
An int,eger flag lndicatlng the
screen display requesEed by Lhe caIler.
Q = fuII screen menu dlsplay
! = snort.-form menu, top of screen
) = snort-form menu, bottom of screen
An optional parameter whlch' 1f
present, is an lnteger flag lndicating
Lhe presence of adolt.lonal opLlons for
E,h1s menu. If Ehe parameter 1s
present, a zero value lndicates that
additional options are not expecEed by
t,tle appllcatlonr anci che aodltlonal options
indicator is not displayed. A value
ot l indlcates that adciltional opt,ions may
be cnosen, and Ehe adcjlEional options flag
1s oisplayeo'*icn the firenu frame. In any
case, tne aodit,ional optlons Key is Lreated
as any other function Key. Tlre display is
Lern'inated and tne Key character sequence
is oasseo to the application eicher througn
a functlon rey ASI (if t.he application
nas prevlously so requested) or ln
the stat,us return cocie.
A string varlabl.e or llteral of any lertgth.
Ihis pararneter conEalns ci)e text, to be
oisplayeo as d message at the botIon, of the
screen oelow the menu Dorcier.

maxlen

Same as i.rrevious maxlen.

nsg2

Same as rr sg1.

maxlen

Same as previous n6xl-en.

P/US SERVICCS LIBfiARY

Paqe 13-14

PACK I{UIJTI CI.'OICE (DYNAMIC) MENU

Packs tne multi buffer tllth peripheral parts of the multi-cnoice ri€our
3.uch as the titIe.

CALL MPACK (status,fieldidrmaxlenrbuff ,maxlen

-br

Irf ieldidrmax.l.enrbuf f ,maxIen...] )

Parameters:

status

A t*o-l{ord integer field used to return
a cooe indicacing tne result.s of
tne requesteo operation, VaIues for status
are lisce,i in Sectlon ?

fieldid

A string vari;bIe or literal of 6 characters.
Tne fielcjio specifies hnat field is to oe
filled or returrred to pack or unpack a rnenu
buffer
Val-ici fieldici values are:

maxlen

buff
maxlen

TI'1'L tiEle fielci
Te XInn explanatory text line I, '2 or 3
GACI global action sEring
Gr{LP giooal help frane 1o
Ol-L I'nn cjef ault ogrtion number
Pt?dT prori!rt. Eexr l ine
0P'j'r\inn opt,ion rexE for option nn (01-12)
ACTi'nn actlon sCring for option nn (01-12)
UHLPnn nelp frame io for oDtion nn (01-12)
KEYiJnn speclficatlon ot Key portion of option
nn (01-f2) text
Inteqer variaole or constant. This is the maxin,um
lengcn of Lne imnerjiately preceoing buffer or string
pdrarir eter.
For fead-onIy parameters, Ehis rnay be
tne lengcn of the siqniflcant oata onIy.
A strinq veriabLe of any Length. This parameter
specifies Ihe value of a field to t-e filleo
or returned to pacK or unpack a rrenu buffer.
Same as previous nraxlen.

;

P./0.s sEirvIcEs LltsiiAiy

Page 1J-15

DISPLAY },lUTJTI-CHOICE (DYNAI'1IC) I'{ENU FRAME

Dj.spIays a mulri choice menu from Lhe multi-buffer.
cALL l'{l/,ENU ( s tat,us, opEioncount, maxlen, optlon-array, Iimit,
re5 ponses , respons ear ray, aidopt flaq r [rs9 1 r max Ien, msg2 [raxlen )
'

status

A t'*o-lt,ord lnteger field used to return
a cooe inoicating the results of
the requesteo operation. VaIues for status
are listed in Secti.on ?

opt,loncount

An integer variable or const,ant. This parameter
1s orre elenrent of optlonarraY.

lnteqer vsriable or constant.. This 1s the r'axi[rur0
length of the immediately preceding buffer or string
paratneter. t'or read-only parameters, tnis raay be
the Ienqth of the signiflcant daE,a onIy.
ootion-array
A two-dimens!onal array of cnaracters; dimensiotted
with tne parameEers riaxlen Dy optioncourrt.'lne
cnaracters 1to maxl.en must De contiguous 1n m€firoFt.
An integer variaole or const,ant. Thls parameter
limit
sg;ecifles tiie maximunr numoer of optlons tl'tat, may be
cnosen irr d nrulti-choice menu.
An integer variable whlch returns the number of
res.oonses
opEions actually selected from a multi-choice Inenu,
responsearray An integer array with tne lenotn ot the value in
tne limit. parameLer. 1'his parameter is returned *it.h
a Iist. of Ehe opcion nunbers selecced trofir a
rrruL t i -crro ice rnenu.
addoptf Iaq
An octional rararneter wnich, if
present,, is an rnteger flag incjicatlnq
the presence of adcitlonaL optlons for
cnis rnenu. If the paranr eter is
present, a zero vaLue incjicaies t hat
addi t.ional options are noc expecEed by
tne applicatlon, ancj the ad,jiLional oPtions
inoicator is noU cjisp.Layed. A value
of l lnoi.cates that, adoit. lonal options rnay
oe cnosen, tinci Ene acirJitional opEions fIa<f
is cjlsplayeo'*1tn the menu frame. ln any
case, the aooitlonal opEions Key is treated
as any other function Key. Tne disnlay is
.Eerminatec end Lhe key character sequence
is passed to the apfilicatj or elther throuah
a fi:ncLj.on Key AST (if che appllcatlon
fras previously so requested) or in
rne stafus return cooe.

maxlen

P/QS SERVICES I,tBRARY

msql

A scring variable or Iiteral of any ]ength.
1'h1s pararneter contains the text to be

screen belo$ the nenu border.

maxlen
msg2

Same as msg1.

maxlen

Sanre as previous maxlen.

Same as prevlous maxlen.

Page 13-1b

P/OS SEP.VICES TJItsRA!tY

Page 13-17

13.4 HELP SERVTCE RUUTITiES
I

P/os provicies access to the lrerr services through Ehe foltor+ing
service routines.
I

OPEN HELP FItE

0pens the specified help definition file.
open at anY time. If another nelp file

0nIy one help file nray be
is open, it 1s closed before

the reguesE,ed file 1s opened
Instead of issuing this caII when the applicatlon executes, a default
Irerp oefinition fire may be specified when the application is
installed. In this case, when tne end user regues Es nelp for thls
applicationr tne defaulc help flle is used.
This calj. ooes not result in a display. If only defines tne current
help flIe name ano Ene current frame.
CalI:
CALI, HFILE (sEatus, f ilename,nraxlenrfraneid,maxlen)

Parameters:

status

A two-word integer field used to
reEurn a cocje indicating the results of
tne reguested operaEion. Values for status
are listei in Seccion ?

filename

A string specifying the file
name and type for the nelp file.
(Ihe oirectory used for the help file is
the ct irectory irr wnicn !he
appl ication resicies. )

maxlen

tnteger variabl.e or constant. l'his is tire maxj.num
lengLn of the immeoiaCely Freceoirrg tuffer or string
paran'eter. For read-onIy parameters, thls rnay b€
the lengCh of the significant dat,a only.
An eignt-byte srring containinq tlte
KeY to Lle tlseC in retrlevinE the
desired help franie. Franreid may not be
blank or of zeto Ienqth; a valid frarreid
rnus t, ce specifieci.
Same as previous rnax Ien.

trameid

maxlen

P/O.S SERV ICES LI HRAiiY

Page l3-1tl

CLOSE HELP FILE

it one was prevlously oPen. P/OS dlsplays
foltowing message if the HELP Key is suDsequently pressed:

C.loses the help tile

t,he

'ISORRY, NO I.IEIJP AVAII,ABLE'I

CalI:
cALL HCL0SE (status)
ParameEers:

A two-word integer fleld used to
status
Ehe
a code lndicatlng the results of
operation. values for stat,us are Ilsted 1n section ?

return

requested

P/OS ST.PVICES LIb'TARY

Page 13-19

SPECIFY HELP.FRAI,{E

Specifles tne ldentifier of the frame to be dlsplayed v'nen heip 1s
r-equested. If a default, help cietinitlon flle was asslgneci yihen the
applicatlon was installed, this caII is unnecessary. This call does
not result, in a oisplay; 1t simgly defines the current, frame.
CalI:
CALIr HFRAME ( status, f rameicl, maxlen)

Parameters 3

"iF'

st,atus

A two-word lnteger fleld used to
return a code indicating the results of
f,ne reguested ope16rlon. values for status
are l1sted 1n SecElon ?

frameld

An eight-byte strlng contalnlng the
Key to be used ln retrleving the
oesireci help frame, Frameld may not be
blank or of zeEo lengtni a vallo frameid
must be speclfied.

maxlen

Integer varlable or constant. Thls 1s the maxlmum.
IengEir of the lmruedlaEely preceding buffer or string
parameter. For read-onIy paramet€rsr this t0ay be
tne length of Ehe slgnificant daca only.

P,/OS SE XV i CES LI BRARY

Page 13-20

DISPLAY iiELP FRAhE

1:!is routine retrieves and dlsplays the current lrelp frane from the
current help fiIe. The user response is accepted. The Iast speclfied
help frame is tne one nanred in a SPECIFY hl.:LP FrrAMg servlce routine.
Tne help frame specified is reaci lnto the help buffer. The executlng
application rrust restore the previous screen display atcer using thls
rouEine.

must be ocen. Lt no help tile is open or no current frame
has been defined, t'ne message NO HELP IS AVAIiJABLE is displayed. If
tne current franre as specified by a previous call is t,o oe used, then
the frarreid parameter may b omltted or may be specified as atI blanxs
or of zero Iength.
A status code indlcating that tne nressage was displayed is returned to
'the user's response may lead to tne aisplay of
the applicatlon.
addltional help frarnes. hhen the user presses the REsbtlE Key, control
returns to fhe executinE application. Durln9 the execution of this
routine, the follow:.ng function keys are hanclLec:
A help file

KLSLiHE

PREV SCREf,N

lf a nelp frame 1s displayedr the fo).lowing keys are handled:
NEXl. SCREEN

If a help menu is displayeo, the fol lowing Keys are nandJeci:
CA h C:lL
DO

arro* Keys
If the executing application hacj specif ieci f unction ,Key ASTs, these
are overrioden. Ihe appllcacion state a! the linre of the call is
saved and res !oreci Defore control returns to it.
CaII:
cALL HEL,p (sEatrrs [,fr3r:Qj.d,max]enJ )
Par6meters:

status

A trro-ivord inteqer field used Eo
return a code inolceting tne result,s of
tne requestecl operation. Values for status

are Listed in section ?
fraireid

An erght character string containilrg t,he
Key t o be useo iri rerrieving c.he
cjeslfed nelp fran,e. Fralni:lcr trrdy not oe

blank or oI zero lengtlr; a vajid franreici

n,uSt be soeci.fieci.

P/OS SEKVICIS LIBKARY
max len

Page I3-2r

lnteger variable or constant. lhis is lhe maxlr:ium
len'lt,n of ihe iurn,eciiatery precedinq buffer or string
parameter'. i'or reai-onIy pararneters, tnis may be
tne len,.tth of Ehe signitlcant data on1y.

Page L3-22

P/OS SERVICUS LltsRARY

13.5 YF-SSAGE .SERVICE ROU.TIIiFS
The folloxing service routines provirie access to the rnessage file
durirrg prografl, €X€cucion.
READ HESSAGE

Reacjs t,ne specltied message from t.he speclfiecj message flle
lnto a
ouffer supplled by the appllcation.
The message file to be usecj must be specltled for each caII to RDMSG.
Thls aIlows multipte message tiles to be in use by one application,
although only one file wiIl be oper) aE any given time. For example,
tne applicatlon can have a message file whlcn is distincc from that,
used by the lanquage-specific Gbject, Time System.
file cannot be opened or read, t.he buffer is filleci wiEh
If the messge
the message ttggN'f 0Piiv MESSACE FILt.'t
If the buf f er is snorLer than the message recorci, t.he recorci is
truncatecj; if t.he ouffer is longerr it is blank-fi11ed. This
faci.Lity may noE be accessible during asynchronous processing.
Instead of issuing t.his call when the aoplication executes, a ciefault
messaqe defj.nitlon fj.Ie may be soecified *nen tne aoplication is
installed. Tne assiqned essage file 1s usecj if Ene file nane
parameter is nor specified.
Tnls is for aoplicatlon use onry.
Layereci prodi.rcts ' sucn as Ianquage 0b jecc f ine Syste'irs ((.r1'S routines)
or sirnilar programs, must supply the fite specificati.on as a parameter
wit,h this callrTr

Ca11:

CALL RD14SG (statusrf ilenamermaxlenrf rameiCrrnaxlen,buf f errmaxlenrlenqth)
Paramet.ers:

status

A two-word integer field used
to return a code indicaCing tne results of
tne requested operat,ion. Values for scacus
are listeo in Section ?

filename

A scring specifying the tile
name dnd type for the nelp file.
(1he oirectory used for the help file
tne oirectory in whicn the
application resides. )

rnaxlen

fratneicj

Integer varieble or constant. 1'his is the maxlnum
lengt,n ot Ene imrnetjiately prececjinq btlffer or string
pararneter. For reao-only par6meters, tnis r1l3! be
tne lengEtr of the significarrr data onJ.y.
An eiqht-byte string cont.aining the
Key to be used in retrievino Ehe

P/OS SERVJCES LIbRARY

maxlen

Pase l3-23

cieslred help frame. Frameld may not be
olanK or of zero Ienggh; a valld frameld
nius t be speclf 1ed.
Same as prevlous maxlen,

butfer

A string variable of any length. This parameter
speclfles the value of a fleld E,o be fllted
or returned t,o pacl( or unpack a menu buf f er.

maxlen

Same as prevlous maxlen.

length

An lnteger vartable.

Thls parameter is a returned value
lndicatlng how much of the ouffer or strlng parameter
actually used by the operation.
'{as

P/AS SEkVICES LId;iAdY
I 3.5. 1

Page L3-24

Values xecurned In StaEus

'fF-e st,at,us F,arar0eEer is used to return error

tndicatlons Eoa calllng
program. Tne first word of the two-word array indicates che source of
the errori tne second '*ord lndicates tne actual error.
AI1 values
belo'rr are ciecimal.

tatus value

meanlng

-+1

lio error;

f or menus, DO '*as pressed.

Qual1f1ed success: for menusr so[i€ functlon key
besicies D0 was pressedi for otner operations,
a record or fleld was truncaEed.

-+2

RSX DSr{ error ( DsH in S'tATUS-+2 ) .
Rl':s I/u sE,at,us error ( I/O cocie in STATUS.+2 ) .
P,/0S error in HeLP.
P/05 error in menus.

-1
-2
-4
-5
-6
-7
-8
-9
-10

I/A error in terminal init.laIizaEion.

Pars ing error.
Proces s terminated by key ot,her t,nan DD.

Irnproper paranieters,

Insufficient buffer space.

If STATUS ls +2 for a menu dlsplay operatlon, then STATLjS+2 indlcates
which function Key wes pressed es fo]Iows. Functlon key values
( decima I ) are as fo I lohis :
VALUE

KEY

tJ0LD SCkUtsir

PRIIIT SCREEN

BR EAK

SETUP
F5

INTERI<UFI

R ES LJi4 r,

CAN CL,L
I"A,IN SCPET,I.J

I
1C

UXIT

F11

F12

r13
APOITlOhAL OPTIDITS

14
15

HLLP

16
L7

DL)

Ft7

1€i

r 1b

r."19

2A
2L

F20
l'I N IJ

22
'23

II.$si{1 hl-liE

RE..TUVU

s gLLct

. ' ,.' :}
P/0S SERVICES Llb'iARY

Pase 73-25

25
26

PREV SCRLEN

2'l

cursor up
curso.r left
cursor down
cursor rlght

28
29
30

3r
32
33
34

IiEXT SCREEll

PF1

PF2
Pi- 3

pF4

The forrowlng decimal values corresond to keypad keys in
mode.

VATUE

KEY

nilnus

36
37
38

comma

STATUS is
f olIows:

-1
-2
-3
-4
-5
-b
-7
-ti
-9
-10

period
EIiTER

39
40
+2
43
44
45
45

apprlcation

I
3

4
5

6
7

I
9

-4 or -5, then ttre p/OS error is lndicated in STATUS+2 as
optlon r ?reater tnan maximum
t.ext line f qreater than max.
multiple occurrence of once-onIy fletd
erroneous frenie outfer contents
title fielci Iengt.h error
text tielc len,tt.h error
frair,e error
dynarnic parse error (unKno,*n flelo id)
ulciple occurrence of once-only fields in
ni

oynaroIc menu frarne
unKnor+n escape sequence

P/OS SERVICHS Lll'iKARY
25
26
21

Pase 13-25
PREV SCRE:f,rr
IiEXT SCkEEtr
cursor up

2g
29
30

cursor left
cursor dovJn
cursor rlgnt

PFL
PF2

Pb-3

P?4

The folLowing decimal values corresond to keypad Keys

mode.

VALUE

KEY

nrlnus

36
37
38

comma

39
40

+2
43

44
45
45
47
48

in appllcation

period
EIi T gR
0
1

2
3

I
5

6
7

If STATUS is '4 or -5' then the t,/OS error is lndicated in STATUS+2 as
follows:
-1
-2
-3
-4

-5
-o
-1

r!
['

l-10

option i ?reater tnan maximum
text Iine d qreater than max,
multiple occurrence of once-onIy fleld
erroneous franie outfer contents
tit.Ie fielci length error
t,ext tielc IengE.h error
fran,e error
dynarnic parse error (unicnown fielcl id)
niulciple occurrence of once-only fields in

oynaroic menu frame
unKnordn escape sequence

P/OS SERVICES LIBRARY

13.6

Page t3-26

}IISCELTANEUUS SERVICES

FA.IAL ERROR

An application progran should call this rouElne in

the event. of an
unexpected and disaollng error conciition which prevents t.he
appllcation fronr continuing.
If this routine is calleci, lLne 22 of the screen is blanl<ed and the
message "AppIicatlon error. Fress RESUr'1E t,o return to t''ialn I'l enu. " 1s
ciisplayed on 11ne 23. The - message specified in thls routlne is
displayed on Iine 24.
'nhen the user presses Ehe RESI.,HE key, the applicat. lon 1s aborted and
the olsplay returns to the main menu. The message strlng shoulo
contain informaClon v'hicn wilI teII the application oeveloper *here
The end user can report this
ancj '$hy the appl!catj.on failed,
informa[1on Eo the Support Services Hot]ine. This routine snould JOT
be useci to avold nano.l.ing user errors in a friendly vray.
CALL FATTER (messaoe

' msglength )

Parameters 3
message

msglengt.h

st.rlng variable or literal, any lengEh
'integer constant or variable

lr
i'
I

P/OS SERVICES LISRA;TY

Page 13-27

GET KEYSTROKE

Gets one keystroKe, status indlcates tne type of key and key name.
The keysEroKe is not echoed on the screen.
CALIJ GETKEY ( status )

status

A two-word integer array.
Value for status are:

+1
+2

the key is a slngle ASCII character
t,atus +2 contalns the ASCII code
Ehe Key ls a functlon key
status +2 cont,ains a code for the
function keyi see token table aoove
see "Values for STATUS'i table 1n
s

Sect,ion ?

stat,us=-7 r status-+2=-11 means that
an invalid CSI sequence was found

Page l3-28

P/OS SLRVICE-S LIBRARY
PARSE SIRING

Parse a string for a CSI sequence. Tne characters 1n Lne parameter
ouff are scanned from the left unt.lI a CSI characEer is founci. The
sequence,*hlch follows is parsed ani t.ranslatec into a token value
lncjicating what functlon key terminates the string. ?he Length ot the
string up to the CSI character is returned in the pararreter msglength.
cALL PRSCS'1 (status, buff , bufflengthr FSglength)
Parameters:

stafus

Two-word int.eger array.
Values for status are:
+2
a valid CSl sequence \{as found
st.atus +2 contains the token vaLue for
thar seguence; see che Eoken t6ble aDove
<0
see values for status taole in Section ?
status=-7r status-+2=-12 means t,nat
no CSf sequence wes founci

buff

A string variable of any length.

bufflengtn

An integer indicating

msgfength

An integer variable.

the length of- buff.

P,/OS SER V ICES LIhRARY

Page I3-29

NEli FILE

Solicit the narte of a new f1Ie Eo be creaEed. The netll file
speclficat,ion forn is clisplayed anci the user is allowed to enter Cne
The filetyoe must be a default
name portion of a file specification.
flle type of Ehe form.xxx and this field may not, oe ollritted.
0n return of this rout,ine, the filename parameter contalns a fuLl. DcL
fiLe specification, including devlce and dlrectory. F1l'e type is
moditled to reflecc any change made by Ehe user *,itn an Aodltlonal
option. see section ? for possible values for the paramater st.at,us.
CALL NEhFIL, (status, f ilename'namelen'fileEypertypelen,

.br
text1, textl 1en, rnsg1, msgllen )
Parameters:

st,atus
fllename
namelen

A t,wo-worci integer array.
A strlng varlable up to 50 byEes.
An integer indicating che lengch of the
filename.

filetype
typelen

A sEring va'riable of 4 bytes.

text,1

A scring variabLe or literal of any Iength.
The strinq t.ext1 1s wriE,cen at the top ctf
t'ne torm.

textllen
msgl

An integer indicatj.nq the Iength of text1.

rnsgl len

An integer indiating the Iength of filecype.

A st,ring variable or Iiteral of any length.
l'he string is'*rlt,ten belor Ehe fornr .
A.n integer inciicating the IenqEh of msgl.

P/OS SE,RVI.CES LIERA}iY

Page 13-30

OLD FILE NAIiE

'fhe caller
Solicits t,he nanes of one or more existino f1les.
spAciftes a selection crlterion for file names from the currenE
directory, the rnaxlmu,n number of cholces the operator will De alloweci
to make ' anci several pieces of text Eo be oisplayeci oD the enu
(text1, msg1, msg2). The routine returns a tisE of selected file
names (fllestrbuf)
and the nunber of choices actualty made
(nunrchoices). The array (sizearray) contalns tne Lenqth of each file
specification in firestrbuf"
File names begin every 50 bytes in
filestrbuf wlth blanr-f111 to the right as needed; tne lengttrs in
sizearray indlcate the actual Iength of each name.
CALL 0LDFIL ( status, numcholces, f ilestrou t,sLzearray, wllcicardspee,
.br
rir

wcs len, t.ext 1 , text 11en, msg 1 , msgl len, msg2, msg2len )

Parameters:
.--

status
numchoices

A two-word integer array.

f ilestrbuf

A s.trlng variable .Listing the selected f lIe names.
File names begln every 50 bytes with blani< fiII to the
right as neeoed

sizearray

An inteqer array indicacing tne actual Iength of
each file specification in filesLrouf,

wlldcarrispec

A strlng variable or riterar

wcslen
t,ext1
textllen
msgl

An integer variable indicating the maximurn number of
cnoices Ehe user may maKe.

that speclfies
the file selection criterla.
An integer inoicating the Iengtn of wilocardspec.
A strinq variable or Iiteral of cext, to be oisplayeC
at the top of the scree|r.
An inteoer indicatinq tne length of text1.
A strinq variable or lireral of t.ext Co be ,)isplayed
al che botLofti of the screen.

rnsqllen

An integer indicating the Iengtn of msg1.

nsg2

Sarr'e as nsq1.

msg2len

An integer lndicating

tne Iengtn of lnsq2.

P/OS SERVICES LIERARY

Page 13-31

CURRENT DATE AND TIME

ReF.urn Ehe current ddte and tin,e. Date is returned 1n datescr 1n. 6n
of the f ollowinq f orrrat,s:
dd-rrrmm-yy (example: 08-l'1ay-82)

'' :
.r -:) '
dd/nn/yy (example z a5/L2/82)
-..Time 1s returned in timestr in one of the followlng formats: ,"' -.r:. - ,
hh:mm:ss (examples 13:45:50)

.::'.-:l-:.1--i

hh:nm:ss x.m. (example: 1:45:50 p.m.)

tr-.-

'-.;

:."

.i.'. :' -.:-;-'

The formaE 1s determlned by setup options. These formats are
truncated, 1f necessary, to flt. the str1n9 varlable provided. Ex-tlg-,:-.r:
length in these variables 1s unmodified, not hlanJ<-fi1]eci, A string
Ienqch may be zero if either oate or t. llne ls not.wanted, buE alI
parameters must still be provided.
-:-.
cAIJt xTIlr'E (datestr, datelen, timest.r, timelen)
Parameters

dat.estr

A string varlable.

datelen

An integer indicating the length of ciat.estr.

tlmestr

A scring variable.

t,imelen

An integer indicating the Iength of timestr.

P/0S SERVICES LIBRAxY

Page 13-32

WAIT FOR RESUME KEY

This routine echoes aII keystrokes i'1th a bell characler exceft the
when Ehe RUSUI'iF: Key 1s pressed, t,he routlne returns to
RESUME Key.
caIIer.
the
CALL !{TFiES ()

t;
t

P/AS SERVICES LIBRARY

Pase 13-33

GET USER NAIlE

0otalns Ehe name *'ith wnrch the user signed on. Thls name may be up
to'-40 characters. rt is truncated to fit the space provlcied.
CALL USRNAfl (username, namelengttr)
Paramet.ers:

username
namelength

A strlng varlable.
An lnceger indlcating the lenoth of username.

lii\
i

P/US SI:RVICES LIBRARY

Page 1 3-34

DISPLAY ON HESSAGE EOARD

Put a messa-qe on the P/OS rressage boarci..Thfs: calI enters the message
firto a -gueue and rlngs the keyboard betl. :Tber user sees the n-,,essage
whi:n:DlspL-ay'message/status 1s sel..ecteci frorn the Meln Fienu.
cALI/: ysc,+1.r,0, Cnse, msslen)

Parameters:

msg
A strlng varlable or llteral.
msglen An lnteger indlcatlng the length of msg.

'.:
P/OS SERVICES LIBRARY

Pase 1 3-35

GET CONFIGURATION TABLE

0f,talns a copy of tne Pro-fesslqnal hardware conf lquratlon tabIe. Th-ls
'.taole
1s bullt by the Professlonal-dlagnost,lc f irnware eve'ry tlme Ehe
Professlonal is po$ered on. Thls call copies the lasc segment of
words of thls t,aole (segment ls cjetermineO by tabl e 1eng thJj :igto,; 3qe
caller's buffer. See ? for a deflniElon of the conflguratlon tabIe.
'y 'r i. '-f.'
2 +!
CALL CoNFIG (configtabler tablelength)
^.

Parameters:
con f 19t abl e

An lnteger array.

tablelength

An integer lndlcatlng the lengt.h of conflgtable.

fssues:

1. where is tne conflguration table deflneci?.

APPEI,JDIX A
SUMI'lARY OF ENTRY POlNTS TO P/OS

A.1

SUI'111ARY OF Ei.ITIiY POINTS

To be supplied.
A.1 .1

FiIe Services

Io be supplied.
A. 1 .2

Disk Servlces

To be suppJ.ied

A.1.3

Commrrnlcations

I'o be supplied.
A. 1 .4

Editor

To be suppl ied.
A.1.5

User Interface

To be suppIled.

SUITI'{ARY OF h;NTRY POIIiIS TO P/OS

A. 1 .5

llscel laneous System .servlces

I.9 De s upp I led .

Page A-2

APPEI{DIX B
THT: DEC HUI,TINATIONATJ CHARACTER SET

8 -Bir
Decimal

Octai

Code

Character

000

nul.

001

SOH

srx

003

ETX

004

EOT

005

ENQ

006

007

ACK
BEL

010

011

0t2

013

\lT

014

015

016

01?

020

DLE

021

DCl

022

021

DC2
DC3
DC4

'Rcmarkr
Null, tape feed, shift,, 'P

Start of heading, start of message, 'A
Sta$ of text, cnd of address, 'B
End of !ext, end of message, 'C
End of transmission, shuts off TWX
machinc, 'D

Enquiry, WRU, 'E
Acknowledge, RU, 'F

Bell,'G

Backspace, format effector, 'H

Horizontal tab, 'I
Line feed, 'J
Vertical tab, 'K

Form feed, p8ge, 'L
Carriage return, 'M

Shifi out, 'N
Shift in, 'O
Data link escape, 'P
Devicc control 1, 'q
Devicc control 2, 'R
Devicc control 3, 'S
Device control 4, 'T

(continucd on next page)

Dciimal

8=Bir I

Octal

Code

Character

nqi

-'NAK

026

SY'N

a2i

iire
.'

030

CAN

031

032

033

SUB
ESC

034
q35

,o
30

036

037

_040

US
SP

.tJ

041

2i)

,..'Remarks

Negative acknowledge, ERR. "U
Synchronous idle, 'V
End-of-transmission block, logical end of

rDedlurD, W
Cancel, 'X

End of medium, 'Y

Substitute,'Z

Escape, prefix, shift, 'K
File separator, shift,, 'L
Group separator, shift, 'M
Record separator, shift, 'N
Unit separator, shift, 'O
Space

043

Exclamation point
Double quotation mark
Number sign

a14

Dollar sign

045

046

042.

Percent sign
&

050

(

Q5l
.052

)

Ampersand
Aposirophe
Left parenthesis
Right parenthesis

"053

Asterisk
Plus sign

034

Comma

055

Minus sign, hyphen
Period, dot
Slash, statement seperBtor

047

0q6

057

060

061

One

062

Two

063

064

o.1

Zero

Three
Four
Five
Six

065

066

06?

Seven

0?0

Eight

071

0i2

Nine
i

0?3

0i4

0?5

Colon
Semicolon
Left angle bracket
Equal .sign
Right angle bracket

075

477

Question mark

100

At sig'n

r01

102

A
B

r03

Upper.case A
Upper-case B
Unper-case C

(continued on n€x! page)

Decimal
,-'Codc

.-..,.t

.1.

8-Blt
Octal

, ,eode'.

-=€Jraraetet

Remarka

D
E
Upper-iase F
I.Jiper-case G
Uiper.clse H

104

69 ?',

1bs

106

D
E
F

lL.

l0?

li0

111

: f-'

TL2

lgfper-case J

113

114

tJpper-cese K
Upper-cdse L

115

Lftper-crise M ..

116

11?

r20

t2I

tLa

t23

124
125

Upper-case
Upper-case O
Upper-case P
Upper-case Q
Upper-case R
Upper-case
Upper-case
Upper-case U

t26

127

v
w

Uiper-casb V
Upper-case W

130

Upiir-casd X

131

Upper-case
upper-case 4

Lefi bracket, shift K

732
lJJ

134

135

136

13?

110

141

98
oo

112

t13
t11

100
101

145

102

146

103

1li

i04

150

Upper-case
Upper-case

i
i

lJpper-case I

S
T .

Y "

Backslash, shift L

Right bracket, shift M
Caret, circumfle:.
.

105

151

106

152

l0?

153

108

154

109

155

110

156

1i1

157

rt2

160

113

161

114

762

115

163

Underscore

Accent grave
Lower-case a
Lrcwer-case b
lrcwer-case c

Loner.case d

e
f
C

Lower.case
Low'er-case
l,ower-case
I.ower-case h
Lower-case i
Lower-case j
Lower-case k
Lower-case I
Lower-case m
Lower-case n
Ircwer-case o
Lower-case p
l.ower-case q
Lower-case r
I-ower-case s

.,
'..

(continued oo next page)

Decimal

8 -sit
Octal

Code

. Code

116

164

Lower-case t

11?

165

LOwer'CaSe U

118

166

lpwer-case i

119

16?

120

170

121

171

w
x
v

t22

t72

tzo

1?3

r24

li1

Lower-case w
Lower-case r
Lower-case y
I-ower-case z
Left brace

72.5

1?5

126

1?6

12i

71i

Remarks

Character

DEL

Vertical line
Right brace
Tilde
Delete, rubout

DEC SUPPLEHENTAL GRAPHIC SET

Code

8-Bi t
0cta I code

lZE

200

'*]feservecl

-129

201

Reserved

202

Reserved

131

203

'Reserved

132

20q

IND

133

205

NEL

Next I i ne

134

205

ssA

Start of selected area

135

207

ESA

: End of selected area

136

210

HTS

' Horizontal tab set

137

211

HTJ

Horizontal tab with justify

t3q

212

VTS

Vertical tab set

139

213

PLD

Partiai I ine down

1q0

214

PLU

Partial I ine up

l4l

215

Reverse i ndex

1\Z

?-1 6

ss2

Single shift

143

?_17

ss3

Single shift three

144

?_20

DCS

Device control string

145

221

PU1

Private use one

146

222

PU2

Private use two

I I{7

22j

STS

Set transmit state

118

z2\

ccH

Cancel character

149

225

Message waiting

226

SPA

Start of protected area

15r

227

EPA

End of protected area

152

2j0

Re s e rved

153

231

Reserved

154

2j2

Reserved

155

2i3

Decimal

Character

Rema rks

' I ndex
)

csr

two

Control sequence introducer

- Decimal
code

._ -*".-5-bi.t
it:'*octal
code

158
.!.-:

.. -..

235

0sc

Operati ng system command

236

Privacy message

APC

Appl i cat ion program command

- -.;

-^*,

'string terminator

--.:-^....-- :'

. ..157

::-l

r.-:):.i

:ii

159

237

160

2\0

i . ;:'3.-, n: i'i. ,-:'-: : ; - ,-

Rese rved
I

162

2t+2

a.:i"."J r.; ir

165
165
167
58

Cent s i gn

Pound s i gn

2\\

':i

2\5

Yen sign

2\6

Reserved

2\7

Section si3n

.250

General currency. sign

Feminine ordinal indicator

Ang le quotat ion ma rk I eft

ti:-'::."
'' i '

i:i,:'

i,':!r-: i{l:

159

;'',:-:i:i{"'-251

70 ii,-,

' ., i, 's:t25tr

1 :,-;.,',.: :, :', :; ' fi: i?t3
1J2, : ,.i;:- ri: ::. -1 i + : i?54

:,s:.,L73:\,,s'i:':: i. :

Reserved

''ll':

lnverted exclamation mark

z\1

163
1

l=;: ; ..

i'i":

: j:::JA

Re se rved

! ;.::25$

Reserved

:ti:,'1jl!.':'"e .:jI; .: i:r256
>:-1i7,9.:- r, ':i '".' I : +::Ag7
t il,/.(t, ' 1r.;, i'- ,: - ; '. :

,.iEr

177

,.:.-.,i

r...,r.'
.J

-.'

r..-:;

-::t

178
,.:.F.-4

179

l:.,

i,-

26?

Res e rved

Degree s i gn

Pl uslmi nus s ign

Superscr i pt 2

Superscr i pt 3

3.r]

263
:':-

j 3: ' i:
i,-i\-.

Rese rved

"i'"t?65:

Hicro s ign

| :. :266,

Pi lcrow, paragraph s ign

-' ''' i" | ::261-

Hiddle dot

''::ri

-1

1q2

't,-,4"ac

'26d

-a,:l-;-

Re s e rved

z6\

1BI

' t':f

a.??-: "261

: -:".

..-:rr.l-r,*::.3ir.-:1
180

'-Remerkg

sr " " '

-*". 27\ -

_156 - _*

.--" -Character

1::.

]

,':..

":--'

Character

Rema rks

Superscript I

i:f

..t85

271

186

272

Hascul ine ordinal indicator

187

273

))

Angle quotation mark right

198

27\

t/4

Fraction one quarter

189

275

1/2

190

276

r9r

277

192

300

193

301

j.': t

a'-i
\\'

UI:

rlri.
Fract ion one ha I f

iii

):1

Reserved
I i'

: li

lnverted question mark

":-,

Capi ta

1\i'

I A wi th grave accent
:)^

Capital A with acute accent
:i:.

194

302

Capita I A wi th ci rcumflex accent

- i^

195

i.l:

Capital A with ri lde

303

196

30I{

Capital A with diaeresis
orr umlaut mark

197

305

'198

j05

lapital A with ring i,
Eap i ta l AE d i pthong :'

199

307

Capital C with cedill:-:

200

310

Eapital E with graveidccent

201

311

Ga-p i ta

202

312

Gap-ital E wi th circumf'lrex accent

203

313

Gspital E with diaeresi'i:s or

i'. ,

I E wi th acute .6ccent

umlaut mark
:-

20t1

314

Cap'i ta I

205

315

Capital I with acute accent
..a

206

315

I rvith g rave accent
:-

t
.

Cap i ta

I I wi th c i rcumfl ex accent

!;'l :

Capital I with diaeresis
lli
or.pmlaut mark

207

317

208

320

209

3?.1

Capjtal N with tilde ii':

210

322

Capital 0 wi th grave accent

Resgrved

:) I

Decimal

rJ-Bi t

Code

0cta I code

Cha racter

Rema rks

; t.--' Capital 0 with acute accent

323

' : " l,.'.

+._*#i-4

32\
-

j25

rt-)

Capital O with c i rcumfl ex accen

Capital 0 with tilde

:l{
n

Capital 0 with diaeresis
.nior umlaut mark

-. OE

lrjCapital 0E I igature

':6

' ''iCapital 0 with slash

326

iil.r.j Xi::ii':;:';;:

l':: i! 3 ii":::"

215*:t r -:'i,i i. ;'31,2327

216 .. ' ., : ., i , r..::.-330

-,1 ei:.I!'lli;;!
217

. i;.,: ,;

U with grave accent

332

Capital U with acute accent

333

Capital U with circumflex accen
U with diaeresis
' Capital
umlaut mark

3 3l{
-l .

:.,c"Pital

i:+-,i

Capital Y with diaeresis
or urnlaut mark

221
.inj,5,5 .?: :i

: i"335

<*.))2t_:. i

'''t.' 336

Rese rved

: .,1, 'n'l37

German small sharp s

:,.-."-i

'223

1i: i,

Dec i mi

22\

--.

--€-:-j

Rema rks

0cta I Code

Code

-.. ..- **-.*

i:l]
3q0

225

341

226

'-3\2

:,.,rt"II
-.

a with graver+ccent

Small a with acuta,accent
r! r
Small a with circumflex accent

1.1'i56ll a with tilde:i-

227

: -.

22q

' :.'.34\

229

3\5

230

3l{6

o3€

,':i*lI

23i

3\7

..q

.-Small c with cedilla"

232

350

Small e with grave accent

233

351

,:lmall e with acute'iE""na

23lc

i52

235

j53

236

354

?37

355

238

355

Small i with circumflex accent

239

357

Small i with diaeresis

2\0

360

241

361

Small n with tilde

2\2

362

Snra I

2\3

16,.3

Small o with acute accent

2\\

36\

Small o with circumflex accent

245

365

Small o with tilde

2\6

j66

2\7

367

Small oe ligature

2\q

370

Small o with slash

"343

l'lsrall a with diaefesis or
i tS
- -umlaut mark
_-rSr"ll a with ring q,^
ae dipthons..-

I e wi th ci rcumf.lex acceni

,: ft"l
Small e with diaeresls
-llmlaut
r-\! or
mark

Small i with grave accent
Small i with acute accent

Reserved for future use

I o wi th grave accent

Small o with diaeresis or

uml aut mark

i- -:].

UecimaT-

8-bi t

.: 2\9

Cha racter

0ctal Code

Coda

..]?t ::

I 1? "i;:'i l

.3o:r'

Rema rks

' l !:,i':'

: ?firtrf l:'vu wi th grave accent

371

acute accent
.. icer r, 3.7\rr-1",,'.,,lli:.'f;;.'r;'j..=...,'""f*l!i-"i*'
'i'-:l '/''u\

zir,,r"r,r :eiu "'ill

252

d""

',!

37\

;'fr:; ; i' i; ;;' ;': :' il

1?,''' l,' ;:; ;

25\

.:i\{ {-::-r sfrirFri.r with ci rcumflex accent
diaeresis or
z'b:i'E

i[illi:,:n'

"
: ; ;=; : , : ;' ; ;i -

;:; ;';:l' diaeresis or
nds€i'ved for future use

376

future use

a.1 4

i: lr, :t:+5

:rl',\c

zg':.'l' - t-.
t!s:.
-.'.-:.-?i
| - -i-" '

ii'

:c 1

'r _ aa.il

: i.-:,.
.. -? i t 2:
v
-;
- a .:!
. .. r .-t
-t
L .: -, . -i,

it;!:-'

-.-,t _ .-.-,.
-'-

- u..M'-

$1-

:'j!\

*
,'..1.::.t:]r.i'':'-:j
;'-'it:\:"''e
>'
r
1

!ir';:a?;9:r:
::'C't::':

-' !:

(r:vii -: Jn9'-'9
': n i': ii'lf

*,x

i': i'"

5,' j-":.i'.sjlj:';

: '::lj:

THE DEC MULTINA TIONATJ CHARACTER SET

P'd9
a e

,--irllfl--

TOOL KIT GLOSSARY

:.-:

Appllcatlon Deve+!'pFr
A firm or lndlvidpgt. uslng the Profd,ssional Developer's Tool KiE to
develop appl lcation programs for.., P/OS. The "gDd user lnsEaIlS
li''
i:
applicatlon soft{lf?rg on P/as.
i

Appllcatlon Dlskegte Bu lld e r

Jr:

J'-

The roor K1r soi"ct{;;e component that. transforms the-J"ask lmage of €:n
applicatlon lnto .-a P/oS appllcatioh on a dlskecte:': The program runs
on the Professlonal..

AppIlcatlon Progr-aIL i
A computer program.qhat, meets some speclflc user n"!!!
f,or examplel
to cont.rol an inventory or to monitor a manufacturing process. The

term "applicatlon programrr is often shortened to "appllcation." A
Professional ovdner can buy a variety of applications.
Some cLasses of applicatlons have generlc names in the computer
industry.
For example, an editor is an apolication thac creates and
eoiEs Eext.

PRO/BAS IC-PLUS -2

A programmlng language useo to develop appllcation softl,jare for

It is provlcjed with the Professional Developer's Tool Kit.

P/0S.

CharacEer

A member of a set of elements used to organize, control, or represent
t,ext. Characters used 1n computers are graphic cnaract,ers and control
cnaracters. The Professlonal terminal uses tne DEC tlultlnationai
cooecj character set having an 8-bit code representation. Thls

cnaracter set includes:

Control characters produclng a function that initlates,
mociifies, or stops the recordinq, processingr transmission,
or interpretation of ciata.
Graphic characters, whlch do not lnclude cont,roL charact.ers,
having a vlsual representation normally nanCwrrt,tn, prlnged,
or displayecj.
End User

for example,
An ultimate user of a Professlonal
self-employed, 'rranagers, technlclans, and clerks.
PRO/FMS- 11 (Forms l.lanagement System)
PRo/Ft'{S-11 creates f orms f or displays

for lnteractlve

those wno are

data

eathering