Digital PDFs

AA-BT74B-TH

November 1985

246 pages

Original

7.5MB

Document:	Tool Kit Reference Manual
Order Number:	AA-BT74B-TH
Revision:	0
Pages:	246
Original Filename:	http://bitsavers.org/pdf/dec/pdp11/pro3xx/POS/AA-BT74B-TH_POS_Tool_Kit_3.0_Reference_Manual_198511.pdf

OCR Text

Tool Kit
Reference Manual
Order No. AA-BT74B-TH

November 1985

This manual provides reference information for some of
the components of the Tool Kit.

REQUIRED SOFTWARE:

Host Tool Kit V3.0
or PRO/Tool Kit V3.0

OPERATING SYSTEM:

P/OS V3.0

DIGITAL EQUIPMENT CORPORATION
Maynard. Massachusetts 01754-2571

First Printing, April 1984
Updated, July 1985
Revised, November 1985

The information in this document is subject to change without
notice and should not be construed as a commitment by Digital
Equipment Corporation. Digital Equipment Corporation assumes no
responsibility for any errors that may appear in this document.
The software described in this document is furnished under a
license and may only be used or copied in accordance with the
terms of such license.
No responsibility is assumed
software on equipment that
affiliated companies.

for the use or reliability of
is not supplied by DIGITAL or its

The specifications and drawings,
herein,
are the property of
Digital Equipment Corporation and shall not be reproduced or
copied or used in whole or in part as the basis for the
manufacture or sale of items without written permission.
Copyright © 1985 by Digital Equipment Corporation
All Rights Reserved
The following are trademarks of Digital Equipment Corporation:
CTI BUS
DEC
DECmate
DECsystem-10
DECSYSTEM-20
DECUS
DECwriter
DIBOL

mnmnamaTM

MASS BUS
PDP
P/OS
PRO/BASIC
PRO/Communications
Professional
PRO/FMS
PRO/RMS
PROSE
PROSE PLUS

Rainbow
RSTS
RSX
Tool Kit
UNIBUS
VAX
VMS
VT
Work Processor

CONTENTS
PREFACE

CHAPTER 1
1.1
1.2
1. 2 .1
1. 2. 2
1. 2. 3
1. 2. 4
1. 2. 5
1. 2. 6

CHAPTER 2

. .

. ix

USING ADS
THE ADS DIALOGUE
. . . .
Step 1: Choose Target System .
Step 2: Choose Installation Command File .
Step 3: Ready Target Diskette . . . .
Step 4: Copy Installation Command File to
First Diskette . . . . . . . . . . . .
Step 5: Copy Files to Target Diskette
Step 6: Label Completed Diskette . . .

1-1
1-2
1-2.
1-3
1-3

APPLICATION DISKETTE BUILDER (ADB)

1-4
1-4
1-4

COMMUNICATIONS SERVICES

2.1

OVERVIEW OF COMMUNICATIONS SERVICES
Status Returns
Line Descriptor Block
2 .1. 2
Autodial Modem Support
2 .1. 3
2.2
BASE SYSTEM SERVICES . .
2.2.1
Base System Start-Up . . . . .
. . .
2.2.2
Base System Routines .
. .
2.2.2.1
Attach Line (CCATT and CCATA)
. .
2.2.2.2
Detach Line (CCDET)
Set Line Characteristics (CCSMC) . . . .
2.2.2.3
2.2.2.4
Get Line Characteristics (CCGMC) . . . .
2.2.2.5
Get/Put Line Configuration Record
( CCLCRG and CCLCRP)
. . . . .
. . .
Set Translate Table (CCMTT)
......
2.2.2.6
2.2.2.7
Di a 1 ca 11 ( cc DI AL ) . . .
.
2.2.2.8
Answer Call (CCANS)
..
2.2.2.9
Originate Call (CCORG) .
. ..
Hang Up a Call (CCHNG) .
. . . .
2.2.2.10
2.2.2.11
Transmit Data (CCTXD) . . . . . . . . .
2.2.2.12
Receive Data (CCRXD) . .
. .....
2.2.2.13
Flush Input Buffer (CCFLSH)
......
Generate Break (CCBRK) .
. . . .
2.2.2.14
Kill Transfer (CCKILL) . . . . . . . . .
2.2.2.15
2.3
PRO/COMMUNICATIONS SERVICES . . . . . . . .
PRO/Communications Start-Up
2.3.1
PRO/Communications Utilities .
. ..
2.3.2
2.3.2.1
Spawn Communications Utility (CCSPWN)
.
2. 3. 3
Phone Book Services . . . . .
. . .
2.3.3.1
Get Phone Book Record (CPHREC) . . . . .
2.3.3.2
Select Phone Book Entry (CPHSEL) . . . .
2 .1.1

iii

2-2
2-2
2-4
2-8
2-9
2-9
2-10
2-10
2-11
2-11
2-12

2 -13
2-14
2 -1 5
2-18
2-19
2-21
2-21
2-22
2-23
2-24
2-25
2-25
2-26
2-26
2-27
2-28
2-28
2-29

File Transfer Services . . . . . . . . . .
File Transfer Initiation Protocol
.
Attaching the File Transfer Subsystem .
Releasing the File Transfer Subsystem .
Synchronous and Asynchronous Operations
File Transfer Synchronization
Set Up File Transfer Options (FTOPTG and
FTOPTP)
................
Attach File Transfer Subsystem (FTATT) .
2.3.4.7
File Transfer Operation Request (FTOPRN)
2.3.4.8
2.3.4.9
Notify On Incoming File (FTNTFY) . . . .
Synchronize with File Transfer (FTSYNC)
2.3.4.10
2.3.4.11
Unpack File Transfer Message Area
(FTUNPK)..............
Detach File Transfer (FTDET} . . . . . .
2.3.4.12
Start File Transfer Server (FTSERV)
2.3.4.13
Enable/Disable File Listening (FTLISN) .
2.3.4.14
TELEPHONE MANAGEMENT SYSTEM (TMS) SERVICES .
2.4
TMS Start-Up . . . . . . . . . . . . . . .
2.4.1
2.4.2
TMS Routines
. . . . . . . . . . .
.
Change Mode (CCMODE) . . . . . . . . . .
2.4.2.1
Auxiliary Keyboard Enable/Disable
2.4.2.2
( CCAUXK ) . . . . . . . . . . . . .
Prepare to Go Voice (CCPTGV) . . . . . .
2.4.2.3
Set DTMF Escape Sequence (CCDTMF)
.
2.4.2.4

2.3.4
2.3.4.1
2.3.4.2
2.3.4.3
2.3.4.4
2.3.4.5
2.3.4.6

CHAPTER 3
3.1
CHAPTER 4
4.1
4;2
4.3
CHAPTER 5
5.1
5.2
5.2.1
5.2.2
5.2.3
5.3
5.3.1
5.3.2
5.3.3
5.3.4

2-30
2-31
2-31
2-32
2-32
2-32
2-33
2-35
2-36
2-38
2-40
2-41
2-42
2-43
2-44
2-45
2-45
2-45
2-45
2 - 46
2-47
2-48

FAST INSTALL

INSTALLING DECNET OBJECTS FOR TESTING

3-3

FILE CONTROL SERVICES (FCS)

SUPPORT BY HIGH-LEVEL LANGUAGES
USING FCS RESIDENT LIBRARY
USING FCS IN-TASK VERSION . . .

. .

4-1
4-2
4-2

FRAME DEVELOPMENT TOOL (FDT)

FDT OVERVIEW
INVOKING FDT .
Invoking FDT on VAX/VMS
. . . . . .
Invoking FDT on RSX-11M/M-PLUS (DCL)
Invoking FDT in PRO/Tool Kit . . . . . . .
FILE COMMANDS
ADD
CONVERT
DELETE .
EXIT . .
iv

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

5.3.5
5.3.6
5.3.7
5.3.8
5.3.9
5.3.10
5.3.11
5.3.12
5.3.13
5.4
5.4.1
5.4.2
5. 4. 3

5.4.4
5. 4. 5

5.4.6
5. 4. 7
5.5
5.6
5.6.1
5.6.2
5.6.3
5.7
5.7.1
5.7.2
5.7.3
5.8
5.8.1
5.8.2
5.9
5.9.1
5.9.2
5.10
5.11
CHAPTER 6

. . . .

. .
.
.
.
.
.
. .
. .
. .
. .
.
. . .
.
.
.
.
. .
.
. .
.
. .
. .
.
. .
.

5-6
5-6
5-7
5-7
5-7
5-8
5-8
5-8
5-9
5-10
5-10
5-11
5-11
5-12
5-12
5-12
5-13
5-13
5-18
5-18
5-20
5-21
5-23
5-23
5-24
5-25
5-26
5-26
5-27
5-28
5-28
5-28
5-29
5-29

INSTALLATION COMMAND LANGUAGE

6.1
6 .1.1
6 .1. 2

6.2
6.3
6.4
6.5
6.6
6.7
6.8
6.9
6.10

FILE
HELP
LIST .
MODIFY . .
NAME .
QUIT .
REPORT . .
SAVE . . .
WINDOW .
FRAME COMMANDS .
ACTION . .
DISPLAY
EXIT . .
HELP . . .
PROFILE
QUIT .
SAVE .
PROFILE, DISPLAY, AND ACTION FORMS .
CREATING A SINGLE-CHOICE MENU
The Profile Form . .
The Display Form . .
The Action Form
CREATING A HELP MENU .
The Profile Form
The Display Form . .
The Action Form
CREATING A HELP TEXT FRAME . . . . .
The Profile Form . . . . .
The Display Form . . . . .
CREATING A MESSAGE TEXT FRAME
The Profile Form . . . . .
The Display Form
RESOLVING ERRORS .
SAMPLE TERMINAL SESSION

INSTALLATION COMMAND FILE FORMAT
6-2
Using .INB and .INS Files
6-3
Using /USER, /NETWORK, and /CLUSTER in Your
. I NB Fi 1 e . . . . . .
. . . . . . . . 6-3
INSTALLATION FILE ERRORS
6-7
ASSIGN HELP . . . . . .
6-8
ASSIGN LOGICAL
. . . . 6-9
ASSIGN MENU
. . 6-10
ASSIGN MESSAGE (.INB FILE ONLY)
. 6-11
COMMENT
. . 6-12
EXECUTE
. . . . 6-12
FILE . . .
. 6-19
INSTALL
. . 6-21
v

6.11
6.12
6.13
6.14
6.15
CHAPTER 7
7.1
7.2
7.3
CHAPTER 8
8.1
8.2
8.3
8.4
8.5
8.6
8.7
8.8
8.9
8.10
8.11
8.12
8.13
8.14
8.15
8.16
8.17
8.18
8.19
8.20
8.21
8.22
CHAPTER 9
9.1
9.2
9.3
9.4

MOUNT
. . . .
NAME . .
. . . .
RUN . . . . .
. . . .
IMPROVING APPLICATION PERFORMANCE . . .
REQUIRED COMMANDS FOR APPLICATIONS .

. 6-23
. . 6-24
. . 6- 25
. . 6-26
. 6-26

MACR0-11 ASSEMBLER (PMA)

INVOKING PMA ON THE PRO/TOOL KIT .
INVOKING PMA ON RSX-11M/M-PLUS
INVOKING PMA ON VAX/VMS
. . . .

7-1
7-1
7-2

POSRES USER INTERFACE LIBRARY ROUTINES

NOTES ON USING POSRES ROUTINES . .
DMENU - DISPLAY DYNAMIC MENU
DPACK - PACK DYNAMIC SINGLE CHOICE MENU
FATLER - FATAL ERROR
. . . .
GETKEY - GET KEYSTROKE
. . . . . .
HCLOSE - CLOSE HELP FILE
.
HELP - DISPLAY HELP FRAME . . . . . . . . .
HFILE - OPEN HELP FILE
..........
HFRAME - SPECIFY HELP FRAME
.
MCLOSE - CLOSE MENU FILE
. . . .
.
MENU - DISPLAY SINGLE-CHOICE MENU
.
MFILE - OPEN MENU FILE
. . . . . . . .
MFRAME - READ MENU FRAME
. . . .
.
MMENU - DISPLAY MULTIPLE-CHOICE MENU
.
MPACK - PACK MULTIPLE-CHOICE MENU . . . . .
MSGBRD - SEND MESSAGE TO A MESSAGE/STATUS
DISPLAY
.
MUNPK - UNPACK MENU BUFFER
. . .
NEWFIL - NEW FILE
OLDFIL - OLD FILENAME
.
PRSCSI - PARSE STRING
. . . . .
RDMSG - READ MESSAGE
. • • .
. . . . .
WTRES - WAIT FOR RESUME KEY

8-1
8-3
8-5
8-8
8-9
8-10
8-11
8-12
8-14
8-15
8-16
8-18
8-20
8-21
8-23
8-25
8-26
8-28
8-30
8- 32
8- 3 3
8- 3 5

CALLABLE PRINT SERVICES

CPRNT . . . . . . . . . . . . . . . .
CPRNV3 .
. . . . . . . . . . . . .
COMPATIBILITY BETWEEN CPRNT AND CPRNV3 .
EXAMPLE

9-1
9-4
9-8
9-8

CHAPTER 10

PROSE TEXT EDITOR

CHAPTER 11

PRO/SORT

11.1
USING PRO/SORT . . . . • . . . . .
11. 2
VALID RMS RECORD FORMATS . . . . .
11. 3
PRO/SORT COMMANDS AND COMMAND FILE
11. 4
COLLATE . . . . . . . . . . . . .
11. 4 .1
COLLATE Compared to SORT ALTSEQ
11. 5
DEFAULT . . . . . . . • . .
11. 6
FIELD
11.6.1
Pseudo-Fields RRN and RFA
.
11. 7
FORCE . . . . . . . . .
.
11.7.1
FORCE Compared to SORT F .
11. 8
INCLUDE . . . . . . . . .
INCLUDE Compared to SORT 0 and I
11.8.1
INPUT AND OUTPUT
11. 9
11.10
PROCESS
11.11
SORT
11.11.1
SORT Compared to SORT N and 0
11.12
WRITE . . . . . .
.
11.12.1
WRITE Compared to SORT D .
PRO/SORT ERROR CODES . .
11.13
11.14
PRO/SORT EXAMPLE . . . .
APPENDIX A
A.1

A.2

APPENDIX B
B.1
B.2

. . .
. . .
. .
. . .
. . .

. . 11-1
. 11-2
. 11-3
11-4
. 11-5
. 11-5
. 11-7
11-9
. 11-10
. 11-10
11-11
11-12
11-13
11-13
. 11-13
11-14
11-15
. 11-15
11-15
11-18

APPLICATION DISKETTE BUILDER ERROR MESSAGES

ADB NORMAL ERRORS . . .
ADB SERIOUS ERRORS .

A-2
A-7

FDT ERROR MESSAGES

B-2
B-9

USER ERRORS
INTERNAL ERRORS

APPENDIX C

POSRES STATUS BLOCK CODES

APPENDIX D

FUNCTION KEY NAMES AND CODES

APPENDIX E

P/OS ERROR CODES

E.1
E.2

•
.

APPLICATION CANNOT BE STARTED
SYSTEM ABORTED TASK

vii

E-1

E-3

INDEX
FIGURES
5-1
5-2
5-3
5-4
5-5
5-6
5-7
5-8
5-9
5-10
5-11
6-1
9-1
11-1
11-2
11-3
11-4
11-5

Forms for a Single-Choice Menu
FDT Screen Editor Keypad
Profile Form for Single-Choice Menu
Display Form for Single-Choice Menu
Action Form for Single-Choice Menu .
Profile Form for Help Menu .
Display Form for Help Menu
.....
Action Form for Help Menu . . . . . . . .
Profile Form for Help Text Frame . . . . .
Display Form for Help Text Frame
Profile F~rm for Message Frame . . .
Installation Command File Format .
Sample Call to CPRNV3
. . . .
Mapping of Bytes to Fields in Input Data
Stream . . . . . . . . . . . . . . . . . .
Sample PRO/SORT Command File . . . . . . .
Sample Input File INPUT.DAT . . . . . . .
Sample Indirect Command File FIELDS.CMD
Resulting Output File OUTPUT.DAT . . . . .

.
.
.
.
.
.
.
.
.
.
.

5-15
5-16
5-18
5-20
5-21
5-23
5-24
5-25
5-26
5-27
5-28
6-2
9-9

. 11-8
11-18
11-19
11-19
11-21

TABLES
1-1
2-1
2-2
2-3
3-1
6-1
6-2
6-3
9-1
9-2
9-3
10-1
11-1
11-2
C-1
C-2
D-1
E-1
E-2

Application File Locations for ADB . .
1-2
Communications Status Return Codes . .
2-3
Characteristic Positions in the LOB
. . . .
2-5
Transmit/Receive Rate Values for LOB .
2-6
Application File Locations for Fast Install
3-2
Summary of /USER, /NETWORK, and /CLUSTER
Qualifiers . . . . . . . . . . .
. . . .
6-6
EXECUTE Qualifiers and Phases of
Installation/Removal . . . . . . .
. 6-17
Required Commands
. . . .
. 6-27
CPRNT Condition Codes
. . . .
9-2
CPRNT Error Codes
. . . .
9-3
Status Returns for CPRNV3
. . . .
9-6
Callable Editor - Status Return Codes
. 10-3
Number of PRO/SORT Commands per Command File 11-3
PRO/SORT Error Codes . . . .
. . . .
11-16
POSRES Status Values . . . .
. . . . C-1
Menu Service Routine Errors
C-4
Function Key Names and Codes. .
. . . . . D-1
Elements of the Status Array .
. . . .
E-1
Elements of Status Array . . .
. . . . .
E-3

viii

PREFACE

Manual Objectives
After reading this manual, you will
important tools contained in the Tool
described in this manual have their
other manuals; this manual supplements

be able to use several
Kit. Note that some tools
primary documentation in
the primary material.

Intended Audience
This document is intended for programmers familiar with the
Kit development cycle and at least one Tool Kit language.
the Tool Kit User's Guide before using this manual.

Tool
Read

Structure of This Document
This manual describes 11 tools, one per chapter:
•

Chapter 1:

Application Diskette Builder (ADB)

•

Chapter 2:

Communications Services

•

Chapter 3:

Fast Install

•

Chapter 4:

File Control Services (FCS)

•

Chapter 5:

Frame Development Tool (FDT)

•

Chapter 6:

Installation Command Language

•

Chapter 7:

MACR0-11 Assembler (PMA)

•

Chapter 8:

POSRES User Interface Library Routines

•

Chapter 9:

Print Services

Chapter 10:

PROSE Text Editor

•

Chapter 11:

PRO/SORT

Appendices A and 9 are devoted to error messages returned by ADB
and FDT. Appendices C and D provide tabular information related
to POSRES user interface programming. Appendix E describes P/OS
error codes.
ix

Preface
Associated Documents

Throughout this manual, we refer to related documentation within
the Tool Kit document set.
For abstracts of other Tool Kit
documents, see the Tool Kit User's Guide.
Conventions Used in This Document
Convention

Meaning

BOLD UPPERCASE

Bold uppercase letters indicate elements
that you must use exactly as shown.

UPPERCASE LETTERS

Uppercase letters indicate elements that you
can omit or use exactly as shown.

bold lowercase

Bold lowercase letters
that you must replace
description in the text.

lowercase letters

Lowercase letters indicate elements that you
can
omit
or replace according to the
description in the text.

indicate elements
according to the

Shaded
areas
containing
bold
letters
indicate a list of elements from which you
must select one.
Shaded areas containing non-bold letters
indicate a list of elements from which you
can optionally select one.
element, ..•

A comma followed by a horizontal ellipsis
indicates that you can repeat the preceding
element one or more times, separating the
elements with commas.
A vertical ellipsis in a figure or example
means that part has been omitted for
brevity.

red letters

Red letters
computer.

indicate

your

input

the

CHAPTER 1
APPLICATION DISKETTE BUILDER (ADB)

The Application Diskette Builder (ADB) creates a master copy of
an application diskette that can be reproduced for distribution.
ADB is distributed with the Host Tool Kit and the PRO/Tool Kit on
the Application Diskette Builder diskette.
ADB uses the information in your installation command file to
copy your application from the hard disk to one or more
diskettes, from which it can be installed on other systems.
An application can span several diskettes.
Multiple applications
can be copied to a single diskette if space allows.

1.1

USING ADB

To prepare a master distribution diskette for
follow these steps:

your

application,

If you have not already installed ADB on your Professional,
do so now.
Insert the ADB diskette and install it as you
would any application.

Copy your application files to the appropriate device and
directory as shown in Table 1-1. The table shows how to use
the qualifiers you have specified on FILE commands in your
installation file to determine the destination of your files.

Select ADB from the menu on which it was installed.
The ADB
dialogue is described in Section 1.2. During the dialogue,
you can press MAIN SCREEN to return to the Main Menu.

1-1

USING ADB
Table 1-1:

Application File Locations for ADB

FILE Command

Copy File From

FILE fname.ext
or
FILE fname.ext/USER

SYOOO:[applicdir]
where applicdir is the name of
the directory containing the
installation command file.

FILE [dir]fname.ext
or
FILE [dir]fname.ext/USER

SYOOO:[dir]
where dir is the name of the
directory that you specified in
the FILE command in your
installation command file.

FILE fname.ext/NETWORK

SYOOO:[applicdir]
where applicdir is the name of
the directory containing the
installation command file.

FILE [dir]fname.ext/CLUSTER

LBOOO:[dir]
where dir is the name of the
directory that you specified in
the FILE command in your
installation command file.

FILE fname.ext/CLUSTER

SYOOO:[applicdir]
where applicdir is the name of
the directory containing the
installation command file.

1.2

THE ADB DIALOGUE

ADB first displays an introductory frame.
dialogue.

1.2.1

Step 1:

Press DO to begin

the

Choose Target System

ADB displays the menu for choosing the target system for your
application.
Choose the appropriate target system for your
appli ca ti on.

1-2

THE ADB DIALOGUE
1.2.2

Step 2:

Choose Installation Command File

ADB displays a list of installation files contained in your
current directory.
If the desired installation command file is
not on this list, press the ADDTNL OPTIONS key to:
•

Select a file from a different directory

•

Select a file from a different volume and directory

•

View the next group of files

•

Specify the file with an extended filename

If ADB does not find an installation command file in the
directory, it displays the Additional Options menu.

current

When you have selected a file, ADB checks it for errors. If ADB
detects an error, refer to Appendix A, correct the problem, and
try again.

1.2.3

Step 3:

Ready Target Diskette

If ADB finds no errors, it displays the Diskette Drive
and Initialization Menu.
•

Selection

If the diskette contains information that must be preserved,
select one of the options that indicates copying will take
place
without
initializing
the
diskette.
Existing
information will be saved.
NOTE

If the installation command file contains a
MOUNT line for this diskette, ADB will expect
the diskette to have the same volume name as
that specified in the MOUNT line.
•

If you do not want to preserve any existing information on
the target diskette, select an option that will initialize
the diskette. When ADB prompts for the volume name, enter
the desired volume name. ADB will check the volume for bad
blocks.

1-3

THE ADB DIALOGUE
NOTE

If your installation command file references
this diskette in a MOUNT line, you will not
be prompted for a volume name.

1.2.4

Step 4:

Copy Installation Command File to First Diskette

ADB displays a form asking you for the name of the application
directory to be created on the application diskette. If an
installation command file contains errors, ADB will not copy the
file and will display an error message. Check the format of the
installation command file, correct the file, and start again.

1.2.5

Step 5:

Copy Files to Target Diskette

The ADB now copies the files listed in the FILE lines of the
installation command file to the target diskette.
If ADB
encounters a MOUNT line, it prompts you to insert a new diskette
and repeats the diskette initialization process.
ADB then
resumes copying files with the next FILE line and continues until
all MOUNT and FILE lines have been processed.
ADB searches for the files to copy in the locations shown in
Table 1-1.
If ADB cannot find a file, is displays a Directory
Selection Menu. Specify the directory that contains the file.
ADB displays a confirmation message when all files are copied.

1.2.6

Step 6:

Label Completed Diskette

You should label your application diskettes with:
•

The application's name

•

The volume name, which must match the name
corresponding MOUNT line, if there is one.

•

The number of diskettes on which the application resides

1-4

provided

the

THE ADB DIALOGUE

•

Minimum hardware configuration required

•

Media space required

If your application spans more than one diskette, you should also
indicate which is the first diskette; that is, indicate which
diskette contains the installation command file.

1-5

CHAPTER 2
COMMUNICATIONS SERVICES

Communications Services allow you to perform communications
operations on the Professional.
Your application program can
access the services either by calling communications routines, or
by spawning tasks that execute communications utility programs.
For example, your program can call a routine named CCATT to
attach a phone line, or it can spawn a task that executes a
terminal emulation utility.
The communications services fall into the following categories:
1.

Base System Services, which DIGITAL provides with the P/OS
operating system.
These services include an asynchronous
driver (XKDRV) for the Communication Port as well as a
communications service library (COMLIB).

PRO/Communications Services, which DIGITAL supplies as an
optional
application,
providing
features beyond those
supplied with the base system.
These services include
utility programs (such as a terminal emulator), as well as
additional communications routines.

Telephone Management System

(TMS) Services, which DIGITAL
supplies as an optional application.
The TMS services
consist of a set of routines that allow your application to
control the TMS hardware. Note that this hardware must be
installed on the Professional in order to call the TMS
routines.

The next section presents general information common to all the
communications services.
Succeeding sections describe each of
the services.

2-1

OVERVIEW OF COMMUNICATIONS SERVICES

2.1

OVERVIEW OF COMMUNICATIONS SERVICES

Before executing any communications service that performs I/O,
you must assign a logical unit number (LUN) to the required
communication line(s). The device names for the communication
lines are:

Device Name

Represents

XKO:
XT1:
XT2:
XT3:

Communication Port
TMS Line 1
TMS Line 2
TMS Voic~ Unit

You can assign a LUN to a communication line either as a static
assignment at task build time, or by using the ALUN$ system
directive (described in the P/OS System Reference Manual).
The
system automatically incorporates the communications impure data
area in the root of any task linking to the COMLIB cluster
library.
If you want to service unsolicited events on the communication
line, you can call the CCATA routine to attach the line.
You are
notified of all unsolicited events via the user asynchronous
system trap (AST) routine declared in the call.
You can perform either synchronous or asynchronous I/O to the
communication line driver.
The event flag number (EFN)--a
parameter on your call line--indicates the type of I/O performed.
For
asynchronous I/O,
the system sets the event flag on
completion of the I/O transfer.
Parameters in calls to the communications routines are all
one-word
integers, unless the description of a particular
parameter specifies otherwise.
For details on a
routine's
parameters,
refer to the routine's description later in this
chapter.
For a description of the calling conventions
routines, refer to the Tool Kit User's Guide.

2.1.1

for

all

the

Status Returns

All communications routines check for proper I/O termination,
returning a two-word status value in the first parameter in the
call line.

2-2

OVERVIEW OF COMMUNICATIONS SERVICES
The first word of the status value contains a code indicating
whether or not the I/O termination was successful. The second
status word contains a code indicating the specific error, if an
error occurred.
The routine obtains this code from the first
word of the I/O status block (IOSB). You can check the first
byte of this word to determine the specific error.
For routines that accept calls issuing an asynchronous QIO, your
application must specify an additional two-word area for the
IOSB. If you use the routine in its synchronous mode, the
routine signals its termination status as described above.
However, if you use the routine's asynchronous mode, the first
status word indicates only whether or not the routine has
successfully issued the QIO. Your program must test the IOSB to
determine if the I/0 terminated successfully after the QIO
completed. For some routines, the system signals QIO completion
by setting an event flag that you specify in the call line.
COMLIB defines all returned status codes as global symbolic
constants. For those languages that allow you to define external
constants, the Professional Application Builder (PAB) resolves
the values at build time.
Each status return has a symbolic name, called the return code.
Table 2-1 shows the return codes and their values. Success
returns are positive values; error returns are negative values.
For the possible return codes for a particular routine, see
routine's description later in this chapter.
Table 2-1:

Communications Status Return Codes

Return
Code

Value

cs.sue

Successful reply

CS.NTB

Successful, no translate table
(CCLCRG, CCLCRP routines only)

CS.FUN

Successful, function key exit
Second word contains key value

CE.UNO

-1

Unsupported message option

CE.MFE

-2

Message format error

Meaning

2-3

that

OVERVIEW OF COMMUNICATIONS SERVICES
Return
Code

Value

CE.REJ

-3

Invalid message option
Second word contains:
1 - Operation disallowed
2
User requested abort
3
File exceeds maximum
4
Invalid action code
5 - File transfer Subsystem busy
6 - Bad parameter
7 - No operation currently active
8. - Invalid password
9. - Server already active
64. - File Transfer Subsystem unattached

CE.MSC

-4

Message type not synchronized

CE.DOC

-5

Data link error

CE. IEA

-6

Internal error abort

CE.RMS

-7

PRO/RMS error
Second word contains the PRO/RMS error code

CE.LIB

-9.

Library mismatch error

CE.STU

-11.

File transfer startup in progress

CE.PRM

-16.

External parameter error

CE.DIR

-17.

RSX Directive error
Second word contains the DSW

CE. IER

-18.

I/O termination error

CE.NNF

-19.

Name not found in Phone Book

CE.CTB

-20.

Phone Book is empty

2.1.2

Line Descriptor Block

C2.DIS
C2.UAB
C2.FTB
C2. IAC
C2.BSY
C2.BPL
C2. IDL
C2.IPW
C2.SAA
C2.NAE

Meaning

The line descriptor block (LOB) stores line characteristics,
which describe how voice or data travels over your communication
line. You need this information to set up the line, either for a
voice or data connection. You can transmit via the Communication
Port or Telephone Management System (TMS) telephone lines.
2-4

OVERVIEW OF COMMUNICATIONS SERVICES
(We describe TMS later in this chapter.)
Each line characteristic consists of one byte, stored in the LOB
in a position-dependent manner. That is, each value's position
in the LOB indicates what characteristic it represents.
Table
2-2 shows the characteristic positions in the LDB.

Table 2-2:

Characteristic Positions in the LOB

Byte

Description

Transmit Rate (Bits per sec)
For allowed values, see Table 2-3

Receiver Rate (Bits per sec)
For allowed values, see Table 2-3

Number of Data Bits
8, 7, 6, or 5

Number of Stop Bits
1 or 2

Parity Checking and Generation
1
0

Enable
Disable

Odd or Even parity
1
0

Even
Odd

XON/XOFF Recognition
1
0

Enable
Disable

Pass 8-bit characters
1
0

Enable
Disable (pass 7-bit characters)

Auto answer ring count
0-9 decimal

(zero means don't answer)

Modem Type
-1

No modem, hardwired line

us FSK, 0-300 baud Bell 103 (TMS)
us DPSK, 1200 baud Bell 212 (TMS)

(decimal) Mini-Exchange

2-5

OVERVIEW OF COMMUNICATIONS SERVICES
Byte

Description

Dial Mode

0
1

2
3

Dial pulse, 10 pulses/second
DTMF
Dial pulse, 20 pulses/second
Off-hook service (external fixed number)

Data Mode
0 Voice telephone
1
2

Serial data
Encoded voice
DTMF data

DTMF Tone Time (10 ms multiples)

1 or 255
13

DTMF Interdigit Time (10 ms multiples)

1 or 255
14

TMS Silence Detect Timeout

1
0
15

Enable
Disable

Reserved

Table 2-3 shows the codes you can use to specify
transmit rate in bytes zero and one of the LDB.
Table 2-3:

Transmit/Receive Rate Values for LOB

Symbol

Decimal Value

Actual baud rate
(Bits per Second

S.50

S.75

S.110

110

S.134

134.5

S.150

150

2-6

receive

OVERVIEW OF COMMUNICATIONS SERVICES

Symbol

Decimal Value

Actual baud rate
(Bits per Second

S.200

200
(TMS only)

S.300

300

S.600

600

S.1200

1200

S.1800

1800

S.2000

2000

S.2400

2400

S.3600

3600

S.4800

4800

S.7200

7200

S.9600

9600

S.EXTA

External
clocking

S.19.2

19200

To change a line characteristic, first call CCGMC or CCLCRG to
get
either the current settings or the default settings,
respectively. Then modify the particular characteristic byte or
bytes and write the new set back using CCLCRP or CCSMC. Note
that CCLRP does not check for validity when you write back the
default characteristics.
In general, all the settings in the LOB must
line to which you write them.

valid

for

the

Much of the information contained in the line descriptor block is
optional and depends on the type of link that you are setting up.
For a voice link, the system uses only those fields that control
the manner in which the call is dialed.
Some data options available via TMS are unavailable on the
Communication Port, and vice versa.
When you choose such an
option, it is ignored, except where a functional incompatibility
2-7

OVERVIEW OF COMMUNICATIONS SERVICES
occurs.
For example, you can specify the 200 baud rate only for
TMS lines. Also, baud rates of 1800 and above are not supported
on the TMS unit.
Note that a particular line characteristic (a byte in the LOB)
corresponds to the second byte in the QIO functions SF.GMC and
SF.SMC.
(The communication routines that handle the
line
characteristics use these two QIO functions. See the P/OS System
Reference Manual for details.)

2.1.3 - Autodial Modem Support

The XKO: device handles any autodial modem that accepts a dial
sequence as data passed on the primary transmit lead. This type
of modem usually has both a start control sequence (indicating
that a telephone number follows) and an end sequence (indicating
the end of the telephone number). Not all modems require the end
sequence.
You can use two methods of dialing through the Communication Port
when an autodial modem is attached.
The first method is to
define the line as hardwired and transmit the dial sequence as
data to the modem.
Most autodial modems give some kind of
response indicating whether
or
not
the
connection
was
successfully established. This can be read as data received from
the modem. Note that this method will only work on XKO:
(one
side effect is that a hardwired line automatically answers any
call because the DTR signal is held high).
The second method supports XKO:, XT1:
and XT2:
lines.
A
program that uses this method need not know the specific line
type that the call is dialed on. To set up the system to support
an autodial modem on XKO: you must define a translate table as
the XKO: device.
The translate table contains three parts:
•

The first part defines a set of character translations.

•

The second part defines the start sequence for
modem.

•

The third part defines the end sequence.

the

autodial

The first part of the translate table defines a set of character
translations that can occur during the dial operation. This
allows you to substitute graphics characters
for
control
characters in the phone number. Also, it allows you to remove
2-8

OVERVIEW OF COMMUNICATIONS SERVICES
format characters from the phone
number.
characters for a phone number are as follows:

Normal

format

Additionally, the space character is a format character.
A
sample
phone number with format characters is [12]
(222)
555-4444.
You can set the translate table by calling the Base System
routine
CCMTT
(see Section 2.2.2.6) or by executing the
PRO/Communications Set-Up Utility (see Section 2.3.2).
By default (that is, if you do not override the default translate
table), the XKO:
device assumes that a DIGITAL DF03 autodial
modem is attached.
Note that any of the parts of the table can be empty.
Look in
the user handbook for the start and end sequence of the
particular autodial modem you are using. The translate table as
stored and returned by the CCLCRP and CCLCRG routines begins at
the first count-byte.

2.2

BASE SYSTEM SERVICES

The Base System Services include an asynchronous driver (XKDRV)
for the Communication Port, as well as a communication service
library (COMLIB). To perform communications operations, you can
either issue QIO requests directly to the XKDRV (see the P/OS
System Reference Manual), or call the routines in COMLIB.
If you are writing your program in a high-level language,
best to use the COMLIB routines.

The Base System Services allow you to set up and control a
telephone connection for data communication. Additionally, the
Base Services allow you to handle voice communication if you
install the optional Telephone Management System (TMS).
The following sections describe the Base System start-up and
Base System routines.

2.2.1

the

Base System Start-Up

When you power up a Professional and boot P/OS, a Base System
start-up program executes.
The program is present on all
systems. This program loads the asynchronous driver, XKDRV, and
2-9

BASE SYSTEM SERVICES
sets up the default line characteristics. It also loads the TMS
Driver, if the hardware is present, and sets the default line
characteristics of TMS lines.

2.2.2

Base System Routines

This section describes the communication
provides with the P/OS operating system.

routines

that

DIGITAL

2.2.2.1 Attach Line (CCATT and CCATA) - There are two attach
routines.
The CCATA routine attaches a line and declares an AST
routine that your application uses for unsolicited events.
The
CCATT only attaches the line.
The caller specifies the AST
routine that CCATA uses.
Format:
CCATT (status, lun)
CCATA (status, lun, ast, param)
status

A two-word status block as described in Section 2.1.1.

lun

The logical unit number for the communication line.

ast

The entry point for an unsolicited event AST.

pa ram

A number that identifies this line as the input
upon entry to an unsolicited event AST routine.

source

Status:
CS.SUS

Successful

CE.PRM

Service call parameter error

CE.DIR

RSX Directive error
Second status word contains the DSW

CE. IER

I/O Termination error
Second status word contains the IOSB first word

CE.IEA

Internal error

2-10

BASE SYSTEM SERVICES
Note:
The routines CCATT and CCATA issue asynchronous QIOs to perform
the attach, which always completes immediately. However, if
another task has attached the line prior to your request, you
receive the status return code CE.IEA, with the second status
word equal to zero. The zero indicates that the attach request
will pend until the line is free. When the line is free, the
driver updates the status parameters with the completion status
of the attach QIO (that is, the driver asynchronously writes the
IOSB to the status block).
To avoid data corruption upon completion of the attach, you might
want to use a separate status block when calling CCATT or CCATA.

2.2.2.2 Detach Line (CCDET) - This routine detaches
previously attached by the CCATT or CCATA routines.

line

Format:
CCDET (status, lun)
status

A two-word status block as described in Section 2.1.1.

lun

The logical unit number for the communication line.

Status:

cs.sue

Successful

CE.PRM

Service call parameter error

CE.DIR

RSX Directive error
Second status word contains the DSW

CE.IER

I/O Termination error
Second status word contains the IOSB first word

CE.IEA

Internal error

2.2.2.3 Set Line Characteristics (CCSMC) - This routine modifies
line characteristics to the required settings.
The routine
writes the characteristics stored in the ldb parameter (see the
call line) to the appropriate driver.

2-11

BASE SYSTEM SERVICES
Format:
CCSMC (status, lun, ldb)

status

A two-word status block as described in Section 2.1.1.

lun

The logical unit number for the communication line.

ldb

The line descriptor block containing the new
characteristics. The block size must be 16 bytes.

line

Status:

cs.sue

Successful

CE.PRM

Service call parameter error

CE.DIR

RSX Directive error
Second status word contains the DSW

CE. !ER

I/O Termination error
Second status word contains the IOSB first word

CE. !EA

Internal error

2.2.2.4 Get Line Characteristics (CCGMC) - This routine
the current line characteristics for the specified line.

returns

Format:
CCGMC (status, lun, ldb)

status

A two-word status block as described in Section 2.1.1.

lun

The logical unit number for the communication line.

ldb

A buffer into which the line characteristics may be
The buffer size must be 16
returned in ldb format.
bytes.

Status:

cs.sue

Successful

CE.PRM

Service call parameter error

CE.DIR

RSX Directive error
Second status word contains the DSW

2-12

BASE SYSTEM SERVICES
CE.IER

I/O Termination error
Second status word contains the IOSB first word

CE.IEA

Internal error

2.2.2.5 Get/Put Line Configuration Record (CCLCRG and CCLCRP) You can use these routines to retrieve and modify the line
configuration record for the specified line.
Format:
CCLCRG (status, dev, unit, ldb, ttble)
CCLCRP (status, dev, unit, ldb, ttble)

status

A two-word status block as described in Section 2.1.1.

dev

A two-byte ASCII string containing the device mnemonic.

unit

The unit number in binary format.

ldb

The line descriptor block.
bytes.

ttble

A 64-byte translate table for
converting
internal
telephone numbers to a format accepted by an autodial
modem. The table begins at the first count-byte.

The block

size

must

Status:

cs.sue

Successful

CS.NTB

Successful, no translate table defined (CCLCRG only)
or
Successful, ttble parameter not supplied
(CCLCRG and CCLCRP)

CE.PRM

Service call parameter error

CE.DIR

RSX Directive error, second status word contains DSW

CE.RMS

File I/O error
PRO/RMS-11 error code passed in second word

CE.IEA

Internal error

Notes:

These routines perform file I/O to the communications set-up data

2-13

BASE SYSTEM SERVICES
file.
(This file stores default line characteristics, translate
tables, and other information used by
the
communications
services.) In order to perform the file I/O, you must assign a
logical unit number to the set-up data file.
Insert the
following global definition command in your PAB command (.CMD)
file:
GBLDEF = CM$LUN:lun
where "lun" is the logical unit number that the system associates
with the communications set-up file.
See the section on command files in this manual for
information.
Also, see the description of GBLDEF
RSX-11M/M-PLUS and Micro/RSX Task Builder Manual.

further
in the

If you specify "ttble" without having previously defined a
translate table, CCLCRG assigns the value zero to the first three
bytes of the translate table buffer. The CS.NTB status return
indicates this condition. Note that both CCLCRG and CCLCRP also
return CS.NTB if you omit the ttble parameter.
You can set up a translate table either by calling CCLCRP or by
using
the
PRO/Communications
application
to
"Set modern
characteristics."

2.2.2.6 Set Translate Table {CCMTT) - This routine allows you to
set a translate table when you are using an autodial modern.
Format:
CCMTT (status, lun, ttble)

status

A two-word status block as described in Section 2.1.1.

lun

The logical unit number for the communication line.

ttble

A 64-byte translate table for
converting
internal
telephone numbers to a format accepted by an autodial
modern. The table begins at the first count-byte.

Status:

cs.sue

Successful

CE.PRM

Service call parameter error

CE.DIR

RSX Directive error
Second status word contains the DSW
2-14

BASE SYSTEM SERVICES
CE.IER

I/O Termination error
Second status word contains the IOSB first word

CE.IEA

Internal error

Notes:
Some autodial modems require that a delay be introduced between
sending the start sequence and presenting the telephone number.
You can introduce a one-second delay by adding an "!" to the end
of the start sequence.
An additional "!" adds an additional
one-second delay.

2.2.2.7 Dial Call (CCDIAL) - This routine dials a call in data
mode on a designated communication line. The type of call you
establish (voice or data) depends on the current data mode of the
device. Use the CCSMC routine to set the data mode.
Format:
CCDIAL (status, lun, tel, len, efn, iosb, tmo)
status

A two-word status block as described in Section 2.1.1.

lun

The logical unit number for the communication line.

tel

A string up to 32 bytes
number.

len

The length of the telephone number.

efn

An event flag the system sets
operation,
or
zero
if you
synchronously.

iosb

A two-word array used as an IOSB.

tmo

The timeout period for the dial to complete.· Specify the
value as follows:

long

representing

telephone

on completion of the
perform the operation

bits 0-7

Number of ten-second intervals, up to 255 decimal

bits 8-15

Number of one-second intervals, up to 255 decimal

The longest timeout interval is 255
(decimal)
seconds.
If the timeout value is larger than 255 seconds, the
routine uses 255 seconds.

2-15

BASE SYSTEM SERVICES
If you do not specify tmo, the driver uses 60 seconds
the timeout value.

Status:

cs.sue

Successful

CE.PRM

Service call parameter error

CE.DIR

RSX Directive error
Second status word contains the DSW

CE.IER

I/O Termination error
Second status word contains the IOSB first word

CE.IEA

Internal error

Notes:

Before issuing the dial, the Communication Port driver raises DTR
and RTS.
These may be dropped depending upon the termination
status of the dial, as described in the following paragraphs.
If you specify a zero timeout (or no timeout parameter), the
Communication Port driver waits 60 seconds to establish carrier.
If at the end of this period carrier is not raised, then DTR and
RTS are dropped.
If you specify a nonzero timeout, the request completes after the
timeout period or after a connection is established. If the
timeout period expires, then the Communication Port driver drops
DTR and RTS and the routine returns an IE.DNR error in the first
word of the I/O status block. If the modem raises carrier before
the timeout period expires, the routine returns rs.sue in the
first word of the I/O status block.
When dialing a call, the Communication Port driver automatically
deletes the format effectors.
These include left and right
parentheses, the dash, and the space character. The driver also
inserts the appropriate start and end codes for a DF03 modem,
provided that you use the default translate table.
For other
types of format effector editing, or for support of autodial
modems with different start/end codes, you must set up a new
translate table (see the description of the CCMTT routine earlier
in this chapter).
If you are dialing TMS, you can specify the following
in your telephone number.

2-16

characters

BASE SYSTEM SERVICES
An exclamation mark causes an access pause and waits for
an initial or intermediate dial tone.
This pause is
required by some telephone systems.
If TMS receives a dial tone,
it continues dialing the
remaining characters in the dial string.
After six
seconds,
if TMS has not received a dial tone,
it
continues dialing as if it had received a dial tone.
You can use this feature where a second dial tone is
needed.
For example,
to dial from within a company's
phone system that requires a "9" followed by a dial tone,
the Phone Book entry could be:
9!(222)555-4444.
!!

Two exclamation marks cause a longer access
pause
(maximum of 40 seconds) that waits for an intermediate
dial tone.
This is used when more than a few seconds of
network switching time is needed.
A comma provides a fixed, two-second delay.
The pound sign symbol is used in two cases.
First,
if
you are dialing in Touch-Tone0 mode, it transmits the "#"
signal, which may be used if your telephone recognizes it
(for
example,
as
a
terminator
at
the end of
variable-length international telephone numbers).
The pound sign can also be used where mixed-mode dialing
is necessary.
For example, if your phone service allows
only rotary dial, and you need to communicate with a
device that requires Touch-Tonea signals, the pound sign
switches from rotary dialing to Touch-Tone0 dialing;
the
pound sign itself is not sent.
For example 555-4444#
could dial in rotary, and all communication after the
pound sign would occur in Touch-Tones.

*ABCD

These additional signals are
required
by
special
communications networks and applications.
The asterisk
is available if you have Touch-Tones service.

If you are dialing the Mini-Exchange, you can specify the
following characters in your telephone number. Note that you
must have specified Mini-Exchange as your modem type in byte 9 of
the line descriptor block (see Section 2.1.2 for details).

2-17

BASE SYSTEM SERVICES
1-8

The Mini-Exchange ports are numbered
connect to a Mini-Exchange port,
instead of a phone number.

The R character specifies that a modem is attached to
port 8.
It can be followed by a telephone number that
the modem will dial. For example, R555-4444.

HR specifies that a modem operating at 1200 baud is
attached to port 8. It can be followed by a telephone
number that the modem
will
dial.
For
example,
HRSSS-4444.

LR specifies that a modem operating at 300 baud is
attached to port 8. Mini-Exchange will set the baud rate
to that of the modem. It can be followed by a telephone
that
modem
number
the
will dial.
For example,
LRSSS-4444.

1 through 8.
To
use the port number

An underscore indicates
that
the
modem
of
one
Mini-Exchange is connecting to the port of another
Mini-Exchange (the two Mini-Exchanges must be connected
by modems). For example, if 555-4444 were the number of
the other Mini-Exchange, R555-4444_6 would dial it and
connect
to its port number 6.
The port selector
following a phone number can be 1 through 7 only.
P

The P character following a port number indicates that a
DIGITAL printer is attached to the specified port. Note
that a telephone number cannot accompany the P code.

When the Professional accepts a connection through Mini-Exchange,
its baud rate is automatically set to that of the originator.

2.2.2.8 Answer Call (CCANS) - This routine answers a call on the
specified telephone line in data mode. The routine answers the
call in the current mode of the line (voice or data).
Format:
CCANS (status, lun)

status

A two-word status block as described in Section 2.1.1.

lun

The logical unit number for the communication line.

Status:

cs.sue

Successful
2-18

BASE SYSTEM SERVICES
CE.PRM

Service call parameter error

CE.DIR

RSX Directive error
Second status word contains the DSW

CE.IER

I/O Termination error
Second status word contains the IOSB first word

CE.IEA

Internal error

Notes:
If no connection occurs within 60 seconds, the routine returns an
error status.
You should call this routine in response to a
"ring indicator" unsolicited event.
In the case of a TMS line where the call has already been
established in voice mode, this routine causes the TMS software
to connect the designated modem in answer mode when a change mode
command is issued to place the line in ASYNC mode.
The
corresponding party must have placed their modem in originate
mode.
(Use the CCORG routine,
followed by a change mode to
ASYNC, to place a modem in originate mode.)
The converse of this is also true. That is, to change a
from ASYNC mode to voice mode, use the following procedure:

line

Use CCPTGV to indicate that the line
disconnected when carrier loss occurs.

not

Use CCMODE to set the desired mode, which does
effect until you issue a CCANS or CCORG call.

not

take

Use CCANS or CCORG to effect the mode change.

2.2.2.9 Originate Call (CCORG) - This routine initiates the
connection in originate mode, once the line has already been
connected. You can use the routine to determine whether or not a
connection currently exists, or to raise DTR and RTS before
making a manual connection.
Format:
CCORG (status, lun, efn, iosb, tmo)

2-19

BASE SYSTEM SERVICES
status

A two-word status block as described in Section 2.1.1.

lun

The logical unit number for the communication line.

efn

An event flag the system sets
operation,
or
zero
if you
synchronously.

iosb

A two-word array to be used as an IOSB.

tmo

The optional timeout parameter. See the description
the tmo parameter in the description of CCDIAL.

on completion of the
perform the operation

Status:

cs.sue

Successful

CE.PRM

Service call parameter error

CE.DIR

RSX Directive error
Second status word contains the DSW

CE.IER

I/O Termination error
Second status word contains the IOSB first word

CE.IEA

Internal error

Notes:

If you you do not specify a timeout parameter, the driver raises
DTR and RTS.
You can then initiate a manual connection in the
normal manner. If you have specified that the line has a modem,
DTR is not raised until you issue CCORG with no timeout
parameter. When using CCDIAL, the driver automatically raises
DTR before dialing a call.
If you specify a zero timeout parameter, the request completes
immediately.
When carrier is down, the driver drops DTR and RTS
and the routine returns an IE.DNR error in the first word of the
IOSB.
When carrier is up, the routine returns rs.sue in the
first byte of the IOSB. You can use this to determine if a
connection exists on a line.
If you specify a nonzero value in timeout, the request completes
either after the timeout period or after a connection is
established. If the timeout period expires, the driver drops DTR
and RTS and the routine returns an IE.DNR error in the first word
of the IOSB. If carrier is up (or comes up before the timeout
period expires), the routine returns rs.sue in the first word of
the IOSB.

2-20

BASE SYSTEM SERVICES

2.2.2.10 Hang Up a Call (CCHNG) - This routine
call previously established on a specified line.

disconnects

Format:
CCHNG (status, lun)
status

A two-word status block as described in Section 2.1.1.

lun

The logical unit number for the communication line.

Status:

cs.sue

Successful

CE.PRM

Service call parameter error

CE.DIR

RSX Directive error
Second status word contains the DSW

CE.IER

I/0 Termination error
Second status word contains the IOSB first word

CE.IEA

Internal error

Note:
The Communication Port driver drops DTR and RTS when
executes. The TMS driver puts the telephone line on-hook.

CCHNG

2.2.2.11 Transmit Data (CCTXD) - This routine transmits a data
buffer
to the destination system at the other end of a
communication line. The routine delivers the data to the
remote
system as a character string with no intermediate line protocol.
Format:
CCTXD (status, lun, efn, iosb, stadd, size)
status

A two-word status block as described in Section 2.1.1.

lun

The logical unit number for the communication line.

efn

An event flag the system sets
operation,
or
zero
if you
synchronously.

2-21

on completion of the
perform the operation

BASE SYSTEM SERVICES
iosb

A two-word array used for the IOSB.

stadd

A buffer that contains the data to be transferred.

size

An integer specifying
transferred.

the

amount

data

Status:

cs.sue

Successful

CE.PRM

Service call parameter error

CE.DIR

RSX Directive error
Second status word contains the DSW

CE.IER

I/0 Termination error
Second status word contains the IOSB first word

CE.IEA

Internal error

2.2.2.12 Receive Data (CCRXD) - This routine reads data from a
communication line.
You can either read all the data currently
buffered in the driver or wait a specific period of time and read
all the data accumulated up to that point. Alternatively, you
can read a fixed amount of data from the line.
Input always
terminates when your task's buffer becomes full.

If you specify XON/XOFF support, the driver transmits XOFF when
the driver's buffer becomes three-quarters full, and transmits
XON when the driver's buffer is emptied to the one-quarter point.
The driver has a limited amount buffer space.
If the driver's buffer
characters are lost.

becomes

full,

additional

Note that the amount of data received is in the
the IOSB.

second

incoming
word

Format:
CCRXD (status, lun, efn, iosb, stadd, size, tmo)

status

A two-word status block as described in Section 2.1.1.

2-22

BASE SYSTEM SERVICES
lun

The logical unit number for the communication line.

efn

An event flag the system sets
operation,
or
zero
if you
synchronously.

iosb

A two-word array for the IOSB.

stadd

A buffer into which the routine can place the data.

size

An integer specifying the input buffer size.

tmo

If you do not specify this parameter, input is not
complete until "size" characters have been written to the
buffer.

on completion of the
perform the operation

If tmo is zero, the request returns immediately after
transferring as many characters as are available up to
the input buffer size. If tmo is not equal to zero, the
request completes after the timeout period specified.
See CCDIAL for the format of tmo.
Status:

cs.sue

Successful

CE.PRM

Service call parameter error

CE.DIR

RSX Directive error
Second status word contains the DSW

CE.IER

I/O Termination error
Second status word contains the IOSB first word

CE.IEA

Internal error

Note:
If you are using a TMS line in DTMF mode, the Touch-Tonee keys
are presented as data characters.
(See the TMS Programmer's
Manual.) Further, in CODEC mode the use of the Touch-Tones keys
is signalled by an AST (if the line is attached for ASTs).

2.2.2.13 Flush Input Buffer (CCFLSH) - This routine flushes
input buffer for the specified communication line.

2-23

the

BASE SYSTEM SERVICES
Format:
CCFLSH (status, lun)

status

A two-word status block as described in Section 2.1.1.

lun

The logical unit number for the communication line.

Status:

cs.sue

Successful

CE.PRM

Service call parameter error

CE.DIR

RSX Directive error
Second status word contains the DSW

CE. IER

I/O Termination error
Second status word contains the IOSB first word

CE. IEA

Internal error

2.2.2.14

Generate Break (CCBRK) - This routine generates a break

or a long space on the line.
Format:
CCBRK (status, lun, brk)

status

A two-word status block as described in Section 2.1.1.

lun

The logical unit number for the communication line.

brk

Specify 0 to send a break.
space.

Specify

Status:

cs.sue

Successful

CE.PRM

Service call parameter error

CE.DIR

RSX Directive error
Second status word contains the DSW

CE. IER

I/O Termination error

2-24

send

long

BASE SYSTEM SERVICES
Second status word contains the IOSB first word
CE. !EA

Internal error

2.2.2.15 Kill Transfer (CCKILL) - This
routine
kills
any
outstanding transfers. You can use it only with asynchronous I/O
transfers. The outstanding transfer terminates in the normal
manner
(the system sets the event flag you specified at
initiation).
Format:
CCKILL (status, lun)

status

A two-word status block as described in Section 2.1.1.

lun

The logical unit number for the communication line.

Status:

cs.sue

successful

CE.PRM

Service call parameter error

CE.DIR

RSX Directive error
Second status word contains the DSW

CE. !ER

I/O Termination error
Second status word contains the IOSB first word

CE.IEA

Internal error

2.3

PRO/COMMUNICATIONS SERVICES

PRO/Communications services consist of:
•

An application that you can invoke from the P/OS menu system.

•

A set of utilities that you can call
program.

•

A set of routines that allow you to perform
File Transfer operations.

from

your
Phone

application
Book

and

As
with
the
Base
System
Services,
you
can
access
PRO/Communications services by calling the COMLIB routines.

2-25

PRO/COMMUNICATIONS SERVICES
The following sections describe PRO/Communications start-up, the
utilities you can execute, and the routines that allow you to
perform Phone Book and File Transfer operations.

2.3.1

PRO/Communications Start-Up

Once you have installed PRO/Communications on your system, every
time
you
power
up
a
Professional
and
boot P/OS, a
PRO/Communications Start-Up Program executes.
It performs the
following operations:
•

installs necessary PRO/Communications tasks

•

starts up the background File Transfer Subsystem

The PRO/Communications Start-Up Program is present on your system
only if you have installed PRO/Communications.

2.3.2

PRO/Communications Utilities

Any application program can use the PRO/Communications utilities.
If you install PRO/Communications on the machine, the system
installs all utilities as part of the start-up procedure.
The utilities supplied with PRO/Communications are:
•

Communications Set-Up - allows the user to specify parameters
that control the functioning of the communications services.
To allow users to change the parameters, your application
program can either invoke this service or call the Base
System routines.

•

Terminal Emulator - allows the Professional to act as a
VT102, VT125, VT52 or native mode terminal connected to a
host operating system. Your program can invoke the terminal
emulator to allow the user to communicate with a host system.
The host system, in turn, can terminate the emulator and
return control to the application.

•

Call Services - allows users to dial and answer calls, using
either TMS or an autodial modem attached to the Communication
Port. This service runs a call control task that you can use
to make connections via entries stored in the Phone Book.

2-26

PRO/COMMUNICATIONS SERVICES
•

Phone Book Maintenance - allows users to maintain the phone
book.
The phone book is a file containing information about
how to connect a Professional to another computer system.
Note that the routines you can use to access the phone book
do not allow maintenance. The phone book runs two programs
as tasks:
a file maintenance program and a server program
that reads or displays entries in the phone book.
You can
call the server program through the phone book services.

Each

the

utilities

has

user

interface.

See

the

Pro/Communications

Manual for a description of the utilities and
their user interfaces. Also, see the Terminal Subsystem Manual
for additional details on the terminal emulator.

You use the CCSPWN routine (see
initiate a utility.

below)

make

request

2.3.2.1 Spawn Communications Utility (CCSPWN) - This routine
spawns a PRO/Communications utility task. On termination the
routine returns the exit status to the requester.
Format:
CCSPWN (status, name)
status

A two-word status block as described in Section 2.1.1.

name

A four-byte string that identifies the requested utility.
EMUL
CSET
CALL
PHNE

Terminal Emulator
Communications Set-Up
Call Services
Phone Book Maintenance

Status:

cs.sue

Successful

CE.PRM

Service call parameter error

CE.DIR

RSX Directive error
Second status word contains the DSW

CE.IEA

Internal error

2-27

PRO/COMMUNICATIONS SERVICES
Note:

In the case of a successful return, the routine returns the exit
status of the utility in the second status word, as follows:
1.

2-4
5-9.
9.
10.

2.3.3

Successful
Error exit
Unused
MAIN SCREEN key was used to terminate program
EXIT key was used to terminate program

Phone Book Services

The services described in this section allow an application to
read specified entries from the phone book, or display the phone
book and allow the user to select an entry.
To perform phone
book maintenance, you must use the phone book maintenance
program.

2.3.3.1

Get Phone Book Record (CPHREC) - This service returns

specified record from the phone book.
Format:
CPHREC (status, name, number, numlen, descr, descrlen, ldb)

status

A two-word status block as described in Section 2.1.1.

name

A 15-byte, space-filled string in which you specify the
name of the entry to be retrieved.

number

A string in which the routine returns the
number. The string can be up to 48 bytes.

numlen

An integer the routine returns indicating the length of
the telephone number.

descr

A string in which the routine returns the description
stored in the phone book. The string can be up to 40
bytes.

descrlen

The length of the description string.

ldb

The line descriptor block, a 16-element byte string in
which the routine returns the line characteristics
required to set up the call.

2-28

telephone

PRO/COMMUNICATIONS SERVICES
Status:

cs.sue

Successful

CE.PRM

Service call parameter error

CE.DIR

RSX Directive error
Second status word contains the DSW

CE.IER

I/O Termination error
Second status word contains the IOSB first word

CE.NNF

Name not found

CE.IEA

Internal error

Note:
If you call this routine with
functions identically to CPHSEL.

blank

name

parameter,

2.3.3.2 Select Phone Book Entry (CPHSEL) - This service displays
all the phone book entries and allows the user to select a
specific entry from those available. Note that the task that
calls CPHSEL must be running from TT1:, or the system returns the
error CE.IEA.
Format:
CPHSEL (status, name, number, numlen, descr, descrlen, ldb)
status

A two-word status block as described in Section 2.1.1.

name

A 15-byte string in which the routine returns the
of the entry to be retrieved.

number

A string in which the routine returns the
number. The string can be up to 48 bytes.

numlen

An integer the routine returns indicating the length of
the telephone number.

descr

A string in which the routine returns the description
stored in the phone book. The string can be up to 40
bytes long.

descrlen

The length of the description string.

ldb

The line descriptor block, a 16-element byte string
2-29

name

telephone

PRO/COMMUNICATIONS SERVICES
which the routine returns
required to set up the call.

the

line characteristics

Status:
cs.sue

successful

CE.PRM

Service call parameter error

CE.DIR

RSX Directive error
Second status word contains the DSW

CE.IER

I/O Termination error
Second status word contains the IOSB first word

CE.NNF

Name not found

CE.IEA

Internal error

CE.CTB

CTAB display error (empty phone book)

2.3.4

File Transfer Services

This section describes services that allow you to use the File
Transfer Subsystem.
Using the File Transfer Subsystem, you can
transfer files between Professionals through callable service
routines.
(Note that PRO/Communications already includes a
Professional-to-Professional file transfer application, which
itself uses the File Transfer Subsystem.)
The File Transfer Subsystem consists of the following components:
•

Communications Manager Program - controls the initiation
termination of the file transfer programs.

•

File Transfer Server - executes in response to a request from
another system to initiate a file transfer.
The server
communicates with the "host" program to perform a
file
transfer.
The host program currently runs on RSX-11M/11M+,
VMS or the Professional.

•

File Transfer Host Program - initiates a file
communicates with the server program.

•

Listener Program - monitors the following communication lines
in the background:
the Communication Port, TMS line 1 and
TMS line 2. The program monitors lines in data mode only for
ASYNC transfers. When the Professional receives unsolicited

2-30

transfer.

and

PRO/COMMUNICATIONS SERVICES
ASYNC data over a monitored line, the listener program
attempts to interpret the data as an ANSI escape sequence,
provided the line is not currently
attached
and
no
outstanding reads are present. The listener processes only
file transfer requests.
You can initiate a file transfer to the Professional either when
the Professional is in terminal emulation mode or when the
listener intercepts the file transfer escape sequence.
The
latter case constitutes a background transfer.
The File Transfer Subsystem always runs asynchronously in the
background; however, the program issuing calls to lt can either
synchronize with each call to the Subsystem or run file transfer
operations asynchronously.

2.3.4.1

File

Transfer

Protocol - Receipt

Initiation

escape sequence initiates file transfer.

of
the
The escape sequence is:

ESC [ 1 ! ""
Prior to sending the escape sequence, the file transfer host
program tries to determine if the Professional is able to perform
the transfer. It does this by sending a device status request
( DSR) :
ESC [ 5 n
The Professional must respond with
response report:

"ready,

malfunctions"

ESC [ 0 n
After accepting the file transfer
escape
sequence,
your
application should request the file transfer server task. At the
end of the file transfer, a further DSR escape sequence will be
received and the "ready, no malfunctions" report described above
must be returned.

order to
initiate a file transfer, the requesting task must attach the
File Transfer Subsystem.
This applies both
to
transfers
initiated by the local system and requests to activate the server
in response to requests from a remote system.
Because of
processor limitations, only one file transfer can be active in
the system at any time.
If another task has alread attached the
File Transfer Subsystem, the Subsystem rejects further requests
2.3.4.2

Attaching the

File

Transfer

2-31

Subsystem - In

PRO/COMMUNICATIONS SERVICES
for attachment. The process of attachment informs the File
Transfer Subsystem of the line on which it performs the transfer.
Also, attachment can optionally send a password to the remote
system (if the local system is the initiator).

2.3.4.3 Releasing
the
File
Transfer
Subsystem - You
automatically
release
the
File
Transfer
Subsystem upon
terminating the task that attached it. Also, you can explicitly
request the release of the Subsystem (using the FTDET routine).
Note that any queued requests continue to be processed, even if
you have released the Subsystem.

Synchronous and Asynchronous Operations - A program that
initiates an operation to the File Transfer Subsystem has two
options. It either can wait for the operation to complete, or
can synchronize with the return message at a later point in time.
This is called an asynchronous operation; you can use it to
initiate multiple file operations.
2.3.4.4

Each call to the file transfer services (except FTDET) results in
a message sent to the File Transfer Subsystem. For each message
sent, the Subsystem returns a response to the requesting task
(unless suppressed).
You can synchronize these responses by
calling the FTSYNC routine. Use the msgid parameter to identify
the response to the requesting task.

File Transfer
Synchronization - The
file
transfer
service calls contain "reply" and "sync" parameters to enable
synchronization between your application program and the File
Transfer Subsystem.
Calls to the file transfer routines that
contain a "reply" parameter cause action messages to be sent to
the File Transfer Subsystem. The Subsystem generates response
messages depending on the value you specify for "reply." These
messages
are
passed using the variable send/receive data
directives.
You can synchronize the caller with
response
messages from the Subsystem by either setting the sync parameter
when issuing a call and setting the reply flag to 2 (running the
Subsystem synchronously), or calling the FTSYNC routine, which
also uses the sync parameter.
2.3.4.5

In either case, setting the sync flag causes the calling task to
stop for a response message from the File Transfer Subsystem.
The user's impure data area holds the response; you can access it
by calling FTUNPK.

2-32

PRO/COMMUNICATIONS SERVICES
The possible values for "reply" are:
Bit(s)

0-1

Value

0
1

2-3

0
1

2
3

3-15

Meaning

No response message.
Response message requested.
Response message and unstop requested.
File Transfer Subsystem will issue unstop
directive for requesting task. You
must use this value if sync flag = 1.
Do not write message to system message board.
Write message to system message board.
Write message to system message board only
on error.
Write message to system message board only
if successful.
Reserved.
NOTE

The File Transfer Subsystem writes messages to
the system message board when a task that has
requested a response message has exited.

Set Up File Transfer Options (FTOPTG and FTOPTP) - Two
routines allow you to configure the file transfer options for
automatic file transfer initiated by a remote system.
The
routine FTOPTG returns the current option settings; the routine
FTOPTP modifies the current option settings.
2.3.4.6

Format:
FTOPTG (status, flags, pswrd, vol, direc, max_file)
FTOPTP (status, flags, pswrd, vol, direc, max_file)

status

A two-word status block as described in Section 2.1.1.

flags

Option Flags:

2-33

PRO/COMMUNICATIONS SERVICES
bit 0

1
0

Enable remote file copy
Disable remote file copy

bit 1

1
0

Enable remote file receive
Disable remote file receive

bit 2

1
0

Supersede existing files
Do not supersede existing files

bit 3

1
0

Enable password security
Disable password security

bit 4

1
0

Local delete enabled
Local delete disabled

Bits 5 through 15 are reserved.
pswrd

A nine-character password to be used by a remote
Professional.
It must be space filled if you have
disabled password security.

vol

A 12-character name of the volume to which the File
Transfer Subsystem places files received from another
Professional. The Subsystem uses this parameter only
if the incoming file specification contains no volume
specification.

direc

A nine-character name of the directory into which the
File Transfer Subsystem places files being received
from another Professional.
The Subsystem uses this
parameter only if the incoming file specification
contains no directory specification.

max_file

A two-word integer specifying the maximum size, in
blocks, of a local file that the remote Professional
can create. Note that a zero value indicates no limit.

Status:

cs.sue

Successful

CE.PRM

Service call parameter error

CE.RMS

File I/O error
PRO/RMS-11 error code passed in second word

CE. IEA

· Internal error

2-34

PRO/COMMUNICATIONS SERVICES

NOTE
These routines
perform
file
I/O
to
the
communications set-up data file.
(This file
stores default line characteristics,
translate
tables,
and
other information used by the
communications services.) In order to perform the
file I/O, you must assign a logical unit number
to the set-up data file.
You do this
by
inserting the following global definition command
in your PAB command (.CMD) file:
GBLDEF = CM$LUN:lun
lun is the logical unit number that the system
associates with the communications set-up file.
See the section on command files in this manual
for
further
information.
Also,
see
the
description of GBLDEF in the RSX-llM/M-PLUS and
Micro/RSX Task Builder Manual.

2.3.4.7 Attach File Transfer Subsystem (FTATT) - This routine
attaches the designated line to the issuing task for use with the
File Transfer Subsystem. You must call this routine prior to
invoking any of the other File Transfer Subsystem routines,
except as noted in the routine definitions. The issuing task can
optionally specify a password to gain access to the remote
system.
Format:
FTATT (status, msgid, reply, sync, dev, unit, 'PSWD', paswrd)
status

A two-word status block as described in Section 2.1.1.

dev

A two-byte ASCII string containing the device mnemonic.

unit

The unit number.

A reply flag.

msgid

An unsigned integer that identifies
for this call.

2-35

the

return

message

PRO/COMMUNICATIONS SERVICES
sync

A synchronization flag:
an
whether or not the calling
response message is queued.

integer
program

that
will

determines
stop if no

0 - Do not stop ·for response
1 - Stop for response message
PSWD

An optional keyword that specifies the presence
password parameter immediately following.

paswrd

A optional nine-byte string containing the password for
the remote system, space-filled. You must immediately
precede this parameter with the PSWD keyword.

Status:

cs.sue

Successful

CE.PRM

Service call parameter error

CE.DIR

RSX Directive error
Second status word contains the DSW

CE.IEA

Internal error

Notes:

If a task issues two calls to FTATT without an intervening
to FTDET, an error occurs on the second call to FTATT.

call

2.3.4.8 File Transfer Operation Request (FTOPRN) - This routine
issues file operation requests to the File Transfer Subsystem.
The routine allows you to:
transfer files between systems,
determine the status of file transfers currently in progress, or
abort the current transfer.
You can specify only one file
operation request in any call to the routine.
Format:
FTOPRN (status, msgid, reply, sync, request)

The format of a request is:

2-36

PRO/COMMUNICATIONS SERVICES
status

A two-word status block as described in Section 2.1.1.

msgid

An unsigned integer that identifies
for this call.

Reply flags.

sync

A synchronization flag:
an
whether or not the calling
response message is queued.

the

integer
program

return

that
will

message

determines
stop if no

0 - Do not stop for response
1 - Stop for response message
ABRT

Allows you to abort the current file operation.
If no
file operation is in progress, the routine returns an
error in the "status" parameter.

STAT

Causes the routine to return statistics on the current
file transfer operation to the caller. You can access
the statistics via the FTUNPK routine.

SEND

Allows you to transfer files to the remote system.
You
can use only a single file specification (no wildcards).

READ

Allows you to transfer files from the remote system. You
can use only a single file specification (no wildcards).

fspecl

A string buffer holding the
file to be transferred.

lenl

The length of fspecl.

fspec2

A
string
buffer
holding
the
destination
specification of the file to be transferred.

len2

The length of fspec2. By default, the destination file
has the same name and type as fspecl.
If no change is
required, len2 should be zero. If you want to place the
file on a specific device or in a specific directory, you
must specify fspec2; otherwise, the routine uses the
system's default destination.

DELE

Allows you to delete a file at a remote system. You can
only specify a single file specification (no wildcards).

2-37

file

specification

the

file

PRO/COMMUNICATIONS SERVICES
fspecl

A string buffer holding the
file to be deleted.

file

specification

the

lenl

The length of

protcl

A one-word integer indicating the protocol to be used
the operation. It can have one of two values:

fspe~l.

0 - Use existing file transfer protocol (default)
1 - Use encoded protocol
In order to use encoded protocol, both systems involved
in the file transfer must be running PRO/Communications
V3.0 or later.
Status:

cs.sue

Successful

CE.PRM

Service call parameter error

CE.UNO

Unsupported message option

CE.MFE

Message format error

CE. IMO

Operation rejected

CE.MSC

Message type out of sync

CE.DOC

DDCMP error

CE.RMS

File I/O error
RMS Error code passed in second word

CE.NFT

No file transfer

CE.IEA

Internal error

2.3.4.9 Notify On Incoming File (FTNTFY) - This routine requests
the File Transfer Subsystem to notify a specified task when a
file is received from a remote system.
Upon arrival of each
file, the Subsystem sends a duplicate of the response message
that it returns to the task requesting the server activation.
This indicates the full specification of the incoming file and
termination statistics.

2-38

PRO/COMMUNICATIONS SERVICES
Format:
FTNTFY (status, msgid, reply, sync, notify,

'TASK', taskid, 'CNCL')
status

A two-word status block as described in Section 2.1.1.

msgid

An unsigned integer that identifies
for this call.

Reply flags.

sync

Synchronization flag: an integer that determines whether
or not the calling program stops if no response message
is queued. This parameter applies only to the File
Transfer Subsystem's initial verification to indicate
acceptance of the request.

the

return

message

0 - Do not stop for response
1 - Stop for response message
notify

Notification flag: an integer that
File Transfer Subsystem notifies
specified file has arrived.

determines how
the task that

the
the

1 - Send the notification message to the specified task.
2 - Send notification message and unstop the specified task.
3 - Send the notification message using the request and
connnect directive.
TASK

Requests the
File
Transfer
Subsystem
to
direct
notification messages to the task specified in taskid.
If you omit this option, the routine by default uses the
current task name.

taskid

Task to be notified, in Radix-50 format.

CNCL

Cancels previous requests for file transfer notification.
The only other optional parameter that you can use with
'CNCL' is 'TASK.'

Status:

cs.sue

Successful

CE.IMO

Operation Rejected

CE.PRM

Service call parameter error

CE.IEA

Internal error

2-39

PRO/COMMUNICATIONS SERVICES
CE.DIR

RSX Directive error
Second status word contains the DSW

Notes:

The File Transfer Subsystem sends response messages to the
specified task.
You can interpret these messages by using the
FTSYNC and FTUNPK routine to access the filename and termination
statistics of the file received.
Setting the sync flag when
calling FTSYNC requires having used a notification flag = 2. The
original msgid you specified when calling FTNTFY is preserved in
all subsequent notification messages. The task being notified
need not be active.

Synchronize with File Transfer
(FTSYNC) - Use this
routine to synchronize your task with an asynchronous request
previously issued by a call to FTATT, FTDET, FTOPRN or FTNTFY.
It places a response message from the File Transfer Subsystem
into the calling program's impure data area.
You
should
immediately unpack the response message by calling FTUNPK.
2.3.4.10

Format:
FTSYNC (status, msgid, sync)

status

A two-word status block as described in Section 2.1.1.

msgid

A message identifier that the File Transfer Subsystem
returns. You pass this parameter in the original call.

sync

Synchronization flag: an integer that determines whether
the program stops if no message is currently queued.
0
1

Do not stop
Stop for response message

Status:

cs.sue

Successful

CE.PRM

Service call parameter error

CE.IMO

Operation Rejected

CE.STU

File transfer start-up in progress

CE.IEA

Internal error

2-40

PRO/COMMUNICATIONS SERVICES
Unpack File Transfer Message Area
(FTUNPK) - This
routine unpacks the message components from the impure data area.
You specify each message component with a keyword. Note that the
calling task need unpack only those components that are of
interest to it. You mus.t immediately precede a call to FTUNPK
with a call to FTSYNC.
2.3.4.11

NOTE

Any call to the other communication service
routines between calls to FTSYNC and FTUNPK can
overwrite the response message held in
the
application's impu~e data area.
Format:
FTUNPK (status,

status

A two-word status block as described in Section 2.1.1.

SIZE

Returns a two-word integer indicating the size
file you are transferring.

filesize

A two-word integer into which the
file's size.

FILE

Returns the name of the current file on which
performing the file operation.

f spec

A buffer into which the

routine

the

places

the

you

are

routine can place the
specification of the file being transferred.
buffer should be at least 50 bytes long.

file
This

len

The length of the file specification
fspec buffer.

the

BLCK

Returns the current block number of the
transferring.

you

are

blcknum

A two-word integer that receives the current
number of the file you are transferring.

block

DEVC

Returns the
operation.

file

device

mnemonic

2-41

for

returned

the

file

current

PRO/COMMUNICATIONS SERVICES
dev

A two-byte
mnemonic.

ASCII

string

that

receives

the

UNIT

Returns the unit number for the current file operation.

unit

An integer that receives the unit number.

TIME

Returns the elapsed time for the current file transfer.

elpstim

A two-word integer that receives the
seconds.

OPER

Returns the current file operation.

elapsed

device

time

operation A single-length integer that receives the code for
operation in progress:

the

1 - READ
2 - SEND
3 - LOCAL DELETE
4 - REMOTE DELETE
Status:

cs.sue

Successful

CE.PRM

Service call parameter error

CE. IMO

Operation rejected

CE.MSC

Message type out of sync

CE.IEA

Internal error

Detach File Transfer (FTDET) - This routine detaches
the File Transfer Subsystem from use by the requesting task.

2.3.4.12
Format:

FTDET (status, msgid, reply, sync)

status

A two-word status block as described in Section 2.1.1.

msgid

An unsigned integer that identifies
for this call.

Reply flags.

Status:

2-42

the

return

message

PRO/COMMUNICATIONS SERVICES

cs.sue

Successful

CE.PRM

Service call parameter error

CE.DIR

RSX Directive error
Second word contains the DSW

CE.IEA

Internal error

2.3.4.13 Start File Transfer Server (FTSERV) - This routine
requests the file transfer server on the local system.
You
should call this routine in conjunction with initiation of the
host file transfer program.
Format:
FTSERV (status, msgid, reply, sync, protcl)

status

A two-word status block as described in Section 2.1.1.

msgid

An unsigned integer that identifies
for this call.

Reply flags.

sync

Synchronization flag:
or not the calling
message is queued.

the

return

message

an integer that determines whether
program will stop if no response

0 - Do not stop for response message
1 - Stop for response message
protcl

A one-word integer indicating the protocol to be used
the operation.
It can have one of two values:

cs.sue

Successful

CE.PRM

Service call parameter error

CE.UNO

Unsupported message option

2-43

PRO/COMMUNICATIONS SERVICES
CE.MFE

Message format error

CE.IMO

Operation rejected

CE.MSC

Message type out of sync

CE.DOC

DDCMP error

CE.RMS

File I/O error
RMS Error code passed in second word

CE.NFT

No file transfer

CE.IEA

Internal error

Enable/Disable File Listening (FTLISN) - Calling this
routine with the enable flag set causes the File Transfer
Subsystem to monitor an unattached line for unsolicited data.
The listener program reads unsolicited data from the specified
line. Upon receiving a valid file transfer request, the listener
automatically initiates a file transfer.
2.3.4.14

Note that other applications can ATTACH or DETACH the File
Transfer Subsystem; however, the listening task will not be able
to initiate file transfers while the Subsystem is attached.
Format:
FTLISN (status, dev, unit, flag)

status

A two-word status block as described in Section 2.1.1.

dev

A two-byte ASCII string containing the device mnemonic.

unit

The unit number.

flag

A flag that indicates the type of request:
0 - Disable listening
1 - Enable listening

Status:

cs.sue

Successful

CS.FLE

File listening already enabled with enable request

CS.FLO

File listening already disabled with disable

2-44

reque~

PRO/COMMUNICATIONS SERVICES
CE.PRM

Service call parameter error

CE.DIR

RSX Directive error
Second word contains the DSW

CE. IEA

Internal error

Note:

If you call FTLISN with just the status parameter, the second
status word contains the current listener status. Bit zero set
means listening is enabled on XKO:.

2.4

TELEPHONE MANAGEMENT SYSTEM {TMS) SERVICES

This section describes services that
program to control the TMS hardware.

enable

your

application

Note the following if you are using CODEC input on a TMS line:
TMS digitizes the voice signal at 4 kilobytes per second, and so
you will lose voice data unless you perform asynchronous I/O and
double buffer the input requests.
Each input request should
specify a 4 kilobyte buffer; this provides 1 second for your
application to process the first buffer before the second buffer
fills.
The following sections describe TMS start-up and routines.

2.4.1

TMS Start-Up

Base system start-up loads the TMS device driver
default line characteristics for each TMS line.

2.4.2

and

sets

the

TMS Routines

This section describes the routines that you can call to control
the operation of the TMS hardware.
Note that you must have
installed the IS;...hardware in order to call any of the routines.

2.4.2.1 Change Mode (CCMODE) - This routine changes the current
mode of the line.
The line must be attached. Alsor the mode
change does not take effect until you issue a CCANS or CCORG
call.

2-45

TELEPHONE MANAGEMENT SYSTEM (TMS) SERVICES
Format:
CCMODE (status, lun, mode)

status

A two-word status block as described in Section 2.1.1.

lun

The logical unit number for the communication line.

mode

One of the following available mode settings:
0
1
2
3

VOICE

= ASYNC (Modem)
CODEC
DTMF Keypad (Touch-Tonee pass all keys)

Status:

cs.sue

Successful

CE.PRM

Service call parameter error

CE.DIR

RSX Directive error
Second status word contains the DSW

CE.IER

I/O Termination error
Second status word contains the IOSB first word

CE.IEA

Internal error

Note:

After calling CCMODE, if you want to change the current mode to
ASYNC, you must establish a connection by calling CCORG. In the
case where your application will be communicating with another
TMS unit, one unit must be in originate mode (using CCORG) and
the other TMS unit must be in answer mode (using CCANS).

Auxiliary
Keyboard
Enable/Disable
(CCAUXK) - This
routine enables or disables the auxiliary keyboard for the
specified TMS line. The line must be attached.
An AST trap
signals input from the auxiliary keyboard. You must use the
CCATA routine to attach the line.
2.4.2.2

Format:
CCAUXK (status, lun, flag)

2-46

TELEPHONE MANAGEMENT SYSTEM (TMS) SERVICES
status

A two-word status block as described in Section 2.1.1.

lun

The logical unit number for the communication line.

flag

This flag indicates
enabled/disabled:

0
1

whether

the

keyboard

being

Disabled
Enabled

Status:

cs.sue

Successful

CE.PRM

Service call parameter error

CE.DIR

RSX Directive error
Second status word contains the DSW

CE. IER

I/0 Termination error
Second status word contains the IOSB first word

CE. IEA

Internal error

2.4.2.3 Prepare to Go Voice (CCPTGV) - This routine warns
specified TMS line that it is about to go into VOICE mode.
does not disconnect the call when the change in mode occurs.
line must be attached.

the
TMS
The

Format:
CCPTGV (status, lun)
status

A two-word status block as described in Section 2.1.1.

lun

The logical unit number for the communication line.

Status:

cs.sue

Successful

CE.PRM

Service call parameter error

CE.DIR

RSX Directive error
Second status word contains the DSW

CE.IER

I/O Termination error
Second status word contains the IOSB first word

2-47

TELEPHONE MANAGEMENT SYSTEM (TMS) SERVICES
CE. IEA

Internal error

Note:

You can call CCHNG to cancel CCPTGV and disconnect the
line.

telephone

2.4.2.4 Set DTMF Escape Sequence (CCDTMF) - This routine sets a
DTMF escape sequence on the specified TMS line. The line must be
attached. When the TMS unit recognizes the DTMF escape sequence
the driver causes an unsolicited event AST for the user task to
indicate the event.
(See the TMS Programmer's Manual.)
Format:
CCDTMF (status, lun, dtmf, dtmflen)

status

A two-word status block as described in Section 2.1.1.

lun

The logical unit number for the communication line

dtmf

A string that contains the DTMF escape
string terminates with a zero byte.

sequence.

The

dtmflen The length of the DTMF escape sequence.
Status:

cs.sue

Successful

CE.PRM

Service call parameter error

CE.DIR

RSX Directive error
Second status wor'a contains the DSW

CE. IER

I/O Termination error
Second status word contains the IOSB first word

CE. IEA

Internal error

2-48

CHAPTER 3
FAST INSTALL

Fast Install allows you to install your application without
having to build application diskettes.
It saves time when you
are testing .your application.
Fast Install does the following:
•

Checks the syntax
command file.

and

organization

your

installation

•

Processes EXECUTE/INS commands in your installation command
file.
(It does not process EXECUTE commands with the /CLS,
/NTW, or /USR commands.) See Chapter 6 for details on the
EXECUTE command.

•

Places the application name into the P/OS menu system.

Fast Install is distributed with the Host Tool Kit and the
PRO/Tool Kit on the Application Diskette Builder (ADB) diskette.
To use Fast Install, follow these steps:

If you have not already installed Fast Install on your
Professional, do so now.
Insert the ADB diskette and install
it as you would any application.

Copy your application files to the appropriate device and
directory as shown in Table 3-1. The table shows how to use
the qualifiers you have specified on FILE commands in your
installation file to determine the destination of your files.

Select Fast Install from the menu on which it was installed.

Fast Install prompts for the name of your application
directory and for the file type ~.INS or .INB) of your
installation command file.
Enter the information and press
DO.

3-1

FAST INSTALL
5.

Fast Install opens the installation command file, checks the
format, and displays a list of application groups. Select
the group in which you want to install your application and
press DO.

After successful installation, you can run
from the P/OS user interface.

Table 3-1:

your

application

Application File Locations for Fast Install

FILE Command

Copy File To

FILE fname.ext
or
FILE fname.ext/USER

SYSDISK:[applicdir]
where applicdir is the name of
your application directory,
which must be the same as the
name of your installation
command file.

FILE [dir]fname.ext
or
FILE [dir]fname.ext/USER

SYSDISK:[dir]
where dir is the name of the
directory that you specified in
the FILE command in your
installation command file.

FILE fname.ext/NETWORK

SYSDISK:[applicdir]
where applicdir is the name of
you application directory,
which must be the same as the
name of your installation
command file.

FILE [dir]fname.ext/CLUSTER

LBOOO:[dir]
where dir is the name of the
directory that you specified in
the FILE command in your
installation command file.

FILE fname.ext/CLUSTER

For details on this case, see
Section 3.1.

3-2

FAST INSTALL

Notes:
•

If Fast Install cannot find the application directory, or the
application
directory does not contain an installation
command file with the same name, installation fails.

•

If a PRO/RMS-11 record error occurs while Fast Install is
opening the installation command file, look up the error code
in the PRO/RMS-11 manual set.
If you cannot correct the
problem,
contact
your
local DIGITAL software support
representive.

•

If the installation command file contains errors
Fast Install prints them.

3.1

INSTALLING DECNET OBJECTS FOR TESTING

syntax,

Applications that contain a DECnet object use a /CLUSTER file
named DECNET.ODS, and possibly other /CLUSTER files, in the FILE
command of the installation file.
If you specify the directory
in the FILE command for these files, naming conflicts can occur
with the /CLUSTER files of other applications.
To avoid such conflict, the system creates a directory for these
/CLUSTER files during normal installation. However, because Fast
Install does not copy any files, you must manually create the
directory, copy the /CLUSTER files into it, and place an entry in
the DECnet object database.
Follow these steps:
•

On P/OS Server systems,

•

Create a new directory on device LBOOO:.

•

Copy all /CLUSTER files that do not specify a directory in
the FILE command of the installation command file to the
directory you created in the previous step.

•

Using DCL on your Professional, issue the following commands:

$ASSIGN LBOOO:[directory] APPL$DST
$ASSIGN LBOOO:[directory] APPL$DST:
$ ASSIGN "applic_name"
DST$NAME
$RUN LBOOO:[ZZDECNET]DAI/COMMAND="/INS/CLS"

3-3

you

CHAPTER 4
FILE CONTROL SERVICES (FCS)

File Control Services (FCS) is a set of file management routines
for use on the RSX-11 family of operating systems. It was
designed for the RSX-llD operating system in the early 1970s, and
has been implemented subsequently for IAS, RSX-llM, RSX-llM-PLUS,
the RSX Application Migration Executive on VMS, and for the RSX
run-time system on RSTS/E. FCS can be considered the precursor
of Record Management Services (RMS-11), which is implemented on
all of the above systems as well as on P/OS (PRO/RMS-11).
NOTE

FCS is described in detail in the IAS/RSX-11 I/O
Operations Reference Manual, which is part of the
RSX-llM/M-PLUS documentation set.
Originally, P/OS applications could use only PRO/RMS-li for file
system operations. All applications targeted for P/OS had to use
PRO/RMS-11. Applications that had been written to use FCS had to
be converted to use PRO/RMS-11 instead.
With the release of the PRO/Tool Kit Vl.O and the Host Tool Kit
Vl.7, the FCS routine library became part of the P/OS system
module library. Tool Kit V3.0 also includes a vectored FCS
resident library.
Thus, you can move applications that use FCS
to P/OS without conversion to PRO/RMS-11. ·
Although P/OS provides a full implementation of FCS, you are
urged to always use RMS in new applications. Use FCS to port
applications designed to run on
RSX
systems
when
such
applications already use FCS.

4.1

SUPPORT BY HIGH-LEVEL LANGUAGES

Programs written in MACR0-11 assembly
Programs written in other Tool Kit
4-1

language can use FCS.
languages (BASIC-PLUS-2,

File Control Services (FCS)
COBOL-81, PRO/DIBOL, FORTRAN-77 and PASCAL) do not work with FCS
because the Object Time Systems (OTS) of these languages on P/OS
use PRO/RMS-11 rather than FCS. The RSX versions of some of
these languages will work on P/OS provided that the programs are
linked using the Tool Kit version of the System Library (SYSLIB)
which includes FCS.
High-level languages available from vendors other than DIGITAL
can use FCS in their object-time systems.
Please refer to
product documentation of these software products.

4.2

USING FCS RESIDENT LIBRARY

Vectored FCS is included with the Tool Kit V3.0.
It is
compatible with the FCSRES for Micro/RSX and RSX-llM-PLUS. A
task linked with vectored FCS can perform FCS operations on
either system without relinking.

4.3

USING FCS IN-TASK VERSION

FCS is also available as modules that
task's virtual address space.

you

can

include

the

NOTE

We recommend that you use the resident library if
possible, since that ordinarily enables the task
to acquire new functionality without relinking.
If it is not possible or desirable to use the resident library,
you can automatically include the same FCS modules from SYSLIB.
However, note that the FCS modules in SYSLIB can handle only
those logical names that translate to devices; the modules do not
handle logical names that translate to any other fields in a file
specification.
Perform the following steps if you are using the in-task version
of FCS and you require the enhanced logical name capability:
1.

Make copies of LB:[l,5]RSXMAC.SML and LB:[l,5]SYSLIB.OLB.
These two libraries will be modified in the following steps.
It will be easier to return the current capabilities if you
save these libraries.

4-2

File Control Services (FCS)
The next three steps show DCL commands
perform the modifications.

that

you

invoke

$ LIBRARY/REPLACE LB:[1,5]RSXMAC.SML FCSMAC.NEW

$ LIBRARY/REPLACE LB:[1,5]SYSLIB.OLB FCSEP.NEW

$ LIBRARY/REPLACE/NOGLOBALS LB:[1,5]SYSLIB.OLB FCSNOEP.NEW

Assemble and taskbuild your programs.

The replacement modules were not included in the distributed
version of SYSLIB because they require more virtual address space
than the existing FCS modules.
Should it be necessary to restore RSXMAC and SYSLIB
prior
states,
replacement modules are provided.
following DCL commands to restore RSXMAC and SYSLIB:

to their
Use the

$ LIBRARY/REPLACE LB:[1,5]RSXMAC.SML FCSMAC.OLD

$ LIBRARY/REPLACE LB:[1,5]SYSLIB.OLB FCSEP.OLD

$ LIBRARY/REPLACE/NOGLOBALS LB:[1,5]SYSLIB.OLB FCSNOEP.OLD

4-3

CHAPTER 5
FRAME DEVELOPMENT TOOL {FDT)

The Frame Development Tool (FDT) is a special-purpose utility for
creating menu, help, and message frames. When these frames are
used with the POSRES User Interface Library, they provide a user
interface for your P/OS application. Designing a user interface
and programming with POSRES are described in the Tool Kit User's
Guide.

5.1

FDT OVERVIEW

Creation or modification of a frame file
steps:

follows

these

general

Plan your frames. You should have a good idea of what frames
your menu structure and help structure will require before
you use FDT.

Start FDT and specify a filename for the frame definition
file.
If you are creating a new file, specify the type of
frames (menu, help or message) you want to create.
This
leaves you at File Command level.

Enter a File Command. When creating a new frame file, you
would typically use the Add command. When modifying a frame
file, you might use commands such as Add, Delete, Modify.

If you are adding or modifying a frame~ enter a Frame
Command. A frame is defined by three separate forms that you
fill in or modify. While entering data in.a form, you use a
special set of keypad keys.
When you are finished with a form, you press ENTER. When you
are finished adding or modifying the frame, you enter the
Save or Quit command.

5-1

FDT OVERVIEW
5.

You are back at File Command level, where you can repeat
Steps 3 and 4 with another frame, or you can supply a File
Command that uses the whole frame file,
such as Convert,
List, Report, Window.
When you are finished with the file, you enter Save or Quit.

The following sections describe how to run FDT,
the File
commands,
the Frame commands, and the forms in more detail.
If
you would like to try out a sample FDT editing session before
moving on, turn to Section 5.11.

5.2

INVOKING FDT

FDT is invoked in different ways depending on whether you are
running it on a VAX, PDP-11, or your Professional. The commands
required to start it are discussed in the following sections.
In each case, FDT requires the name of the
not include the filename, FDT prompts for
If the file does not exist,
type is .DAT.
are creating a new file and prompts for
you will store in the file.:
Create (H)elp,

If you do
frame file.
one. The default file
FDT assumes that you
the type of frame that

(M)essage, or (S)ingle-choice menu file?

You enter H, M, or S.

NOTE
You can only store frames of the same type in a
file.
You must create separate files for help,
messages, and single-choice menus.

5.2.1

Invoking FDT on VAX/VMS

For convenience, edit your
following symbol definition:
$ FDT

file

and

insert

:== $FDT

Once the symbol is defined, you can invoke FDT by typing:

$ FDT filename

5-2

the

INVOKING FDT

5.2.2

Invoking FDT on RSX-11 M/M-PLUS (DCL)

If FDT is installed on your system as " ... FDT II, enter:

$ FDT filename
If FDT is not an installed task, enter:

$ RUN $FDT

5.2.3

Invoking FDT in PRO/Tool Kit

You must install the FDT task.
You might edit your start-up
command file with the appropriate command to install FDT from the
directory in which it resides.
To start FDT, enter:

$ FDT filename
If FDT is not an installed task, enter:

$ RUN $FDT

5.3

FILE COMMANDS

Some file commands operate on all frames in the frame file.
Other file commands operate on individual frames; these require
that you supply the name of the frame
(called the frame
identifier, or frameid)
with the command.
File commands are
entered in response to the prompt:
File Command:
With the exception of the QUIT command, you can abbreviate any
file command to a single character.
If you enter a command and
omit required parameters, FDT displays prompts requesting them.
While working at file command level, the current file type and
filename are displayed in a message at the top of your screen.

NOTE
Do not embed spaces in frame identifiers.
POSRES
routines cannot retrieve them correctly at run
time.

5-3

FILE COMMANDS
5.3.1

ADD

The ADD command begins the creation of a new frame.
New
can be added to a new or existing frame definition file.

frames

Format:

ADD f rameid
frameid

A string of up to eight alphanumeric
identifies the new frame.

characters

that

Notes

•

A frame identifier must consist of alphanumeric
characters. FDT converts all characters to uppercase.

•

If you are editing a help file, FDT prompts as follows:

ASCII

Help (M)enu or (T)ext?
Respond with M for a help menu or T for a help text frame.
•

FDT displays a Profile form, which is the first form you must
fill in when you are creating a new frame.

5.3.2

CONVERT

The CONVERT command creates a converted frame file that can be
read directly by POSRES menu services during program execution.
Format:

CONVERT output-file
output-file

The name of the converted frame file.

Notes:

•

The default file types for converted files are:
.HLP
.MSG
.MNU

Help definition file
Message definition file
Menu definition file

5-4

FILE COMMANDS
•

All required fields on frames must be filled in before the
frame is converted. If a frame lacks required information,
an error message appears and the frame is not converted.

•

FDT displays these messages:
x frames converted, y frames not converted.
The largest frame, "<framename>", is n (m octal) bytes long.
The numbers x, y, and n, are decimal. The number m is the
octal equivalent of n.
If there are unconverted frames,
other messages will appear.
Record the size of the largest frame converted. You can use
this number to compute the minimum amount of buffer space
required for frames of the type stored in this file (see the
discussions of the Professional Application Builder and the
P/OS User Interface Services in the Tool Kit User's Guide).

5.3.3

DELETE

The DELETE command deletes the specified frame from
file.

the

current

Format:

DELETE f rameid
frameid

The identifier of the frame to be deleted.

Notes:

•

Before deleting the frame, FDT shows the Display form for the
specified frame and prompts:
Delete this frame?
Enter YES to delete the frame; enter NO to avoid deleting it.
Control returns to the File Command prompt.

5.3.4

EXIT

The EXIT command saves the current frame definition file on disk
and exits from FDT.
(The EXIT command is identical to the SAVE
command.)

5-5

FILE COMMANDS
Format:

EXIT
Notes:

•

If the file already exists, it is assigned
version number.

•

After saving a file, FDT displays a confirmation message
naming the file saved and returns control to system command
level.

5.3.5

the

higher

FILE

The FILE command terminates processing of the
opens a new frame file.

current

file

and

The default file

type

Format:

FILE filename
filename

The name of the new frame file.
is .DAT.

Notes:

•

If you have modified the current file, FDT prompts:
Save current file?
Enter YES to save it, or NO to discard it.

•

If you are creating a new frame file,
type of file you want to create:

FDT

prompts

for

Create (H)elp, (M)essage, or (S)ingle-choice menu file?
Enter H, M, or S; or press RETURN to exit.

5.3.6

HELP

The HELP command displays a list of FDT file commands.
5-6

the

Frame Development Tool
Format:

HELP

5.3.7

LIST

The LIST command displays a list of the
file, by frame identifier.

frames

the

current

Format:

LIST
Notes:

•

The frames are listed in the order they were created,
although the order may change as a result of the addition or
deletion of frames.

5.3.8

MODIFY

The MODIFY command begins the process of
frame in the frame file.

modifying

existing

Format:

MODIFY frameid
frameid

The identifier for the frame to be modified.

Notes:

•

FDT displays a message indicating the frame is available
modification and displays the "Frame Command" prompt.

5.3.9

NAME

The NAME command renames a frame.

5-7

for

FILE COMMANDS
Format:

NAME old-frameid new-frameid
old-frameid

Is the frameid that is to be renamed.

new-frameid

Is the new name
characters).

5.3.10

(up

eight

ASCII

alphanumeric

QUIT

The QUIT command returns control to system command level without
saving the current file. All changes made to the current file in
the current editing session are discarded.
(All
of
the
characters in the QUIT command must be typed.)
Format:
QUIT

5.3.11

REPORT

The REPORT command creates
a
printable
file
containing
information about each frame in the current frame file.
Format:

REPORT filename
filename

The name of the
report.

output

file

that

will

contain

the

Notes:

•

The default file type for the report file is .RPT.

•

If you do not specify a filename, FDT uses the current
filename by default.

5.3.12

frame

SAVE

The SAVE command saves the current frame definition file on disk
and exits from FDT.
(The SAVE command is identical to the EXIT
command.)

5-8

Frame Development Tool
Format:
SAVE
Notes:
•

If the file already exists, it is assigned
version number.

•

After saving a file,
FDT displays a confirmation message
naming the file saved and returns control to system command
level.

5.3.13

the

higher

WINDOW

The WINDOW command converts the current file to a Synergy
frame file.
(See the Synergy Programmer's Manual.)

source

Format:
WINDOW filename
Notes:
•

The default file type is .SFF.

•

The text that appears in the Display form becomes the text in
the Synergy window.
Other text fields,
such as action
strings, become option values or comments in the Synergy
frame file.

Frame identifiers are not changed.
(The Synergy Frame
• Compiler
Tool diagnoses numeric names and names that are
longer than six characters.)
•

The conversion cannot be complete, since the frame files of
FDT and FCT do not provide identical functionality.
However,
FCT will diagnose most of the problems during the first
attempt to compile the Synergy frame file.
If you encounter
strange errors, use the CONVERT command to discover and
correct missing fields before trying the WINDOW command a
second time.

5-9

Frame Development Tool
the SFF files that you derive from your MNU and HLP
• Combine
files before using the Synergy Frame Compiler, so that
references to help frames will be resolved.

5.4

FRAME COMMANDS

Frame commands allow you to modify frames.
response to the prompt:

They are

entered

Frame Command:
With the exception of the QUIT command, you can abbreviate any
frame command to a single character. If you enter a command and
omit required parameters, FDT displays prompts requesting them.

5.4.1

ACTION

The ACTION command invokes Action forms for the options on the
current menu.
An Action form specifies a keyword, a help frame
pointer, and (for single-choice menus only) an action string for
each option.
Format:

ACTION

ALL

Specifies all options in the current menu.
default.

ALL

the

NEW

Specifies only those options for which you have
entered an action form.

not

yet

option

Specifies a particular option by

ordinal

number

12) •

Notes:

•

Action information can be assigned only to
frames).

5-10

menus

(not

text

Frame Development Tool
•

Each option must be assigned action information.

•

If you specify an option that has already been assigned
action information, the current description is displayed on
the Action form. You can then enter new information or
change existing information.

5.4.2

DISPLAY

The DISPLAY command invokes a Display form for the current frame.
The Display form contains the text that the user sees on the
screen.
Format:

DISPLAY
Notes:

•

A Display form for a menu contains
text, options, and prompt.

•

A Display form for a help text frame contains the
text.

•

A Display form for a message frame contains the message text.

5.4.3

the

title,

explanatory
title

and

EXIT

The EXIT command saves the current frame on disk in the current
file, displays a confirmation message, and returns control to
file editing level. (The EXIT command is identical to the SAVE
command.)
Format:

EXIT
CAUTION

This command saves the current frame, not the
file.
To save the file, enter an EXIT or SAVE
command at file command level when you are
finished editing.
5-11

Frame Development Tool
5.4.4

HELP

The HELP command displays a list of FDT frame commands.
Format:

HELP
Notes:

•

If you request help at the Frame Command prompt while you are
working on a text or message frame, the ACTION command is not
listed.

5.4.5

PROFILE

The PROFILE command displays a Profile form for the current
frame.
The Profile form contains data that documents the frame
and describes the operation of the frame to menu services.
This
information is not visible to the end user.
Format:

PROFILE
Notes:

•

The Profile form for a single-choice menu contains a frame
description, a global help frame pointer, the default option,
and the global action string.

•

The Profile
description,
option.

•

The Profile form for a help text frame contains a frame
description, the frame's screen location, a previous help
frame pointer, and a next help frame pointer.

•

The Profile form
description.

5.4.6

form for a help menu
contains
a
frame
a previous help frame pointer, and the default

for

message

frame

contains

frame

QUIT

The QUIT command returns control to file
5-12

command

level

without

Frame Development Tool
saving the
discarded.

current

frame.

Any

changes made to the frame are

Format:
QUIT

Note:
All four characters of the QUIT command must be entered.

5.4.7

SAVE

The SAVE command saves the current frame on disk in the current
file, displays a confirmation message, and returns control to
file editing level.
(The SAVE command _is identical to the EXIT
command.)
Format:
SAVE

CAUTION
This command saves the current frame,
not the
file.
To save the file, enter an EXIT or SAVE
command at file command level when you are
finished editing.

5.5

PROFILE, DISPLAY, AND ACTION FORMS

FDT provides access to frame descriptions by means of forms.
When you enter the ADD command to create a new frame, FDT
displays a series of forms for you to fill in.
When you enter
the MODIFY command to edit an existing frame, FDT allows you to
specify which forms you want to modify.
As shown in Figure 5-1, there are three types of forms:

5-13

PROFILE, DISPLAY, AND ACTION FORMS
•

The Profile Form

The Profile form (invoked by the PROFILE command) contains
data that describes the purpose and operation of the frame to
POSRES and to your task. This information is not visible to
the user.
•

The Display Form

The Display form (invoked by the DISPLAY command) contains
fields that correspond to the fields in the frame. It
describes how the form will appear to the user.
•

The Action Form

The Action form (invoked by the ACTION command) is for menu
frames only. It specifies a keyword, help frame pointer, and
(for single-choice menus) an action string for each option.

5-14

PROFILE, DISPLAY, AND ACTION FORMS
FORMS
ProI'ile for Single Choice Menu MAIN

Frame Description
This is the main menu for the elementary education application.

l
Global Help Frame [MENU}

Default Option f 3 I
Global Action String
[ DATABASE • ELEM

Display for Single Choice Menu MAIN

ELEMENTARY EO'JCATION APPLICATION
This application offers elementary education in seven fields of study. Select
one of the courses :isted here.

9IOLOGY

COt-!P'JTER SC I ENCE
GEOGRAPHY
GOVERN~ENT

[

HISTORY
LITERAT 1JRE
MATHE:-!A7 I CS

[ H~e a selection and press the DO key:
Action Number J for Sing:i.e Choice Menu MAIN
~escription:

GEOGRAPHY

[GEO

'"'"e [llEL?GEO]
[ GEOG0010

Option Action S'::-~r.g

MENU DEFINITION FILE
CD

...

•

I I I
MENU
- - - - - - - - ELEMENTARY EDUCATION APPLICA''!CN - - - - - - - - .

This application offers elementary education in seven flelds of :it'..:.dy.
one of the courses listed here:

;:ie:ect

BIOLOGY
COMPUTER SC I ENCE

-> CEOCRAPHY
GOVERNMENT

HISTORY
LiiERAT~RE

MATHEMATICS

Add1<;1onal Options avaUab~e

Make a selection and press the DO key:

Figure 5-1:

Forms for a Single-Choice Menu

5-15

PROFILE, DISPLAY, AND ACTION FORMS
Each form contains one or more fields.
The meaning of some
fields is clear from the field name or prompt. Other fields,
such as help frame pointers, are interrelated and are more
complex.
Some fields are optional; others are required. If you fail to
fill in a required field, FDT accepts the frame. However, when
you try to CONVERT the frame file, an error occurs and the
conversion fails.
You can use your keyboard's numeric keypad and ARROW keys to
manipulate text within a field. Figure 5-2 shows the layout of
the numeric keypad. Like other screen editors, FDT uses an
insert mode for entering text. There is no insert command. To
enter text, simply type on the main keyboard.

0 G0
HELP

~1~'ti, ..,

rDELETE-,
CURRENT
LINE

[I] ,. ~~i~o

DELETE

WORD

BOJB:g~~~TE
Doo
[ JO
r

EXIT
CURRENT

~FORM

Figure 5-2:

FDT Screen Editor Keypad

5-16

PROFILE, DISPLAY, AND ACTION FORMS
The keypad keys operate as follows:
Move the cursor forward, backward, up, or down,
within and between fields. You can use the 6, 4,
8, and 2 keys (respectively) on the numeric
keypad for the same purposes.
Displays a description of the field the cursor
currently points to. If pressed again, the HELP
key displays a description of the keypad keys.
Deletes from the cursor to the end of the line.
Deletes from the cursor to the next word.
Deletes the character the cursor is on.
Positions the cursor at
next field on the form.

the

beginning

the

Positions the cursor at the
previous field on the form.

beginning

the

Returns control to frame editing command level
unless you are filling in multiple Action forms,
in which case the next Action form for the menu
(if there is one) is displayed.

5-17

CREATING A SINGLE-CHOICE MENU
5.6

CREATING A SINGLE-CHOICE MENU

5.6.1

The Profile Form

Profile for Single Choice Menu [IDENTIFIER]
Frame Description

[

l
Global Help Frame [
Default Option [
Global Action String

[

Figure 5-3:

]
]

Profile Form for Single-Choice Menu

Field

Type

Max. Size

Purpose

Frame
Description

Optional

Six lines of
72 characters

Enter a description
of the overall
purpose and operation
of the menu. For
example, you can
document the content
and meaning of the
global action string.

Global
Help Frame

Optional

Eight alphanumeric characters

Specify the help
frame to be displayed
when the selector is
at the rest position
or if no option frame
pointer exists.

Default
option

Optional

Two digits

Specify the ordinal
number of the option
on which the selector
is to begin when the
menu is displayed. If
you leave this field
blank, the selector
begins at the rest
position.

5-18

CREATING A SINGLE-CHOICE MENU
Field

Type

Max. Size

Purpose

Global
action
string

Optional

72 characters

Specify a string that
associates some
useful data with this
menu. When the MFRAME
routine reads this
menu into memory, it
returns the global
action string to your
task, which can use
or ignore it.

5-19

CREATING A SINGLE-CHOICE MENU

5.6.2

The Display Form

Display for Single Choice Menu [IDENTIFIER]
[

TITLE TEXT

EXPLANATORY TEXT

[

OPTION DESCRIPTION

PROMPT

[

Figure 5-4:

Display Form for Single-Choice Menu

Field

Type

Max,. Size

Purpose

Title

Required

64 alphanumeric characters

Enter the title to be
displayed on the
first line of the
menu.

Explanatory text

Optional

Three lines of
72 characters

Enter text
introducing the user
to the options listed
on this menu.

Option
descriptions

Required

Twelve lines
of 64 characters

Enter the option
list. You must
specify at least one
option.

Prompt

Required

72 characters

Enter a string that
requests the user to
make a selection.

5-20

CREATING A SINGLE-CHOICE MENU
5.6.3

The Action Form

Action Number [#] for Single Choice Menu [IDENTIFIER]
Description: [OPTION DESCRIPTION]

Action Description

[

Option Keyword [
Option Help Frame

J
[

Option Action String

[

Figure 5-5:

J
J

Action Form for Single-Choice Menu

The message line at the top of the form shows the ordinal number
of the option for which action is being assigned. It also shows
the identifier of the menu on which the option is displayed.
Field

Type

Max. Size

Purpose

Action
Description

Optional

Two lines of
72 characters

Enter a description
of the overall
purpose and operation
of the option. For
example, you can
document the content
and meaning of the
option action string.

Option
keyword

Required

30 characters

Enter any contiguous
substring of the
option. This keyword
appears in bold when
the menu is displayed
in order to indicate
which characters the
user can type to
select this option.

Option
Help Frame

Optional

Eight alphanumeric characters

Specify the help
frame to be displayed
when the user presses
the HELP key while
the selector is
positioned at this
option.

5-21

CREATING A SINGLE-CHOICE MENU
Field

Type

Max. Size

Purpose

Option
action
string

Optional

72 characters

Specify a string that
associates some
useful data with this
option. When the user
selects an option,
the MENU routine
returns this string
to your task, which
can use or ignore it.

5-22

CREATING A HELP MENU
5.7

CREATING A HELP MENU

5. 7 .1

The Profile Form

Profile for Help Menu [IDENTIFIER]
Frame Description

[

l
Previous Help Frame
Default Option [

[
]

Figure 5-6:

Profile Form for Help Menu

Field

Type

Max. Size

Purpose

Frame
Description

Optional

Six lines of
72 characters

Enter a description
of the ave rall
purpose and operation
of the menu. For
example, you can
document how it fits
into the larger help
structure.

Previous
Help Frame

Optional

Eight alphanumeric characters

Specify the help
frame to be displayed
when the user presses
the PREV SCREEN key.

Default
option

Optional

Two digits

Specify the ordinal
number of the option
on which the selector
is to begin when the
menu is displayed. If
you leave this field
blank, the selector
begins at the rest
position.

5-23

CREATING A HELP MENU
5.7.2

The Display Form

Display for Help Menu [IDENTIFIER]
TITLE TEXT

[

EXPLANATORY TEXT

[

OPTION DESCRIPTION

[

PROMPT

Figure 5-7:

Display Form for Help Menu

Field

Type

Max. Size

Purpose

Title

Required

64 alphanumeric characters

Enter the title to be
displayed on the
first line of the
menu.

Explanatory text

Optional

Three lines of
72 characters

Enter text
introducing the user
to the options listed
on this menu.

Option
descriptions

Required

Twelve lines
of 64 characters

Enter the option
list. You must
specify at least one
option.

Prompt

Required

72 characters

Enter a string that
requests the user to
make a selection.

5-24

CREATING A HELP MENU
5. 7 .3

The Action Form

Action Number [#] for Help Menu [IDENTIFIER]
Description: [OPTION DESCRIPTION]

Action Description

[

Option Keyword [
Option Help Frame

Figure 5-8:

J
]

[

]

Action Form for Help Menu

Field

Type

Max. Size

Purpose

Action
Description

Optional

Two lines of
72 characters

Enter a description
of the overall
purpose and operation
of the option. For
example, you can
document whether the
option help frame is
a menu or a text
frame.

Option
keyword

Required

30 characters

Enter any contiguous
substring of the
option. This keyword
appears in bold when
the menu is displayed
in order to indicate
which characters the
user can type to
select this option.

Option
Help Frame

Required

Eight alphanumeric characters

Specify the name of
the help menu or text
frame to be displayed
when the user selects
this option.

5-25

CREATING A HELP TEXT FRAME
5.8

CREATING A HELP TEXT FRAME

5.8.1

The Profile Form

Profile for Help Text [IDENTIFIER]
Frame Description

[

]
Frame Location [FULL]
Previous Help Frame [
Next Help Frame [
]

]

Figure 5-9:

Profile Form for Help Text Frame

Field

Type

Max. Size

Purpose

Frame
Description

Optional

Six lines of
72 characters

Enter a description
of the overall
content of the frame.

Frame
Location

Required

Specific
options

Specify "FULL",
"TOP", or "BOTTOM",
according to where
you want this frame
to appear. A full
frame has 16 lines of
text; a top or bottom
frame has 8 lines.
The default is
"FULL". To change it,
position the cursor
on the "F" and press
the DELETE WORD key
on the keypad.

Previous
Help Frame

Optional

Eight alphanumeric characters

Specify the help
frame to be displayed
when the user presses
the PREV SCREEN key.

Next Help
Frame

Optional

Eight alphanumeric characters

Specify the help
frame to be displayed
when the user presses
the NEXT SCREEN key.

5-26

CREATING A HELP TEXT FRAME
5.8.2

The Display Form

Display for Help Text [IDENTIFIER]
[

TITLE TEXT

......,

Help Text

Figure 5-10:

Display Form for Help Text Frame

Full screen and top or bottom half help text frames have
different Display forms representing the difference in the number
of lines in the frame. However, they all share the same fields,
and the full screen help text frame is representative.
Field

Type

Max. Size

Purpose

Title

Required

64 alphanumeric characters

Enter the title to be
displayed on the
first line of the
frame.

Help text

Required

16 lines of 72
characters

Enter at least one
line of text that
provides help on some
aspect of your
application.

5-27

CREATING A MESSAGE TEXT FRAME
5.9

CREATING A MESSAGE TEXT FRAME

5.9.1

The Profile Form

Profile for Message [IDENTIFIER]
Frame Description

Figure 5-11:

Profile Form for Message Frame

Field

Type

Max. Size

Purpose

Frame
description

Optional

17 lines of 72
characters

Enter text that
documents the
contents and purpose
of the message.

5.9.2

The Display Form

Message text frames are displayed with no border or prompt.
The
Display form for this type of frame is simply a blank screen with
the usual message line at the top identifying the current frame.
Field

Type

Max. Size

Purpose

Message
text

Required

21 lines of 79
characters

Enter the message
text. You must enter
at least one line.

5-28

RESOLVING ERRORS

5.10

RESOLVING ERRORS

All FDT user errors produce a short beep from the keyboard.
For
example, while you are filling in forms, if you press a key that
is not on the FDT keypad or attempt to type over field
boundaries, the keyboard beeps and the key action is ignored.
Errors other than the example given above produce a descriptive
error message following the keyboard beep.
FDT Error messages
are described in Appendix B.
Certain invalid keystrokes disrupt the FDT screen display.
For
example, a line feed entered while an FDT form is displayed
scrolls the screen upward. Also, a backspace typed to the File
or Frame Command prompt allows typing over the prompt, causing
valid commands typed at this point to be rejected.
If you enter
an invalid keystroke that alters a form display, type CTRL/W to
refresh the screen and continue.
If you enter an invalid
keystroke that alters a File or Frame Command prompt, enter valid
commands until one is accepted.

5.11

SAMPLE TERMINAL SESSION

The following is a sample of a terminal session using the Frame
Development Tool on an RSX-11M/M-PLUS system.
It is recommended
that you use the single-choice menu shown in Figure 5-1 to fill
in the forms.

$ RUN $FDT
FDT starts and prompts for a
creates a new file.

filename.

this

example,

FDT

Filename: SAMPLE
FDT prompts for the type of frames to be stored in the file.
Create (H)elp,

(M)essage, or (S)ingle-choice menu file?

The file SAMPLE.DAT will
prompts for a file command.

contain

single-choice

menus.

FDT

File Command: ADD MAIN
The ADD command creates a new frame called MAIN.
Because it is a
new frame,
FDT displays a Profile form. When you finish the
form, press the ENTER key.
MAIN is now the current frame.
FDT
prompts for a frame command.

5-29

SAMPLE TERMINAL SESSION
Frame Command: DISPLAY
The DISPLAY command creates a Display form for MAIN.
When you
finish the form, press the ENTER key. FDT prompts for another
frame command.
Frame Command: ACTION
The ACTION command creates Action forms for each option on the
display form for MAIN. When you finish an Action form, press the
ENTER key.
When all the Action forms are done, FDT prompts for
another frame command.
Suppose that you want to correct a
mistake on the Action form for the third option.
Frame Command: ACTION 3
FDT displays the action form for option three
with
the
information you entered before. When you finish the form, press
the ENTER key. FDT prompts for another frame command.
Frame Command: SAVE
MAIN is saved on disk, and a confirming
FDT prompts for a file command.

message

displayed.

File Command: SAVE
FDT saves the file SAMPLE.DAT, which contains MAIN, on
returns control to host system command level.

disk

and

Suppose that you decide to modify the Profile form for MAIN.
$ RUN $FDT

Filename: SAMPLE
File Command: MODIFY MAIN
FDT extracts MAIN, displays a message confirming that MAIN
available for modification, and prompts for a frame command.

Frame Command: PROFILE
The PROFILE command invokes the Profile form for MAIN, the
current frame.
The information you entered before is still
FDT
there. When you finish the form, press the ENTER key.
prompts for a frame command.
Frame Command: SAVE

5-30

SAMPLE TERMINAL SESSION
FDT saves MAIN with the new Profile form and prompts for
command.

file

File Command: QUIT
FDT discards all changes made to the file SAMPLE.DAT (including
the new Profile form) and returns control to host system command
level.

5-31

CHAPTER 6
INSTALLATION COMMAND LANGUAGE

Every application requires an installation command file.
This
file, whose filename contains either a .INB or .INS extension, is
important for creating application diskettes and for installing,
running, and removing an application.
The system uses an installation file in the following ways:
•

Building Application Diskettes

When you start the Application Diskette Builder (ADB) to
build the distribution diskettes for your application, ADB
reads the installation file to identify the files to copy to
the application diskette(s).
•

Copying Application to Public Library

The system manager on a P/OS system can copy applications
into the Public Library. The installation file directs the
transfer of files from application diskette to the Public
Library on hard disk.
•

Installing an Application

When the user installs your application, P/OS reads the
installation file to identify the files to copy to the hard
disk at installation time. If you have tasks that should
execute during the installation process, they can be run by
the EXECUTE command in the installation file.
•

Running an Application

When a user runs your
application,
P/OS
reads
the
installation file to identify task images (it adds the names
to its list of executable tasks), to open any Menu, Message,
and Help frame files (specified in ASSIGN commands), and to
start the first application task.

6-1

Installation Command Language

•

Removing an Application
When the user removes your application,
P/OS reads the
installation file to identify the files to delete from the
hard disk.

•

Deleting Application from Public Library
When the system manager deletes applications from the Public
Library,
the system reads the installation file to determine
which application files to delete from the Library.

6.1

INSTALLATION COMMAND FILE FORMAT

An installation command file is an ordinary text file that you
can create with any editor.
Some Tool Kit languages provide a
facility for creating a general-purpose installation file.
Note
the following requirements for command files:
•

Command lines can be up to 132 characters long.

•

There is one command per line.

•

Commands must appear in a prescribed order.

The format of an installation file is
Boldface indicates a mandatory command.

NOTES

Figure 6-1:

shown

Figure

COMMAND LINES
! A sample install file.
NAME "name"
FILE filespec/option1/option2
MOUNT volume
EXECUTE taskspec/option1/option2/option3
INSTALL f ilespec/option1/option2/NOREMOVE/FIX
ASSIGN MESSAGE filespec/option
ASSIGN MENU f ilespec/option
ASSIGN HELP filespec/option frameid
ASSIGN LOGICAL name "equiv"
RUN taskname

Installation Command File Format

6-2

6-1.

INSTALLATION COMMAND FILE FORMAT

Notes to Figure 6-1
1.

The MOUNT command is required for
applications.
(See Section 6.11.)

multiple-diskette

ADB and Fast Install generate a warning message if you
omit the RUN command. Although P/OS does not require the
RUN command to be present, most applications must use it.

The order of the FILE commands determines the order in which
files are copied from the application diskettes or Public
Library. The order of the INSTALL commands determines the order
in which task image files are processed when an application is
started.

6.1.1

Using .INB and .INS Files

For applications
.INB extension
your application
in P/OS V3.0 and

that will run on P/OS V3.0 you should use the
on your installation filename.
This will allow
to take advantage of additional features present
later versions.

To run on V2.0A and earlier P/OS systems, your application must
supply a .INS file.
These systems do not recognize .INB files as
installation files.
You can supply both an .INB and .INS file for any application.
In general, we recommend that you supply both forms of the
installation file so that your application is compatible with the
maximum number of systems.
The following are valid only in .INB files:
•

ASSIGN MESSAGE command

•

/USR, /NTW, and /CLS qualifiers on the EXECUTE command

/USER, /NETWORK,
specification

•

/TASK=name qualifier on the INSTALL command

6.1.2

and

/CLUSTER

qualifiers

any

file

Using /USER, /NETWORK, and /CLUSTER in Your .INB File

You use the /USER, /NETWORK,
and /CLUSTER qualifiers on any
command whose format includes a file specification.
These

6-3

INSTALLATION COMMAND FILE FORMAT
qualifiers tell P/OS where on the system each application file
normally resides; thus they allow you to control access to the
files.
A description of each qualifier follows.:
•

/USER--Separate file available for each user

Application files with the /USER qualifier are available
separately to each user who installs the application. Such
files cannot be shared among different users. An example of
a
/USER
file is a file containing individual set-up
information.
On P/OS V2.0A or
earlier
systems,
all
application files were treated as /USER files.
Files given the /USER qualifier always reside on the device
SYSDISK:, in either a dynamically-created directory named
[ZZAPnnnnn] or in the directory specifed in the installation
command.
During run time, your application can refer to any /USER
files either by using the logical APPL$USER: in conjunction
with the filename and extension (preferred), or by using the
complete file specification. However, for compatibility with
P/OS V2.0A and earlier systems, you must instead translate
the logical APPL$DIR and use the resulting device and
directory in your file specification.
Sample references to a /USER file:
APPL$USER:SETUP.DAT
SYSDISK:[MYAPPLDIR]SETUP.DAT
•

/NETWORK--file can be shared among users

Application files with the /NETWORK qualifier can be shared
among users executing the same application. This saves disk
space, since the system can use a single copy of the file for
all users executing your application on a particular system.
Most read-only files are good candidates for the /NETWORK
qualifier.
Also, a read-write database could be a /NETWORK
file, provided that your application properly manages any
concurrent accesses.
Files having the /NETWORK qualifier reside on the disk
specified by the system manager when they are copied from
places
/NETWORK
files
in
a
diskette.
The
system
directory
of
the
form
dynamically-created
[ZZAPnnnnn.ZZPUBAP].

6-4

INSTALLATION COMMAND FILE FORMAT
During run time, your application must refer to any /NETWORK
files by using the logical APPL$NETWORK: in conjunction with
the filename and extension.
Sample reference to a /NETWORK file:
APPL$NETWORK:DATABASE.DAT
•

/CLUSTER--file can be shared among different applications
Application files with the /CLUSTER qualifier caf1 be shared
among users executing different applications. Only a Server
manager can install /CLUSTER files on a system.
As
with
/NETWORK
files,
a
read-only
file
or
a
properly-managed read-write database is a good candidate for
the /CLUSTER qualifier. A callable editor task would be a
very good candidate.
Files given the /CLUSTER qualifier reside on LBOOO:, the boot
device of the Server that down-line loaded the system on
which your application is running.
Usually, you specify the directory in the installation
command. However, if you omit the directory, P/OS places the
file in a dynamically-created directory
of
the
form
[ZZCLnnnnn].
In general, we strongly recommend that you
supply the directory, since your application cannot determine
the dynamically-created name at run time. See Section 3.1
for an exception that applies to applications using DECnet.
During run time, your application must refer to any /CLUSTER
files by using the actual file specification. No logical
names are available for /CLUSTER files.
Sample reference to a /CLUSTER file:
LBOOO:[ZZPRQDCL]PIP.TSK

Table 6-1 summarizes the three qualifiers.

6-5

INSTALLATION COMMAND FILE FORMAT

Table 6-1:

Summary of /USER, /NETWORK, and /CLUSTER Qualifiers

Qualifier

Location

Logical Name

/USER

SYSDISK:[ZZAPnnnnn]
or
SYSDISK:[directory]

APPL$USER:

•

SYSDISK: points to the
user home.

•

nnnnn is created
dynamically by the
system.

•

directory is specified in
the installation command.

/NETWORK

/CLUSTER

device:[ZZPAnnnnn.ZZPUBAP]

•

device is the device
chosen by the workstation
or Server manager.

•

nnnnn is created
dynamically by the
system.

LBOOO:[directory]
or
LBOOO:[ZZCLnnnnn]

•

LBOOO: points to the
system library device.

•

directory is

•

nnnnn is created
dynamically by the
system.

specif~ed in
the installation command.

6-6

APPL$NETWORK:

None

INSTALLATION FILE ERRORS
6.2

INSTALLATION FILE ERRORS

Errors resulting from an incorrect installation command file
documented as follows:

are

•

Errors returned during operation of ADB or Fast
documented in Appendix A.

are

•

Errors returned to the end user when installing, removing, or
transferring your application to or from the Public Library
are documented in Appendix E.

6-7

Install

ASSIGN HELP
6.3

ASSIGN HELP

command assigns a filename as the default help file for your
application.
If you have a default help file, you need not call
the Open Help File service routine at run time.

Thi~

This command is used only when your application is started by the
user.
Format:
ASSIGN HELP f ilespec/option f rameid

filespec

Specifies the name of a help frame file.

option

Is optional and can only be specified in .INB files.
It can be one of /USER, /NETWORK, or /CLUSTER. The
qualifier you specify indicates where the help frame
file resides. See Section 6.1.2 for details.

f rameid

Is a string of up to eight
the default help frame.

characters

that

specifies

Notes:

•

You must use the same f ilespec that you used in the the
command.

•

You can have only one ASSIGN HELP
file.

•

The ASSIGN HELP command is optional.
However, we strongly
recommend that you supply it in your installation command
file.
If you do not supply an ASSIGN HELP command, POSRES
does not provide any default help file.

•

If you have multiple help files, always use ASSIGN HELP to
specify your primary help file as the default. In an HFILE
call to open a different help file,
specify only the file
name
of
the other help file, not the complete file
specification. POSRES obtains any missing fields of the file
specification from the value given in ASSIGN HELP.

6-8

command

per

FILE

installation

ASSIGN LOGICAL

6.4

ASSIGN LOGICAL

This command defines a logical name at run time.
(See the Tool
Kit User's Guide and P/OS System Reference Manual for information
about logical names.) This command is used only when your
application is started by the user.
Format:
ASSIGN LOGICAL name "equiv"

name

Is a string that specifies the logical name that is
be defined.

equiv

Is a string that specifies the equivalence name.

Notes:

•

The ASSIGN LOGICAL command is optional.

•

Multiple ASSIGN LOGICAL commands can be used.

6-9

ASSIGN MENU

6.5

ASSIGN MENU

This command assigns a file as the default menu file for your
application.
If you have a default menu file, you need not call
the Open Menu File (MFILE) service routine at run time.
This
command is used only when your application is started by the
user.
Format:
ASSIGN MENU f ilespec/option

filespec

Specifies a menu frame file.

option

Is optional and can only be specified in .INB files.
It can be one of /USER, /NETWORK, or /CLUSTER. The
qualifier you specify indicates where the menu file
resides.
See Section 6.1.2 for details.

Notes:
•

You must use the same f ilespec that you used in the the
command.

•

You can have only one ASSIGN MENU
file.

•

The ASSIGN MENU command is optional.
However, we strongly
recommend that you supply it in your installation command
file.
If you do not supply an ASSIGN MENU command,
POSRES
does not provide any default menu file.

•

If you have multiple menu files, always use ASSIGN MENU to
specify your primary menu file as the default.
In an MFILE
call to open a different menu file,
specify only the file
name
of
the other menu file,
not the complete file
specification. POSRES obtains any missing fields of the file
specification from the value given in ASSIGN MENU.

6-10

command

per

FILE

installation

ASSIGN MESSAGE (.INB FILE ONLY)

6.6

ASSIGN MESSAGE (.INB FILE ONLY)

This command assigns a file as the default message file for your
application.
This command is used only when your application is
started by the user.
Format:
ASSIGN MESSAGE f ilespec/option

filespec

Specifies a message frame file.

option

Is optional and can only be specified in .INB files.
It can be one of /USER, /NETWORK, or /CLUSTER. The
qualifier you specify indicates where the message file
resides.
See Section 6.1.2 for details.

Notes:

•

You must use the same f ilespec that you used in the the
command.

•

You can have only one ASSIGN MESSAGE command per installation
file.

•

This command is valid only for P/OS V3.0 or later versions.

•

You can have only one ASSIGN MESSAGE command per installation
file.

•

The ASSIGN MESSAGE command is optional. However, we strongly
recommend that you supply it in your installation command
file.
If you do not supply an ASSIGN MESSAGE command, POSRES
uses
APPL$DIR
as
the
default
device and directory
specification for all message file operations.

•

If you have multiple message files, always use ASSIGN MESSAGE
to specify your primary message file as the default.
In an
RDMSG call to open a different message file, specify only the
file name of the other message file, not the complete file
specification. POSRES obtains any missing fields of the file
specification from the value given in ASSIGN MESSAGE.

6-11

FILE

COMMENT
6.7

COMMENT

An exclamation point (!) indicates that the line is a comment.
The exclamation point must be the first nonblank character on the
line.
Format:

text

6.8

EXECUTE

This command causes a
following operations:

specified

task

execute

•

Install application

•

Remove application

•

Copy application to the Public Library

•

Delete application from the Public Library

If the task exits with status greater than one,
copy operation aborts.

the

during

the

install

P/OS acts on the EXECUTE command as soon as it is read from the
install~tion
file.
Thus, the position of the EXECUTE command
relative to FILE commands is significant, as explained below.
Format:
EXECUTE taskspec/option1/option2/option3

taskspec

Is the task image file in one of
for both .INB and .INS files:

the

following

forms

[directory]file.TSK
APPL$DST:file.TSK
Additionally, the following form of taskspec is allowed
for .INB files:
file.TSK
file

Is the filename for the task image to be executed.
6-12

EXECUTE
directory Is the directory
executed.

containing

the

task

image

APPL$DST

Points to the destination device:[directory] for
being transferred.

/optionl

Is required.

/option2

files

It is one of the following:

/INS

Executes the specified
task
either
during
application installation, or when the workstation
or Server manager is copying application files
into a shared area (such as the Public Library or
LBOOO:).
This command must follow the FILE
command that copies the specified task image to
the hard disk.
It can precede other
FILE
commands
in
order
to avoid copying files
needlessly in the event that the task exits
unsuccessfully.

/REM

Executes the specified task
at
application
removal,
or when the workstation or Server
manager is deleting application files from a
shared area (such as the Public Library or
LBOOO:).
This
command
must
precede
the
FILE/DELETE command that refers to the same task
image file.

Is optional is and allowed only for .INB files.
This
option further specifies when the task should be
executed.
Omitting option2 executes the task as follows:

/USR

•

During installation (you have also specified
the /INS qualifier): The system executes the
task when copying /USER files from
the
application diskette into APPL$USER:.

•

During removal (you have also specified the
/REM qualifier):
The system executes the
task when deleting from APPL$USER:
those
/USER
files
originally
copied
from
application diskette.

as option2 executes the task as follows:
•

During installation (you have also specified
the /INS qualifier): The syst~m executes the
task when copying /USER files from the Public
Library into APPL$USER:.

6-13

EXECUTE
•

/NTW

During removal (you have also specified the
/REM qualifier):
The system executes the
task when deleting from APPL$USER:
those
/USER files originally copied from the Public
Library.

as option2 executes the task as follows:
•

When copying (you have also specified the
/INS qualifier):
The system executes the
task when copying
/NETWORK
files
from
application diskette to APPL$NETWORK:.

deleting (you have
• When
/REM qualifier):
The

task when deleting
APPL$NETWORK:.
/CLS

also specified the
system executes the
/NETWORK
files
from

as option2 executes the task as follows:
•

When copying (you have also specified the
/INS qualifier):
The system executes the
task when copying /CLUSTER files from the
application diskette onto LBOOO:

deleting (you have
• When
/REM qualifier):
The

task when
LBOOO:.
/option3

deleting

also specified the
system executes the
/CLUSTER
files
from

is optional and is allowed only for .INB files.
This
option specifies the location of the task image, if you
did not specify it in the taskspec.
If present,
option3 is one of:
/USER

Specifies that the task image is found in
APPL$USER:.
If the corresponding FILE line
has a /USER qualifier,
the EXECUTE line
should also have a /USER qualifier.

/NETWORK

Specifies that the task image is found in
APPL$NETWORK:.
If the corresponding FILE
line has a /NETWORK qualifier,
the EXECUTE
line should also have a /NETWORK qualifier.

/CLUSTER

Specifies that the task image is found in the
system library,
LBO:.
If the corresponding
6-14

EXECUTE
FILE line has a /CLUSTER qualifier,
the
EXECUTE line should also have a /CLUSTER
qualifier.
Notes on Combining Qualifiers:

In most cases, combinations of the EXECUTE qualifiers option2 and
option3 are straightforward. The following examples are typical:
EXECUTE ATASK.TSK/INS/USR/USER

This
command
executes
ATASK.TSK
during
application
installation (see /INS), at the point when the system is
copying /USER files from the Public Library (see /USR)
into
APPL$USER:.
The system expects to find ATASK.TSK in
APPL$USER:--that is, the corresponding FILE command precedes
the EXECUTE command.
(See /USER.)
EXECUTE XTASK.TSK/INS/USER

This
command
executes
XTASK.TSK
during
application
installation (see /INS),
at the point when the system is
copying /USER files from the application diskette
(no
option2 qualifier present)
into APPL$USER:.
The system
expects to find ATASK.TSK in APPL$USER:.
(See /USER.)
EXECUTE BTASK.TSK/REM/NTW/NETWORK

This command executes BTASK.TSK during application removal
(see /REM),
at the point when the system is removing
/NETWORK files (see /NTW) from APPL$NETWORK:.
The system
expects to find ATASK.TSK in APPL$NETWORK:.
(See /NETWORK.)
The following examples are somewhat more complicated.
EXECUTE CTASK.TSK/INS/USR/NETWORK

This
command
executes
CTASK.TSK
during
application
installation (see /INS),
at the point when the system is
copying /USER files from the Public Library (see /USR)
into
APPL$USER:.
The system expects to find CTASK.TSK in
APPL$NETWORK:.
(See /NETWORK.) The file CTASK.TSK is a
shared component that the workstation or Server manager has
previously copied to APPL$NETWORK:.
EXECUTE [ZZWHA]DTASK.TSK/INS/USR/CLUSTER

This
command
executes
DTASK.TSK
during
application
installation (see /INS),
at the point when the system is
copying /USER files from the Public Library (see /USR)
into
6-15

EXECUTE
APPL$USER:.
The system expects to find DTASK.TSK on LBOOO:
(see /CLUSTER). The file DTASK.TSK is a shared component
that the Server manager has previously copied to LBOOO:.
Examples showing invalid
follow.

combinations

option2

and

option3

EXECUTE [SOMEDIR]ETASK.TSK/INS/USR/NETWORK

INVALID COMMAND: The /NETWORK file ETASK.TSK cannot have an
explicit directory.
EXECUTE (ZZSYS]FTASK.TSK/INS/CLS/USER

INVALID COMMAND: The desire is to execute the task when the
Server manager is copying /CLUSTER files from diskette onto
LBOOO:.
(See /CLS.) However, the /USER qualifier tells the
system to locate the file in the user-specific application
directory, which does not exist at the time the Server
manager is copying /CLUSTER files.
EXECUTE (ZZSYS]GTASK.TSK/INS/CLS/NETWORK

INVALID COMMAND: This example is similar to the previous
one. The /NETWORK area, in which the system will search for
GTASK.TSK, does not exist when the Server manager is copying
/CLUSTER files from diskette onto LBOOO:.

General Notes:
•

The EXECUTE command is not supported on P/OS Hard Disk
to Version 2.0.

•

The qualifiers /option2 and /option3 are supported
files only.

•

To execute a task whenever the installation process copies
/USER files
into APPL$USER:,
you must provide two EXECUTE
commands: one that specifies the /USR qualifier as option2,
and one that omits option2 altogether.

•

The task referred to by taskspec in the EXECUTE command
cannot be linked with libraries that must be installed during
application installation.
This is because all
EXECUTE
commands
must
precede
all
INSTALL
commands in the
installation file.
Consequently, tasks written in high-level
languages, which normally require installation of a run-time
library, cannot be executed in the installation file.

6-16

for

prior
.INB

EXECUTE

NOTE
A solution is to execute a task written in
MACR0-11 that install.s any required tasks or
libraries, and then spawns
other
tasks
written in high-level languages.
•

Your executing task can determine the phase of installation
or removal by issuing a GMCR$ directive (documented in the
P/OS System Reference Manual). This directive returns the
option!
and option2 qualifiers present on the EXECUTE
command. Table 6-2 describes the phases associated with
different combinations of the qualifiers.

•

You can place an EXECUTE command anywhere
FILE command can be placed.

•

APPL$DST points to the destination
files
being
transferred
during
installation.

•

At installation, copying, or removal time the logical names
APPL$DIR, APPL$USER:, and APPL$NETWORK:
are not defined for
your application.

•

The logical
name
APPL$SRC:
points
to
the
source
device:[directory] of the most recent file copied during the
current phase of installation.

Table 6-2:

that

MOUNT

device:[directory]
for
the current phase of

EXECUTE Qualifiers and Phases of Installation/Removal

option1/option2

Installation or Removal Phase

/INS

End user is installing from diskette

/INS/USR

End user is installing from Public Library

/INS/NTW

System manager is installing the "entire
application" or "application-specific
components" from diskette into Public Library

/INS/CLS

System manager is installing "entire
application" or "system-wide components" from
diskette onto LBOOO:.

6-17

EXECUTE
option1/option2

Installation or Removal Phase

/REM

End user is removing application

/REM/USR

End user is removing application

/REM/NTW

System manager is removing application from
Public Library

/REM/CLS

System manager is removing application from
Public Library

6-18

FILE

6.9

FILE

The FILE command specifies the name of an application file.
You
must supply a FILE command for each file that is to be copied to
your diskettes during application building and that is to be
copied to or removed from the hard disk during application
installation or removal.
This command is used by ADB when your application diskettes are
built, and by P/OS when your application is installed or removed.
Format:
FILE f ilespec/option1/option2
filespec

Is the file specification in
both .INB and .INS files:

the

following

form

for

file.TSK
[directory]file.TSK
During the execution of ADB, the file specification is
used to locate the file so that it can be copied to the
diskette. The details of this search for the file
to
be copied are described in Chapter 1.
The file is copied to the diskette in the application
directory,
or in the directory that is named in the
file specification. A directory is created on the
diskette,
if it does not already exist. Thus, FILE
[ABC]FOO.DAT causes the file to be placed in
(ABC]
on
the diskette.
During the installation of the application,
the FILE
command is used to determine where to place the file
that is copied from the diskette.
/option1

Is required.

It must be one of the following:

/KEEP

Prevents the file
(and
directory)
from
being
application is removed.

/DELETE

Allows the
file
(and
the
application
directory,
if there are no files remaining)
to be deleted when the
application
is
removed.

6-19

the
application
deleted when the

FILE
/option2

Is optional and allowed only for
.INB files.
It
determines where the file is to be placed. Option2
must be one of the qualifiers /USER, /NETWORK,
or
/CLUSTER.
The default is /USER, but you should always
explicitly specify the qualifier.
See Section 6.1.2
for details.

Note:

Do not include a FILE command for the installation file itself.

6-20

INSTALL

6.10

INSTALL

This command specifies each task image or library to be installed
(placed in the installed task list) at run time. This command is
used only by P/OS when the user selects your application to be
run.
Format:
INSTALL f ilespec/option1/option2/NOREMOVE/FIX

filespec

Is the file specification in
both .INB and .INS files:

the

following

form

for

[directory]file.TSK
file.TSK
/option!

option2

Is required.

It must be one of the following strings:
a

read-only

/LIBRARY

Specifies that the
resident library.

file

/COMMON

Specifies that the
resident library.

file

read-write

/TASK

Specifies that the file
task image.

executable

/TASK=name

Is valid for .INB files only.
It specifies
that the file is an executable task image,
and the name of the task image should be
replaced with "name".
The assigned name
must be a one- to six-character string of
characters in the Radix-50 character set.

Is optional and is allowed only in .INB files.
It can
be one of /USER, /NETWORK, or /CLUSTER. The qualifier
you specify indicates where the task image or library
to be installed resides. The default is /USER, but you
should always explicitly specify this qualifier.
See
Section 6.1.2 for details.

/NOREMOVE Can be specified only with the /TASK option.
It
specifies that the task will not be aborted or removed
when the application exits (or is aborted).
/FIX

Can be specified only with the /TASK option.
It
specifies that the task is to be fixed in memory during
execution (not swapped).
6-21

INSTALL

Notes:
•

The maximum number of
installation file is 31.

INSTALL

commands

allowed

•

All INSTALL commands with /LIBRARY and /COMMON options
precede any INSTALL command with a /TASK option.

must

ensure
that
a
/NOREMOVE option can be used to
• The
noninteractive background task, such as a file transfer, is
not aborted on request.
Use care with the /NOREMOVE option.
The task remains
installed
after your application terminates.
When any
application starts up, if it attempts to install a task with
the same name as the task that you left installed, the new
install command is ignored provided the INSTALL command has a
/NOREMOVE option.
This is convenient for
your
application,
since
its
installation file has such an option on the INSTALL line.
But if another application happens to use the same task name,
and its INSTALL does not use the /NOREMOVE option (the normal
case), the INSTALL command fails and the other application
cannot be run.
Once you install a task with /NOREMOVE, it remains installed
(it can be checkpointed if active) until another task
explictly removes it (using the PRO/Tool Kit DCL REMOVE
command, for example), or until the system is powered down.
For more information about installing tasks,
refer
PROTSK routine in the P/OS System Reference Manual.

6-22

the

MOUNT
6.11

MOUNT

This command specifies the name of the next volume in a multiplediskette application.
When you are preparing your distribution diskettes, the MOUNT
command signals ADB to prompt you to insert a new diskette, and
causes ADB to copy subsequent files to the new volume.
When the user installs the application from your distribution
kit, the MOUNT command specifies when the user should be prompted
to insert the next diskette for installation to continue.
Format:
MOUNT volume

volume

Is a string of up to 12 characters
volume name (without a colon).

that

specifies

Notes:

•

The MOUNT command is optional for
entirely on one diskette.

appiications

•

No MOUNT command is required for
multiple-diskette application.

the

6-23

first

that

reside

diskette

NAME

6.12

NAME

This command specifies the application name seen by the user when
the application is installed.
P/OS places this name (or a
replacement name supplied by the user) on a menu.
Format:
NAMB "name"

name

Is a string of up to 40 characters that identifies your
application.

Notes:

•

You must supply exactly one
file.

•

You can use single or double quotes to delimit the string.

NAME

6-24

command

per

installation

RUN
6.13

RUN

This command specifies the name of the first task to
run time.

execute

is a string of up to six characters that specifies
name of an installed task.

the

Format:
RUN taskname

taskname
Notes:

•

You can include no more than one RUN command per installation
file.

•

The task name must be identical to the name specified in the
TASK option in your PAB command file, or in the /TASK=name
option. (If you did not use a TASK option when you built the
application, the task name defaulted to the first six
characters of the name of the task image file.)

6-25

IMPROVING APPLICATION PERFORMANCE

6.14

IMPROVING APPLICATION PERFORMANCE

To minimize the disk seek time
start-up process,
follow these
installation file:

and enhance the application
guidelines when creating an

•

Place FILE commands that have corresponding INSTALL commands
before any other FILE commands. Arrange the INSTALL commands
in the same order as their corresponding FILE commands.
INSTALL commands with the /COMMON and /LIBRARY options must
appear before INSTALL commands with the /TASK option.

•

Wherever possible, group FILE commands and INSTALL commands
by directory.
This will minimize seek time for retrieving
directory information.

6.15

REQUIRED COMMANDS FOR APPLICATIONS

Table 6-2 shows command lines that you might need to include in
your installation command file, depending on other software that
your application uses.
Note the following:
•

For .INS files, omit the /CLUSTER qualifier.

•

Applications do not need FILE or INSTALL commands for
PRO/FMS-11, PRO/GIDIS, POSRES, PRO/Communications, RMSRES, or
the print utility.

6-26

REQUIRED COMMANDS FOR APPLICATIONS

Table 6-3:

Required Commands

If Application Uses:

Installation File (.INB) Must Include:

BASIC-PLUS-2

INSTALL [ZZSYS]PBFSML.TSK/LIBRARY/CLUSTER

COBOL-81

INSTALL [ZZSYS]C81LIB.TSK/LIBRARY/CLUSTER

DIBOL

INSTALL [ZZSYS]DBLRES.TSK/LIBRARY/CLUSTER

FORTRAN-77

INSTALL [ZZSYS]PROF77.TSK/LIBRARY/CLUSTER

PASCAL

INSTALL [ZZSYS]PASRES.TSK/LIBRARY/CLUSTER

CET

INSTALL [ZZSYS]PASRES.TSK/LIBRARY/CLUSTER
INSTALL [ZZSYS]CET.TSK/TASK/CLUSTER

PRO/SORT

INSTALL [ZZSYS]PASRES.TSK/LIBRARY/CLUSTER
INSTALL [ZZSYS]PROSORT.TSK/TASK/CLUSTER

6-27

CHAPTER 7
MACR0-11 ASSEMBLER (PMA)

Professional Tool Kit MACR0-11 (PMA) is the PDP-11 relocatable
assembly language processor.
Refer to the PDP-11 MACR0-11
Language Reference Manual for detailed information about PMA.

7.1

INVOKING PMA ON THE PRO/TOOL KIT

To invoke PMA on a Professional running the PRO/Tool Kit, type:
$ MACRO

See the description of the MACRO
Command Lanuage and Utilities
command.

command in the PRO/Tool Kit
Manual for details on the MACRO

You can also invoke PMA on
following command in DCL:

PRO/Tool

the

Kit

entering

the

$ RUN $PMA

You receive the PMA> prompt, indicating that you are in the PMA
environment.
See the PDP-11 MACR0-11 Language Reference Manual
for command line format.

7.2

INVOKING PMA ON RSX-11M/M-PLUS

If PMA is installed on your system as " ... PMA" and your terminal
Command Language Interpreter (CLI) is MCR, type the following
command:

> PMA command
where "command" is a command string.
See the PDP-11
Language Reference Manual for command line format.
7-1

MACR0-11

INVOKING PMA ON RSX-11M/M-PLUS
If PMA is installed on your system as " ... PMA" and your
CLI is DCL, type the following command:

terminal

$ MACRO

See the RSX-11M/M-PLUS Command
information on the MACRO command.

Language

Manual

for

further

If PMA is not an installed task (whether your terminal CL! is MCR
or DCL), type:
$ RUN $PMA

You receive the PMA> prompt, indicating that you are in the PMA
environment.
See the PDP-11 MACR0-11 Language Reference Manual
for command line format.

7.3

INVOKING PMA ON VAX/VMS

For convenience, edit your
following symbol definit~on:
$ PMA

file

and

insert

the

:== MCR PMA

Once the symbol is defined, you can invoke PMA by typing:
$ PMA command

where "command" is a command string.
See the PDP-11
Language Reference Manual for command line format.

7-2

MACR0-11

CHAPTER 8
POSRES USER INTERFACE LIBRARY ROUTINES

This chapter describes the routines provided by POSRES, the
User Interface Library.

P/OS

8.1

NOTES ON USING POSRES ROUTINES

•

You can call POSRES routines from MACR0-11 or from high-level
languages.
POSRES
uses
the
PDP-11 calling sequence
convention, which is described in the Tool Kit User's Guide.
POSRES preserves the stack pointer (SP); it does not preserve
any other registers.

•

Tasks that use POSRES must include some specific information
in their PAB files, as described in the Tool Kit User's
Guide.

•

All POSRES routines accept a two-o/ord integer parameter named
"status".
The values returned in the status block vary
according to the routine called and are listed in Appendix C.

•

Some POSRES routine parameters
specify
values
(input
parameters), others return values (output parameters), and
some do both. Output parameters must be variables.
Input
parameters, however, can be variables, constants, or constant
expressions, depending on your language.
If it does not
support constant expressions as actual parameters, read
"expression" as "constant."

•

Several POSRES routines accept parameters consisting of
variable-length character (byte) string buffers. All string
buffers are accompanied by an integer value that specifies
the length of the buffer. Because these values mean the same
thing, they are all named "buflen" and directly follow the
buffer parameter.

8-1

NOTES ON USING POSRES ROUTINES
•

String buffers that return values are accompanied by an extra
parameter that returns an integer value representing the
actual length of the string returned in the buffer.
Because
these integer variables all mean the same thing, they are all
named "strlen" and directly follow the "buflen" parameter.

•

Some POSRES routines have parameters that can can be omitted
from the right.
For example, if the fourth parameter is
omitted, then parameters five, six, and seven must also be
omitted.

•

Some POSRES routines have parameter groups with a variable
format within the group. Short parameter lists (no more than
three or four groups) are easier to read and debug.
Long
parameter lists, however, are more efficient because they
require fewer calls.

•

POSRES parameter list run-time checking is somewhat limited.
Check your source code against the lists in this chapter
carefully.
Invalid parameters can
cause
unpredictable
results.

8-2

DMENU - DISPLAY DYNAMIC MENU
8.2

DMENU - DISPLAY DYNAMIC MENU

This routine displays
buffer.

the

single-choice

the

dynamic

Format:
DMENU (status, action, buflen, strlen, display, add_opt,

msgl, buflen, msg2, buflen)
status

Is a two-word
indicating the
Appendix C. )

action

Is a string buffer of up to 80 characters that returns
the action string associated with the option selected.
The action string is truncated or filled with blanks to
fit the buffer.

buf len

Is an integer expression that specifies
the action buffer.

strlen

Is an integer variable that returns the actual length of
the string in the action buffer.

display

Is reserved for future use.
zero for this parameter.

add_opt

Is an integer expression that specifies whether to
display an Additional Options flag on the menu and
whether to return control if the user presses the ADDTNL
OPTIONS key. Values:

integer
results

array that returns a
of the routine call.

the

length

code
(See

Specify an integer value of

zero = no flag
nonzero = display Additional Options flag
msgl

Is a string expression of up to 80 characters
specifies a message to be displayed on line 23.

buflen

Is an integer expression that specifies
msgl.

msg2

Is a string expression of up to 80 characters
specifies a message to be displayed on line 24.

bu fl en

Is an integer expression that specifies
msg2.

8-3

the

length

that
of
that
of

DMENU - DISPLAY DYNAMIC MENU
Note:

If you specify a nonzero value for the Additional Options
flag,
POSRES returns (-14/14) in the status block when the
user presses the ADDTNL OPTIONS key.
Example:

1880 REM *** Displaying a single-choice Dynamic Menu. ***
1890 Act$ = SPACE$(80%) !Buffer area of the action string
1900 Msg1$
'This is the first message line for the dynamic menu.'
1910 Len1%
LEN(Msg1$) !Length of the first message line
1920 Msg2$
'This is the second message line for the dynamic menu.'
1930 Len2%
LEN(Msg2$) !Length of the second message line
1940 CALL Dmenu BY REF &
(Stblk%(),Act$,80%,Len3%,0%,0%,Msgl$,Lenl%,Msg2$,Len2%)

8-4

DPACK - PACK DYNAMIC SINGLE CHOICE MENU
8.3

DPACK - PACK DYNAMIC SINGLE CHOICE MENU

This routine packs
buffer.

(stores

information

in)

the

dynamic

status

Is a two-word integer array that returns a
indicating
the results of the routine call
Appendix C).

code
(see

f ieldid

Is a string expression of up to
six
uppercase
characters that specifies one of the following field
identifiers:

Format:
DPACK (status, group, ... )

The format of a group is:

f ieldid

'TITL'
'TEXTnn'
'GHLP'
'PRMT'
'OPTNnn'
'ACTNnn'
'OHLPnn'

menu field

title
explanatory text
global help frame identifier
prompt text for line 21
option text for option nn
action string for option nn
help frame identifier
for option nn

01,02,03
01-12
01-12
01-12

buf len

Is an integer expression that specifies the
the fieldid.

fieldval

Is a string variable of any length that specifies the
contents of the field.
For example, if fieldid is
'TITL' then fieldval specifies the title text.

bu fl en

Is an integer expression that specifies the
the field value.

CLRB

Is a string constant containing a command
the dynamic buffer.
8-5

length

length
that

clears

DPACK - PACK DYNAMIC SINGLE CHOICE MENU
DFLTnn

Is a string constant containing a command that sets the
default option number to nn (01-12).

KEYWnn

Is a string constant containing a
command
specifies the keyword of option nn (01-12).

off set

Is an integer expression that specifies the beginning
of an option keyword as an offset from the beginning of
the option (range zero to one less than the length of
the option text).

keylen

Is an integer expression that specifies the
the option keyword.

that

length

Notes:
•

The order in which you pack menu fields is not significant.

•

If you specify an option help frame identifier (OHLPnn) with
an invalid (greater than 12) number, POSRES does not return
an error code in the status block.

Example:
1480 REM *** Packing the Dynamic menu buffer.
1490 Title$ = 'Title for DYNAMIC Menu'
1500 L1% = LEN(Title$)
!Length of title field
1510 Txt1$ = 'This menu is a shorter version of the FRAME001 Menu.'
1520 L2% = LEN(Txt1$)
!Length of textl field
1530 Glbhlp$ = 'HELPOOOO'
1540 Prmtln$ = 'Select the desired option and hit DO'
1550 L3% = LEN(Prmtln$)
!Length of prompt line
1560 Opt1txt$ = 'Option 1 - the first choice'
1570 L4% = LEN(Optltxt$)
!Length of option 1 text
1580 Opt2txt$ = 'Second option - the default'
1590 L5% = LEN(Opt2txt$)
!Length of option 2 text
1600 Actst1$ = 'Action string for the first test option.'
1610 L6% = LEN(Actst1$)
!Length of action 1 text
1620 Actst2$ = 'Action string for the second option'
1630 L7% = LEN(Actst2$)
!Length of action 2 text
1640 Hlpfr1$
'HELP0001'
1650 Hlpfr2$ = 'HELP0002'
1655

The Dpack call can be specified on multiple lines.
However, the first parameter must always be Status

1657 REM *** Packing the new Dynamic Single Choice Menu.***
1660 Call Dpack BY REF &
(Stblk%(), 'CLRB', 4%, 'TITL', 4%, Title$, L1%)
1680 Call Dpack BY REF &
8-6

DPACK - PACK DYNAMIC SINGLE CHOICE MENU
( Stblk% ()I 'TEXT01', 6%, Txt1$, L2%)
1700 Call Dpack BY REF &
(Stblk%(), 'GHLP' I 4%, Glbhlp$, 8%, 'DFLT02' I 6%)
1720 Call Dpack BY REF &
(Stblk%(), 'PRMT', 4%, Prmtln$, L3%)
1740 Call Dpack BY REF &
(Stblk%(), '0PTN01', 6%, Opt1txt$, L4%)
1760 Call Dpack BY REF &
( Stblk% ( ) I '0PTN02', 6%, Opt2txt$, L5%)
1780 Call Dpack BY REF &
(Stblk% ()I 'ACTN01'' 6%, Actst1$, L6%)
1800 Call Dpack BY REF &
(Stblk%(), 'ACTNIT2', 6%, Actst2$, L7%)
1820 Call Dpack BY REF &
(Stblk%(), '0HLP01', 6%, Hlpfr1$, 8%)
1840 Call Dpack BY REF &
(Stblk%(), 'OHLP02', 6 9-,.0' Hlpfr2$, 8%)
1860 Call Dpack BY REF &
(Stblk% ()I 'KEYW01' I 6 9-,.0 ' 0%, 8%, 'KEYW02', 6%,0%,6%)

8-7

FATLER - FATAL ERROR
8.4

FATLER - FATAL ERROR

The Fatal Error routine informs the user of an unexpected and
disabling error condition and returns control to P/OS (not to
your task). It blanks line 22, displays the message "Application
error.
Press RESUME to return to Main Menu." on line 23, and
displays an application-defined message on line 24. ·That message
can tell the user why the application failed and where to look
for recovery information.
Format:
FATLER (message, buflen)

message

Is a string expression of up
specifies an error message.

bu fl en

Is an integer expression that specifies
the message parameter.

characters
the

length

Example:

100 ON ERROR GOTO 1120

1120 REM Fatal error handling
1130 Linenum$ = STR$(ERL)
l Get line number
1140 Errormsg$ = ERT$(ERR)
l Get error message number
1150 Rtnmsg$ = 'Fatal error occurred at ' &
+ Linenum$ + '. ' + Errormsg$
1160 L% = LEN(Rtnmsg$)
1170 CALL Fatler BY REF( Rtnmsg$, L% )

8-8

that
of

GETKEY - GET KEYSTROKE

8.5

GETKEV - GET KEYSTROKE

Gets a single keystroke from the terminal.
echoed on the screen.

The keystroke is

not

Format:

GETKEY (status)

status

Is a two-word integer
following codes:

array

containing

one

the

First
Word

Second
Word

A DEC Multinational decimal character
representing a main keyboard key.

code,

A code representing one
shown in Appendix D.

keys

Indicates an error has occurred.
for status values.

the

function

See Appendix

Example:

100

DIM Stblk%(1%)
PRINT "Enter a key";\. CALL Getkey BY REF( Stblk%() )
SELECT Stblk%(0%)
CASE 1%
PRINT "Main keyboard key="; CHR$(Stblk%(1%))
CASE 2%
PRINT "Function or Keypad key -- ".' Stblk%(1%)
CASE ELSE
PR I NT " Er r o r . St at us = " ; St b 1 k %( 0 % ) , St b 1 k %( 1 % )
END SELECT
GOTO 100

8-9

HCLOSE - CLOSE HELP FILE
8.6

HCLOSE - CLOSE HELP FILE

This routine closes the current help definition file.
Format:
HCLOSE (status)

status

Is a two-word integer array that returns
a
indicating
the results of the routine call.
Appendix C. )

Example:

1990 REM *** Closing help definition file ***
2000 CALL Hclose BY REF( Stblk%() )

8-10

code
(See

HELP - DISPLAY HELP FRAME
8.7

HELP - DISPLAY HELP FRAME

Displays the default help frame or a specified help frame.
Format:
HELP (status, frameid, buflen)

integer
results

array that returns a
of the routine call.

code
(See

status

Is a two-word
indicating the
Appendix C.)

frameid

Is a string of up to eight
the help frame to display.

characters

that

identifies

bu fl en

Is an integer expression that specifies
frame id.

the

length

Note:

If you specify a nonexistent help
returns immediately without an
block.

frame
error

identifier, POSRES
code in the status

Example:

1180 REM *** Display help text frame ***
1190 CALL Help BY REF(Stblk%(), 'HELP0000', 8%)

8-11

HFILE - OPEN HELP FILE

8.8

HFILE - OPEN HELP FILE

This routine opens the specified help definition
the default help frame.

file

and

sets

Format:
HFILE (status, filespec, buflen, frameid, buflen)

status

Is a two-word
indicating the
Appendix C.)

integer
results

array that returns a
of the routine call.

code
(See

filespec

Is a string expression
definition file.

that

help

buf len

Is an integer expression that specifies the
the help file specification.

f rameid

Is a string expression of one to eight characters
specifies the name of the default help frame.

buf len

Is an integer expression that specifies the
the default help frame string.

specifies

the
length

of
that

length

Notes:

•

Only one help file can be open at any time.
If another help
file is open, HFILE closes it before the requested file is
opened.

•

You should provide a complete file specification for your
help file, unless your installation command file contains an
ASSIGN HELP command.
If your installation command file does
contain an ASSIGN HELP command, you do not have to specify a
device and directory in the file specification.
Use the appropriate system logical name to represent the
device and directory. The location of the help file depends
on the qualifiers you use on the FILE command in your
installation file.
For example, suppose you specify the following
in your .INB file:

FILE

command

FILE TEST.HLP/NETWORK
In your HFILE call, the file specification for TEST.HLP is:
APPL$NETWORK:TEST.HLP

8-12

HFILE - OPEN HELP FILE
Note that if you omit fields in the file specification,
POSRES uses the P/OS default file specification, which is
almost certainly wrong.
See the Tool Kit User's Guide, for details regarding
logical names and accessing application components.
•

You must supply a default
results in a fatal error.

help

frame.

Failure

system
do

Example:
100

DIM SCB%(7%), STATUS%(1%)
! Get name of application directory

FILE_SPEC$ = SPACE$(29%) ! buffer for equivalence name
CALL PROLOG BY REF &
(SCB%(), 4%, 'APPL$DIR', 8%, FILE_SPEC$, 30%)
Construct filespec and open help file
FILE_SPEC$ = FILE_SPEC$ + 'TEST.HLP'
CALL HFILE BY REF &
(STATUS%(), FILE_SPEC$, LEN(FILE_SPEC$),

8-13

'FOO', 3%)

HFRAME - SPECIFY HELP FRAME
8.9

HFRAME - SPECIFY HELP FRAME

Specifies the frameid of the frame to be displayed when help is
requested.
This call does not result in a display; it simply
defines the default frame.
Format:
HFRAME (status, frameid, buflen)

status

Is a two-word
indicating the
Appendix C.)

integer
results

array that returns a
of the routine call.

f rameid

Is a string expression of up to eight characters that
specifies the default help frame identifier. A fatal
error results if frameid is specified as blank or of
zero length.

buf len

Is an integer expression that ~pecifies
the frameid string.

the

code
(See

length

Notes:

•

The help frame definition file must be
HFRAME.

•

If you specify a nonexistent help
returns immediately without an
block.

frame
error

open

calling

identifier, POSRES
code in the status

Example:

1140 REM *** Calling help frame ***
1150 CALL Hframe BY REF(Stblk%(), 'HELP0001', 8%)

8-14

before

MCLOSE - CLOSE MENU FILE
8.10

MCLOSE - CLOSE MENU FILE

This routine closes the current menu file.
Format:
MCLOSE (status)

status

a
Is a two-word integer array that returns
indicating
the results of the routine call.
Appendix C. )

Example:

2020 REM *** Closing menu definition file ***
2030 CALL Mclose BY REF( Stblk%() )

8-15

code
(See

MENU - DISPLAY SINGLE-CHOICE MENU
8.11

MENU - DISPLAY SINGLE-CHOICE MENU

Displays a frame from the default static menu buffer.
Format:
MENU

(status, action, buflen, strlen, display, ad_opt,
msgl, buflen, msg2, buflen)
integer
results

array that returns a
of the routine call.

code
(See

status

Is a two-word
indicating the
Appendix C.)

action

Is a string buffer of up to 80 characters that returns
the action string associated with the option selected.
The action string is truncated or filled with blanks to
fit the buffer.

bu fl en

Is an integer expression that specifies
the action buffer.

strlen

Is an integer variable that returns the actual length of
the string in the action buffer.

display

Is reserved for future use.
zero for this parameter.

add_opt

Is an integer expression that specifies whether to
display an Additional Options flag on the menu and
whether to return control if the user presses the ADDTNL
OPTIONS key. Values:

the

length

Specify an integer value of

zero = no flag
nonzero = display Additional Options flag
msgl

Is a string expression of up to 80 characters
specifies a message to be displayed on line 23.

bu fl en

Is an integer expression that specifies
msgl.

msg2

Is a string expression of up to 80 characters
specifies a message to be displayed on line 24.

bu fl en

Is an integer expression that specifies
msg2.

8-16

the

length

that
of
that
of

MENU - DISPLAY SINGLE-CHOICE MENU
Example:

1350 REM *** Calling menu routine ***
1360 Action$ = Space$( 80% ) !Buffer area for the action string
1370 Msg1$ = 'This is the first message line'
1385 L1% = LEN(Msg1$)
!Length of the first message
1390 Msg2$ = 'This is the second message line'
1400 L2% = LEN(Msg2$)
!Length of the second message
1410
!0% = display (full)
1420 CALL Menu BY REF &
(Stblk%(),Action$,80%,Length%,0%,0%,Msgl$,Ll%,Msg2$,L2%)
1430
!0% = add. options (no)

8-17

MFILE - OPEN MENU FILE
8.12

MFILE - OPEN MENU FILE

This routine opens the specified menu definition file.
Format:
MFILE (status, filespec, buflen)

status

Is a two-word
indicating the
Appendix C.)

filespec

Is a string expression
definition file.

buf len

Is an integer expression that specifies the
the menu file specification.

integer
results

array that returns a
of the routine call.

code
(See

that

specifies

the
length

Notes:

•

Only one menu file can be open at any time. MFILE closes any
open menu file before opening the requested file.

•

You should provide a complete file specification for your
menu file, unless your installation command file contains an
ASSIGN MENU command. If your installation command file does
contain an ASSIGN MENU command, you do not have to specify a
device and directory in the file specification.
Use the appropriate system logical name to represent the
device and directory. The location of the menu file depends
on the qualifiers you use on the FILE command in your
installation file.
For example, suppose you specify the following
in your .INB file:

FILE

command

FILE TEST.MNU/USER
In your MFILE call, the file specification for TEST.MNU is:
APPL$USER:TEST.MNU
Note that if you omit fields in the file specification,
POSRES uses the P/OS default file specification, which is
almost certainly wrong.

8-18

MFILE - OPEN MENU FILE
See the Tool Kit User's Guide, for details
regarding
logical names and accessing application components.

system

Example:
100

DIM SCB%(7%), STATUS%(1%)
l Get name of application directory

FILE_SPEC$ = SPACE$(29%) ! buffer for equivalence name
CALL PROLOG BY REF &
(SCB%(), 4%, 'APPL$DIR' I 8%, FILE_SPEC$, 30%)
Construct filespec and open menu file
FILE_SPEC$ = FILE_SPEC$ + 'TEST.MNU'
CALL MFILE BY REF (STATUS%(), FILE_SPEC$, LEN(FILE_SPEC$))

8-19

MFRAME - READ MENU FRAME
8.13

MFRAME - READ MENU FRAME

Reads the specified menu frame into the static menu buffer.
Format:
MFRAME {status, frameid, buflen, action, buflen, strlen)

status

Is a two-word
indicating the
Appendix C.)

integer
results

f rameid

Is a string of one to eight characters that specifies a
menu frame identifier.

bu fl en

Is an integer expression that specifies the
the frameid.

action

Is a string variable of any length that returns the
global action string associated with the menu frame, if
present. The global action string is truncated or
padded with spaces to fit the buffer.

bu fl en

Is an integer expression that specifies
length of the action parameter.

the

maximum

strlen

Is an integer variable that returns the
of the returned global action·string.

actual

length

array that returns a
of the routine call.

code
(See

length

Note:

The menu definition file must be open before calling MFRAME.
Example:

1220 Gloact$ = Space$( 80% ) !Buffer for global action string
1230 CALL Mf rame BY REF &
( Stblk%(), 'FRAME001', 8%, Gloact$, 80% , Len%)

8-20

MMENU - DISPLAY MULTIPLE-CHOICE MENU
8.14

MMENU - DISPLAY MULTIPLE-CHOICE MENU

This routine displays a multiple-choice menu.
Format:
MMENU (status, opt_buff, opt_len, opt_count, max_opt,
resp_count, resp_array, add_opt,

msg1, buflen, msg2, buflen)
status

Is a two-word integer array that returns a
indicating the results of the routine call.
Appendix C) .

opt_buf f

Is a string buffer that specifies the options on this
menu, in the form of a concatenated string.

opt_len

Is an integer expresssion that specifies the length
of an option (up to 64 characters). All options must
have the same length.
Before concatenation, use
trailing space characters to pad all option strings
to this length.

opt_count

Is an integer expression that specifies the number of
options in the buffer.

max_opt

Is an integer expression that specifies the
number of options that the user can select.

resp_count

Is an integer variable that
options actually selected.

resp_array

Is an integer array of the size specified in max_opt
that returns the ordinal numbers of the selected
options in ascending order.

add_opt

Is an integer expression that specifies whether to
display an Additional Options flag on the menu and
whether to return control if the user presses the
ADDTNL OPTIONS key. Values:

returns

the

code
(See

maximum

number

zero = no fla9
nonzero = display Additional Options flag
msgl

Is a string expression of up to 80 characters
specifies text to be displayed on line 23.

bu fl en

Is an integer expression that specifies the length of
msgl.
8-21

that

MMENU - DISPLAY MULTIPLE-CHOICE MENU
msg2

Is a string expression of up to 80 characters
specifies text to be displayed on line 24.

that

buf len

Is an integer expression that specifies the length of
msg2.

Example:
REM *** Setting up to display the Multiple-choice Menu ***
!Maximum option length
Optlen% = 6%
! Option count.
Optct% = 9%
!Option text. Note that
Opttxt$(0%)
"Red
"
Opttxt$(1%)
"Orange"
!Tool Kit BP2 zero-based arrays
!are returned in Resary%
Opttxt$(2%)
"Yellow"
!as 1 through 9, not
Opttxt$(3%)
"Green "
!O through 8.
Opttxt$(4%) = "Blue "
Opttxt$(5%)
"Purple"
Opttxt$(6%)
"Brown "
Opttxt$(7%)
"Black "
Opttxt$(8%) = "White "
! Now concatenate all the options
! in one string (Optct% by Optlen%)
Opt$ = Opttxt$(0%) + Opttxt$(1%) + Opttxt$(2%) + Opttxt$(3%) + &
Opttxt$(4%) + Opttxt$(5%) + Opttxt$(6%) + Opttxt$(7%) + &
Opttxt$(8%)
!Max. number of options
2450 Lmt% = 9%
!Buffer area for message line one.
2460 Msg1$
SPACE$(75%)
!Buffer area for message line two.
2470 Msg2$ = SPACE$(75%)

2300
2310
2320
2330
2340
2350
2360
2370
2380
2390
2400
2410
2430
2435
2440

2475 REM *** Displaying the Dynamic Multi-Choice Menu. ***
2480 CALL Mmenu BY REF &
(Stblk%(), Opt$, Optlen%, Optct%, Lmt%, Res%, Resary%(), &
0%, Msg1$, 75%, Msg2$, 75%)

8-22

MPACK - PACK MULTIPLE-CHOICE MENU
8.15

MPACK - PACK MULTIPLE-CHOICE MENU

This routine packs (stores information
menu buffer.

in)

the

multiple-choice

Format:
MPACK (status, group, ... )

The format of a group is:

integer
results

status

Is a two-word
indicating the
Appendix C.)

f ieldid

Is a string expression of up to
six
uppercase
characters that specifies one of the following field
identifiers:
f ieldid

'TITL'
'TEXTnn'
'GHLP'
'PRMT'

array that returns a
of the routine call.

code
(See

menu field

01,02,03

title
explanatory text
global help frame identifier
prompt text for line 21

bu fl en

Is an integer expression that specifies the
the field identifier.

fieldval

Is a string variable of any length that specifies the
contents of the field.
For example, if fieldid is
'TITL' then fieldval specifies the title text.

bu fl en

Is an integer expression that specifies the
the field value string.

CLRB

Is a string constant containing a command
the multi-buffer before use.

Note:

You can make multiple calls to MPACK.

8-23

length

length
that

clears

MPACK - PACK MULTIPLE-CHOICE MENU
Example:
2050 REM *** Setting up to pack the multi-buffer **
2060 Title$ = 'Title for Multiple-choice Menu '
2070 L1% = LEN(Title$)
!Length of the title field
2080 Txt1$ = 'This menu is an example of a Multiple-choice menu.
2090 L2% = LEN(Txt1$)
!Length of the first text line
2100 Txt2$ ='Use the SELECT key to choose your favorite colors.'
2110 L3% = LEN(Txt2$)
!Length of the second text line
2140 Glbhlp$ = 'HELP0000'
2150 Prmtln$ = 'Use the SELECT key to make a choice and press DO'
2160 L5% = LEN(Prmtln$)
!Length of the prompt line
2170 REM *** Packing the multi-buffer. ***
2180 Call Mpack BY REF &
(Stblk%(), 'CLRB', 4%, 'TITL', .4%, Title$, L1%)
2200 Call Mpack BY REF &
(Stblk%(), 'TEXT01', 6%, Txt1$, L2%)
2220 Call Mpack BY REF &
(Stblk%(), 'TEXT02', 6%, Txt2$, L3%)
2260 Call Mpack BY REF &
(Stblk%(), 'GHLP', 4%, Glbhlp$, 8%)
2280 Call Mpack BY REF &
(Stblk%(), 'PRMT', 4%, Prmtln$, L5%)

8-24

MSGBRD - SEND MESSAGE TO A MESSAGE/STATUS DISPLAY

8.16

MSGBRD - SEND MESSAGE TO A MESSAGE/STATUS DISPLAY

This routine sends a message to the P/OS Message/Status Display,
described in the Hard Disk System User's Guide.
In a P/OS Server
environment, the Message/Status Display can belong to the user,
the workstation, or the Server.
Format:
MSGBRD (status, message, buflen, destin)

status

Is a
two-word integer array that returns
a
indicating
the
results of the routine call.
Appendix C.)

code
(See

message Is a string expression of up to 59 characters that
specifies text to be sent to the Message/Status Display.
All nonprintable characters in the message are
replaced
with blanks.
buflen

Is an integer expression that specifies the length of the
message string.

destin

Is
an
integer
expression
that
specifies
which
Message/Status Display is to receive the message.
If
omitted,
the destination
defaults
to
the
user's
Message/Status Display.
Value

Global

Destination

u.def
w.def

user's Message/Status Display
workstation's Message/Status Display

Note:

The MSGBRD routine is not in POSRES; it is in the system
(SYSLIB).
Example:

111
114
117
140
150
160

Dim Stblk%(1%)
Msg$ = "A sample message for posting."
REM Post message on workstation's message display.
Call Msgbrd By Ref (Stblk%(),Msg$,Len(Msg$),1%)
Print Stblk%(0), Stblk%(1)
End

8-25

library

MUNPK - UNPACK MENU BUFFER
8.17

MUNPK - UNPACK MENU BUFFER

This routine unpacks (returns
static menu buffer.

the

information

stored

in)

the

Format:
MUNPK

(status, group, ... )

The format of a group is:

integer
results

code
(See

array that returns a
of the routine call.

status

Is a two-word
indicating the
Appendix C. )

fieldid

Is a string expression of up to six uppercase characters
that specifies one of the following field identifiers:
f ieldid

'TITL'
'TEXTnn'
'GACT'
'GHLP'
'PRMT'
'OPTNnn'
'ACTNnn'
'OHLPnn'
bu fl en

Menu Field

title
explanatory text
global action string
global help frame identifier
prompt text for· line 21
option text for option nn
action string for option nn
help frame identifier
for option nn

01,02,03

01-12
01-12
01-12

Is an integer expression that specifies
the field identifier string.

the

length

fieldval Is a string variable of any length that returns the
value of the field. For example, if fieldid is 'TITL',
then fieldval returns the title text.
bu fl en

Is an integer expression that specifies
the field value buffer.

the

strlen

Is an integer variable that returns the
field value string.

length

8-26

length
of

of
the

MUNPK - UNPACK MENU BUFFER
DFLT

Is a string constant containing a command that
the default option number.

def opt

Is an integer variable that returns the
number (01-12).

KEYWnn

Is a string constant containing a command that requests
the off set and length of the keyword of option nn
(01-12).

off set

Is an integer variable that returns the beginning of an
option keyword as an off set from the beginning of the
option (range zero to one less than the length of the
option text).

keylen

Is an integer variable that returns the
keyword.

default

length

requests
option

the

Example:

1290 Title$ = Space$( 40% )
1300 CALL MUNPK BY REF(Stblk%(),

!Buffer area for the menu title
'TITL' I 4%, Title$, 40%, Length%)

8-27

NEWFIL - NEW FILE
8.18

NEWFIL - NEW FILE

Solicits the name of a new file to be created by
P/OS New File Specification form.

displaying

the

Format:
NEWFIL (status, filespec, buflen, strlen, deftype,
buflen, strlen, text, buflen, msg, buflen)

integer
results

status

Is a two-word
indicating the
Appendix C.)

filespec

Is a 50-character string buffer that returns the file
specification entered by the user. If you specify a
default filename, it can be no longer than nine
characters and must be followed by a null character or
a space.

bu fl en

Is an integer expression that specifies the
the filename buffer (50).

strlen

Is an integer variable that returns the
of the file specification.

def type

Is a four-character string variable that specifies a
default file type. If the user changes the file type
via Additional Options, NEWFIL returns the updated file
type.

buf len

Is an integer expression that specifies the
the file type buffer (4).

strlen

Is an integer variable that returns the length
string returned in deftype.

the

text

Is a string expression of 0 to 72 characters
specifies text to appear at the top of the form.

that

bu fl en

Is an integer expression that specifies the
the text string.

msg

Is a string expression of 0 to 80
specifies text to appear on line 23.

bu fl en

Is an integer expression that specifies the
rnsgl.

8-28

array that returns a
of the routine call.

code
(See

length

actual

length

characters
length

of
that
of

NEWFIL - NEW FILE
Example:
100 REM Program to test the NEW FILE Service
110 DIM Stblk%( 1% )
120 Filename$ = SPACE$( 50%
~ Set up buffer for filename
130 Filetype$ ='.DAT'
! Set up filename type
140 Text1$ = 'Test to check the Service of NEW FILE.'
160 Msg1$ = 'Message at bottom of NEW FILE menu.'
180 CALL Newfil BY REF (Stblk%(),
Filename$, 50%, Namelen%,
&
Filetype$, 4%, Typelen%,
&
Text1$, LEN(Text1$), Msg1$, LEN(Msg1$))
190 PRINT "Status="; Stblk%( 0% ), Stblk%( 1% )
200 PRINT "Filename = "; Filename$
210 PRINT "Name length
"; Namelen%
220 PRINT "Type length="; Typelen%
230 END

8-29

OLDFIL - OLD FILENAME
8.19

OLDFIL - OLD FILENAME

The Old Filename routine solicits the names of one
existing files by displaying the File Selection Menu.

array that returns a
of the routine call.

code
(See

Format:
OLDFIL (status, maxfiles, files, strlens,
wildcard, buflen, textl, buflen,
msgl, buflen, msg2, buflen)

status

Is a two-word
indicating the
Appendix C.)

maxfiles

Is an integer variable that specifies the maximum
number of files the user can select and returns the
number of files actually selected.

files

Is a string buffer that returns the selected file
specifications in concatenated SO-character strings,
left-justified and blank-filled.
Thus, the size in
characters
is
50 times the number specified in
maxfiles.

strlens

Is an integer array of the size specified in maxfiles
that
returns
the
actual
length
of each file
specification string.

wildcard

Is a string ~xpression
selection criteria.

bu fl en

Is an integer expression that specifies the
the wildcard string.

text

Is a string expression of 0 to 72 characters that
specifies text to be displayed at the top of the
screen.

bu fl en

Is an integer expression that specifies the
text.

msgl

Is a string expression of 0 to 54 characters
specifies text to be displayed on line 23.

bu fl en

Is an integer expression that specifies the
msgl.

msg2

Is a string expression of 0 to 54 characters
spetifies text to be displayed on line 244

integer
results

8-30

that

specifies

the
length

length

file
of

of
that
of
that

OLDFIL - OLD FILENAME
Is an integer expression that specifies the
msg2.

bu fl en

length

Notes:

•

You can use the default wildcard specification (*.*)
by
supplying a zero-length string,
in order to display the
latest versions of all files in the user's current directory.

•

The Additional Options "show all versions" and "show only the
latest versions" work only when you use the default wildcard
specification. Otherwise, the same file selection menu will
reappear.

Example:

100
120
130
140
160
180
200
230

250
260
270

DIM STBLK%(1%), SIZEARRAY%(1%)
NUMCHOICE%
2%
FILEBUF$
SPACE$(100%)
WILDSPEC$
'*.TSK'
TEXT1$
'Choose a file spec and Press DO'
MSG1$
'This is the first message'
MSG2$
'This is the second message'
CALL OLDFIL BY REF
(STBLK%(), NUMCHOICE%, FILEBUF$, SIZEARRAY%(),
WILDSPEC$, LEN(WILDSPEC$), TEXT1$, LEN(TEXT1$),
MSG1$, LEN(MSG1$), MSG2$, LEN(MSG2$))
PRINT "Status:"; STBLK%(0%), STBLK%(1%)
PRINT "Files chosen:"; NUMCHOICE%
PRINT MID$(FILEBUF$, (I%* 50%) -49%, SIZEARRAY%(I%-1%))
FOR I% = 1% TO NUMCHOICE%

8-31

&
&
&

PRSCSI - PARSE STRING

8.20

PRSCSI - PARSE STRING

This routine parses a string for a CSI sequence.
The character~
in the buff parameter are scanned from the left until a CSI
character is found.
The sequence following the CSI character is
parsed and translated int:' a value indicating which function key
terminates the string.
Format:
PRSCSI (status, buff, buflen, csipos)
status

Is a two-word integer array.
In the first element of the
array,
+2, indicates that a valid CSI sequence was found
and that the second element contains one of the function
key values in Appendix D. A value less than 0 indicates
an error occurred.
(See Appendix C.)

buff

Is a string variable of any length.

buflen

Is an integer expression that
buff.

length

csipos

Is an integer variable that returns the position of
CSI character, counting from one.
(See the notes.)

the

specifies

the

Note:
The csipos parameter was described in previous
Tool
Kit
documentation as the length of the string, up to but not
including the CSI character. The value returned is actually the
length of the string, up to and including the CSI character.
Example:
10
30
40
50
60
70
80
90
100
200

Dim Stblk%(1%)
Buffer$ = "This is an example of PARSE" + ESC + "[29"'"
Call Prscsi By Ref &
(stblk%(), buffer$, len(buffer$), csipos%)
If stblk%(0%) < 0 goto 100
Buffer$ = left$(buffer$, csipos% - 1%)
Print buffer$
Print Stblk%(1%)
Goto 200
Print "error"; stblk% ( 0%); stblk% ( 1%)
End

8-32

RDMSG - READ MESSAGE
8.21

RDMSG - READ MESSAGE

This routine reads a message from a message definition file
a buffer.

into

Format:
RDMSG (status, filespec, buflen, frameid, buflen,
message, buflen, strlen)

status

Is a two-word
indicating the
Appendix C.)

integer
results

array that returns a
of the routine call.

code
(See

filespec

Is a string specifying the message definition file.

bu fl en

Is an integer expression that specifies the
the filespec parameter.

f rameid

Is a string expression of 1 to 8 characters that
identifies the message frame to read from the message
file. A fatal error results if frameid is specified as
blank or of zero length.

bu fl en

Is an integer expression that specifies the
the frameid string.

message

Is a string buffer of any length that returns the
specified message. The message is truncated or filled
with blanks to fit the buffer.

bu fl en

Is an integer expression that specifies the
the message buffer.

strlen

Is an integer variable that returns the
of the returned message string.

length

actual

length

Notes:

If you do not include an ASSIGN MESSAGE command in your
• installation
file, and you do not provide a complete file
specification for your message file in the RDMSG call, POSRES
attempts to open the message definition file in APPL$USER:
(or APPL$DIR for older systems).
•

If you do include an ASSIGN MESSAGE command in
your
installation command file, you do not have to specify a
device and directory in the file specification. POSRES uses
the qualifiers specified on the ASSIGN MESSAGE command to
determine where to look for the the message definition file.
8-33

RDMSG - READ MESSAGE
For example, suppose you specify the following ASSIGN MESSAGE
command in your .INB file:
ASSIGN MESSAGE TEST.MSG/USER
POSRES searches
specification:

for

TEST.MSG

using

the

following

file

See the Tool Kit User's Guide, for details regarding
logical names and accessing application components.

system

APPL$USER:TEST.MSG

Example:

1100 CALL Rdmsg BY REF &
(Stblk%(),'BASETEST.MSG',12%,'MESS0001' ,8%,B$,B%,L%)

8-34

WTRES - WAIT FOR RESUME KEY

8.22

WTRES - WAIT FOR RESUME KEY

This routine echoes all keyst~okes except the RESUME key with a
bell character.
When the user presses the RESUME key, control
returns to the task.
You can use this routine to allow the user
to read something on the screen or change a diskette, for
example, before proceeding.
Before calling WTRES, display a
message such as "Press RESUME to continue." on the screen.
Format:
WTRES

()

Example:

1180
1190
1120

PRINT "Calling HELP frame. Press RESUME to continue."
CALL Wtres BY REF()
! Allow user to read message
CALL Help BY REF(Stblk%(), 'HELP0000', 8%)

a. . 35

CHAPTER 9
CALLABLE PRINT SERVICES

Print Services consists of two callable routines that allow your
application to print a file, stop, continue, abandon or restart a
print job, or obtain printer status.
The two routines, CPRNT and CPRNV3, differ in their capabilities
and
in their compatibility with different operating system
versions. See Section 9.3 for complete details.
CPRNV3 provides an additional feature:
the ability to submit
print requests to a particular print queue. Print queues are
available only on P/OS V3.0 systems or later.
If you need compatibility across all system versions,
instead of CPRNV3.

use

CPRNT

For both routines, a request to print a file executes a
noninteractive task whose installed name is C$PRNT. Also, both
routines use the RS calling convention to pass parameters.
For
each call, register 5 must contain the address of your parameter
buffer. For details on the RS calling convention, see the P/OS
System Reference Manual.

9.1

CPRNT

Format:
CPRNT (status, request, filespec, len)
status

A two-word integer array used
indicating the results of the
below) .

request

A 75-word integer array.

to return a
code
service request (see

The first word specifies
of the following request values:
9-1

one

CPRNT
+1
+2
+3
+4
+5
+6

Print file
Abandon current print job
Pause current print job
Continue the paused print job
Restart the current print job
Report printer condition

The remainder of the array is used as temporary storage
by the CPRNT routine.
f ilespec

An ASCII string expression that contains the file
specification of the file to be printed if the print
file service (+l) is requested.
Spe~ify
zero if a
service other than print file is requested.

len

An integer expression that contains the number of
characters in filespec. Specify zero if the filespec
parameter was omitted.

Status Values:

In the first word of the status array indicates that the
request was accepted.
If the request was "report printer
condition," the second word returns one of the decimal
condition codes shown in Table 9-1.

-1

In the first word of the status array indicates that a
directive error occurred. The Directive Status Word (DSW)
error is contained in the second element of the array.

-21

In the first word of the status array indicates that a Print
Service error occurred.
The second element of the array
contains one of the decimal error codes shown in Table 9-2.

Table 9-1:

CPRNT Condition Codes

Code

Description

Print job accepted
Stop print job accepted
Pause print job accepted
Continue print job accepted
Restart current file accepted
Print job active
Print job paused
Print job inactive
Printer offline

2.
3.
4.

5.
6.
7.
8.
9.

9-2

CPRNT
Code

Description

10.
22.
23.

Printer offline/paused
Print request accepted, but printer type does not match
Unable to determine printer status

Table 9-2:

CPRNT Error Codes

Code

Description

-11.

Print job already active
Printer busy
Printer already attached
Print job not in progress
Print job not paused
Print job already paused
Parameter out of range
Printer is offline
More than 9 files selected
Printer offline / print job paused
Illegal file specification length
Port currently in use
Mini-Exchange not connected
Mini-Exchange printer currently in use
Print Server directive error encountered
Previous Mini-Exchange connection not broken
Error accessing set-up file. General RMS error.
Error accessing set-up file. File access error.
Error accessing set-up file. Error reading attributes.
Error closing set-up file.
Error accessing set-up file. Bad device specification.
Error accessing set-up file. Bad directory
specification.
Error accessing set-up file. No such directory.
Error accessing set-hlp file. Device not ready.
Error accessing set-up file. File locked by another
user.
Error accessing set-up file.
File not found.
Error accessing set-up file. Bad node name.
Error accessing set-up file. Privilege violation.

-12.
-13.
-14.

-15.
-16.
-17.
-18.
-19.
-20.
-21.

-24.
-25.
-26.
-27.
-28.
-29.
-30.
-31.
-32.

-33.
-34.

-35.
-36.
-37.

-38.
-39.

-40.

9-- 3

CPRNT
Code

Description

-41.
-42.
-43.
-44.
-45.

Error accessing set-up file.
Error accessing set-up file.
Error accessing set-up file.
Error accessing set-up file.
Error accessing set-up file.
string.
Error accessing set-up file.
specification.

-46.

File processor error.
File processor error.
Bad file extension.
Bad file version number.
Illegal wildcard in merged
Extraneous data in file

Notes:

P/OS Hard Disk, the call to the CPRNT always returns
• On
immediately with status.
If a request to print a file is
accepted, then CPRNT prints the file as a noninteractive
application while the calling application goes on to other
processing.
•

For compatibility with earlier versions of P/OS, you can call
CPRNT on sytems running P/OS V3.0 or later. See Section 9.3
for details.

9.2

CPRNV3

Format:
CPRNV3

(status, request, subfun, copynum, reserv
qnam, qlen, filespec, flen, jobnum)

status

Is an eight-word integer array used to return status
information. CPRNV3 currently uses only the first four
words.

request

Is a 75-word integer array.
the request:

9-4

The

first

word

contains

CPRNV3
Symbol

Value

Request

RQ.PRN
RQ.ABO
RQ.HLD
RQ.REL
RQ.STS

Submit a set of files to print
Abort a print request
Hold a print request
Release a held print request
Report status of a print request

3
4
5

The remainder of the array is used as temporary storage
by the CPRNV3 routine.
sub fun

Reserved.

copynum

Is a one-word integer representing the number of copies
of the job to print. The default value is one, and the
maximum value is 100.

reserv

Is reserved. You must supply a place holder, which
CPRNV3 ignores. qname
Is a variable-length string
representing the name of the queue in which to place
the print job.
The maximum length is 39. If you
specify zero for this parameter, CPRNV3 places the job
in the default queue, if defined.
Note that, to send a request to the default print
queue, the user who is running your application must
have previously specified a default queue. You should
query the user for the print queue name if your program
receives the error CE.QNF (default print queue not
defined).

qlen

Is a one-word integer representing the
qname parameter.

f spec

Is a variable-length string representing the file
specification of the file to be printed. The maxi~um
length is 65. CPRNV3 ignores this parameter if the
request is other than to print files.

flen

Is a one-word integer representing the
fspec parameter.

jobnum

Is an integer word specifying the job number of the job
to be aborted, held, released or reported. CPRNV3
ignores this parameter if the request is to print
files.

9-5

length

the

CPRNV3
Status Values:

Table 9-3 shows the status returns that you can receive
call to CPRNV3.

after

For a successful return (PS.sue in word 0 of the return block),
CPRNV3 places the job number in word 1 of the return block. If
there is a directive error during processing, CPRNV3 returns the
Directive Status Word (DSW) in word 1. For information on DSW
values, see the P/OS System Reference Manual.
The error PE.PRN in word 0 indicates that an error occurred in
the C$PRNT task.
The specific C$PRNT error code is in word 1.
All other error codes in word 0 indicate that the error occurred
in the CPRNV3 routine.
Whenever CPRNV3 returns a value of -12. in word 2 of the return
block, an RMS error has occurred; CPRNV3 returns the RMS STS and
STV status in words 3 and 4, respectively.
See the PRO/RMS-11
Macro Programmer's Guide for information on RMS errors.
Table 9-3:

Status Returns for CPRNV3

Word 0

Word 1

PS.sue

Job
number

Success

(+1)

PE.DSW

DSW

Directive error

Word 2

Word 3

Description

( -1)
( -3)

Server exited before
completing function

CE.BAB

Invalid argument block

CE.EXT

( -4)

( -5)

Invalid print queue name
length

CE.BFL

Invalid file spec length

CE.BQL

( -6)

PE.PRN

CE.BFN

( -2)

Invalid or unsupported
request function

9-6

CPRNV3
Word 0

Word 1

Word 2

PE.PRN

CE.BRP
( -3)

Incomplete request packet

(-2)

PE.PRN

CE.QNF

(-2)

( -4)

(Default) print queue not
defined

PE.PRN

CE.QFU
( -5)

Print queue is full

(-2)

PE.PRN

CE.NSJ

No such job

( -2)

(-6)

PE.PRN
(-2)

CE.DNF
( -8. )

PE.PRN

CE.ADF

( -2)

( -9. )

PE.PRN

CE.PDF

(-2)

(-10.)

PE.PRN
( -2)

CE.VRC
(-12.)

Error issuing VRCX
directive

PE.PRN
( -2)

CE.BQN

Invalid print queue name

PE.PRN

CE.QUE

( -2)

(-14.)

PE.PRN

CE.CPY

( -2)

(-15.)

PE.PRN

CE.FVE

( -2)

(-16.)

PE.PRN

CE.APS

( -2)

(-17.)

PE.PRN

CE.BJN

( -2)

(-19.)

PE.PRN

CE.AQF

( -2)

(-20.)

PE.PRN

CE.ARQ

( -2)

( -21. )

Word 3

Description

Data file not found

-12.

RMS
error

Error accessing data file

-12.

RMS
error

Error parsing data file
specification

DSW

( -13. )
-12.

RMS
error

Error queueing (creating
request file)

-12.

RMS
error

Error copying a data file
Bad file version string

-12.

RMS
error

Error accessing private
set-up file
Invalid job number

-12.

RMS
error

Error accessing queue file

-12.

RMS
error

Error accessing entry file

9-7

CPRNV3
Notes:
•

The CPRNV3 routine defines all request (RQ.xxx) and status
(PE.xxx and CE.xxx) symbols. When the task builder resolves
a reference to CPRNV3,
it automatically resolves these
symbols as well.

•

After a call to CPRNV3,
there might be a waiting period
before
Print Services processes the request.
If your
application queues a set of files to print and immediately
follows with a status report request, the call may return a
"No such job" error (CE.NSJ) because the print request has
not yet been processed.
In such cases, your application
should wait for some time and retry.

•

To indicate that you want the default value for a parameter,
specify a place holder whose value is zero for a numeric
parameter, or a null string (a string whose length is zero)
for a string parameter.

9.3

COMPATIBILITY BETWEEN CPRNT AND CPRNV3

Use CPRNT if you design an application to run on all P/OS
versions.
However, when calling CPRNT on P/OS V3.0 systems or
later, note that you can only specify the print request
(RQ.PRN)
in the call to CPRNT. No other requests are valid on P/OS V3.0
systems or later.

9.4

EXAMPLE

Figure 9-1 shows a sample MACR0-11 program that calls CPRNV3.

9-8

EXAMPLE
PRMBLK:

. WORD
.WORD
.WORD
.WORD
.WORD
.WORD
.WORD
.WORD
.WORD
.WORD
.WORD

Number of parameters
Status block
Print request
Subfunction
Number of copies to print
Banner page flag
Print queue name
Length of the print queue name
Address of the filename(s) to print
Length of the filename(s)
Job number

10 .
STATUS
REQUEST
SUB FUN
NUMCOP
BANNER
QUEUE
LQUEUE
FI LEN
FILENL
JOBNUM

Status block
STATUS: .BLKW
8.
Print file(s) request
REQUEST: . WORD
RQ.PRN
Required buffer space for CPRNV3
. BLKW
74 .
Subfunction value (reserved)
SUBFUN: .WORD
0
Print 1 copy of the file
NUMCOP: .WORD
1
Print with a banne~ p~ge
BANNER: .WORD
1
Print queue name
QUEUE:
;Example print queue name
.ASCII /PRO$$PROVOLUME$LAS0Q/
0
No length if using default queue
LQUEUE: .WORD
File name to print
FI LEN:
.ASCII /FILE.TYP/
Actual length of the filename
TMP
= . - FILEN
Ensure on an even boundary
.EVEN
TMP
Length of the filename
FILENL: .WORD
0
No job number needed to print
JOBNUM: .WORD

;+
; Code

,. -

START:

.MCALL

EXIT$S

MOV
CALL

#PRMBLK, RS
CPRNV3

RS => Parameter block pointer
Call Print Services to print a file
Exit the task

EXIT$S
.END

Figure 9-1:

START

Sample Call to CPRNV3

9-9

CHAPTER 10
PROSE TEXT EDITOR

PROSE is the text editor supplied with P/OS.
It
offers
facilities for entering and editing text to create documents,
source programs, and memos or similar text files.
Editing keys
on the Professional keyboard allow text manipulation. The end
user documentation describes PROSE and the PROSE user interface.
By calling the PROSE callable editor task (CET), an application
can offer the text editor for use within its own context. For
example, an electronic mail application might use the editor to
provide editing services for message creation or modification.
All the editor functions offered to the end user are available in
the callable form of the editor.
Application tasks invoke the callable editor task by calling the
CET subroutine that resides in SYSLIB. This subroutine invokes a
separate editor server task to perform the actual editing
session.
Parameters to the CET subroutine define the input and output
filename, a temporary work filename, format options, maximum line
length for text entry, and left and right margin values.
The input filename is the file to be edited.
An empty or new
file can also be created with the newfile parameter .. After
editing, the callable editor opens the output file with the
specified name to create the edited version of the file.
The CET subroutine passes the specified parameters to the
callable editor by spawning it as a task. The subroutine waits
until the editor server task terminates before returning control
to the calling application. When the editing session terminates,
the server task returns a two-word status block to the CET
routine, which in turn passes the status back to the application.
The callable editor uses EFN (event flag number) 32, so the
calling application should not use it.

10-1

PROSE Text Editor
Prior to calling the CET subroutine, the calling task should
detach from the terminal since the callable editor attaches to
the terminal during execution. After the callable editor task
exits, the calling task can reattach to the terminal. For
example, if the application is written in BASIC-PLUS-2 and
attaches the terminal for CTRL/C ASTs, it should use RCTRLC to
detach the terminal before CET is invoked.
List the name of the callable editor task in the application
installation file to make sure that it is installed when the
application task calls it.
(See Chapter 6 for details.)
Format:
CET (status, infile, inlen, outfile, outlen,
workfile, wklen, newfile, format, maxline,
in1tleft, initright, initwrap, lun)

status

A two-word integer array that returns the results
the editing session as shown in Table 10-1.

infile

A string expression that specifies
The default file type is .DOC.

inlen

An integer expression that specifies
characters in the input filename.

the

outfile

A string expression that specifies an output file.
The default file type is .DOC. If the output file is
the same as the input file, P/OS creates a new
version of the file.

outlen

An integer expression that specifies
characters in the output filename.

workfile

A string expression that specifies a temporary work
file. The editor task deletes this file on exit.

wklen

An integer expression that specifies
characters in work filename.

the

newfile

An integer expression that specifies
source file should be created.

whether

input

the

zero

Uses an existing file
specified in infile

nonzero

Creates a new file with the name
in outf ile

10-2

with

file.

number

the

of
new
name

specified

PROSE Text Editor
format

An integer expression that specifies whether or not
to retain escape sequences in the output file (see
notes).
zero

Discards formatting data

nonzero

Retains formatting data

maxline

An integer expression in the range 2 to 160 that
specifies the maximum number of characters on a line
that can be saved by a user.

initleft

An integer expression in the range 1 to 131 that
specifies the initial left margin value for a new
file.

initright

An integer expression that specifies
right margin value for a new file.

initwrap

An integer expression that specifies the default word
wrap setting for a new file.

lun

zero

Disables word wrap

nonzero

Enables word wrap

the

An integer expression that must be present
ignored by the editor task. Specify zero.

initial

but

Note:

During the editing session, the user can define margin settings
for different regions of text that result in the inclusion of
nonprinting characters, called escape sequences, in the output
file. The presence of escape sequences in files may cause errors
if the file is used with host system utilities.
If you remove
the escape sequence from a file, it will print as expected.
However, if you edit the file again, the margins will be lost.

Table 10-1:

Callable Editor - Status Return Codes

First

Second

Meaning

The editing session completed
normally.

10-3

PROSE Text Editor
First

Second

Meaning

The editing session completed
normally, and the output file it
produced contains escape sequences
indicating formatting information
(for example, margin settings).

-1

DSW code

The CET subroutine could not invoke
the server task.

-2

POSRES code

The Callable Editor Task could not
open its help file. The second status
word contains the second word of the
status block that was returned from
the execution of the HFILE routines
in POSRES.
The Callable Editor Task encountered
a problem related to the parameters
passed to it. The second status word
has a specific code:

-3

-1

The server encountered an error while
trying to receive the parameters from
the CET subroutine.

-2

The parameters contain invalid
values. For example, the initial left
margin value is greater than or equal
to the initial right margin value.

-4

RMS code

The Callable Editor Task could not
open the specified input file. The
second status word contains the RMS
error code returned in the STS field
of the FAB when the open failed.

-5

RMS code

The Callable Editor Task could not
create the specified output file. The
second status word contains the RMS
error code returned in the STS field
of the FAB when the create failed.

-6

RMS code

The Callable Editor Task could not
create the specified work file. The
second status word contains the RMS
error code returned in the STS field
of the FAB when the create failed.

10-4

PROSE Text Editor

First

Second

Meaning

-8

The server task encountered a fatal
run-time error (for example, an odd
address trap).

-9

The input file is not an RMS
sequential file.

-10

RMS code

An I/O error occurred when writing
the output file.

-11

RMS code

An I/O error occurred when performing
I/O to the work file.

-12

RMS code

An I/0 error occurred when reading
the input file.

-13

RMS code

The UDK/Set-Up file could not be
opened. The STS field of the FAB used
to access the file is returned in the
second status word.

-14

DSW code

CET could not create the dynamic
region used to hold the editor's XBUF
buffer pool.

-15

DSW code

CET could not create the address
window needed to map to XBUF.

-16

DSW code

An error occurred during a mapping
operation to access CET's XBUF
region.

Example:
10
20

Status return data
DIM StatBlk%(1%)
PRINT "Calling CET
" ! Calling the editor task
CALL CET BY REF
( StatBlk% (),
Return status block.
II If I
0 %I
No name since creating new file.
"MESG.EXC", 8%,
Name of resulting output file.
Work file used by editor.
"SY:W. FIL" 8%,
1%,
We're creating a new file.
Allow margins; discard ESCapes
0%,
Let user create long lines.
160%,
Initial margins 5, 72, word wrapped
5%, 72%, l g,.o I
placeholder - value is ignored
0%)
PRINT
PRINT "Back from editor~ Status block:"
I

10-5

&
&
&
&

&
&
&
&
&

PROSE Text Editor
PRINT "
PRINT "
END

Word 0 -" , StatBlk%(0%)
Word 1 -" , StatBlk%(1%)

10-6

CHAPTER 11
PRO/SORT

PRO/SORT is a general-purpose
This section discusses how
supports. Error messages are
sample PRO/SORT command file,

11.1

sorting utility that runs on P/OS.
to use PRO/SORT and the commands it
listed in Section 11.13.
For a
see Section 11.14.

USING PRO/SORT

Application tasks use the PROSRT routine to invoke and pass to
PRO/SORT the name of a command file containing sorting commands.
The parameter list can include the names of an input file
(containing records to be sorted) and an output file (containing
the sorted records or indices to the sorted records).

Format:
PROSRT (cmdfile, buflen,
outfile, buflen,
inpfile, buflen, status)

cmdfile

Is a string expression containing a PRO/SORT command
file specification. The default file type is ".CMD".

bu fl en

Is an integer expression that specifies the
characters in cmdfile.

outfile

Is a string expression containing a PRO/SORT output
file specification. There is no default file type.

bu fl en

Is an integer expression that specifies the
characters in outfile.

inpfile

Is a string expression containing a PRO/SORT input file
specification. There is no default file type.

11-1

number

USING PRO/SORT
bu fl en

Is an integer expression that specifies the
characters in inpfile.

status

Is a two-word integer array
information from PRO/SORT.

that

number

receives

status

In your application installation command file,
make sure to
include a FILE command for each PRO/SORT command file. Also,
include the following commands in the order shown:
INSTALL [ZZSYS]PASRES.TSK/LIBRARY/CLUSTER
INSTALL [ZZSYS]PROSORT.TSK/TASK/CLUSTER
A sample BASIC-PLUS-2 call to PRO/SORT follows:
1000 DIM STATUS%(1%)
CALL PROSRT BY REF ('TEST.CMD' I 8%, 'DATA.OUT' I 8%,
'SOURCE.INF' I 10%, STATUS%())
Programmers using MACR0-11 should note that PRO/SORT
flag #31.

11.2

uses

event

VALID RMS RECORD FORMATS

The PRO/SORT input and command files can be of variable-length or
fixed-length sequential record format,
independently of each
other. For example, the input file can have variable-length
records and the command file fixed-length records. The record
type for the output file matches that of the input file.
If the input
record size
If the input
possibilities
•

file uses variable-length records,, the maximum
(MRS) of the output file equals the input file MRS.
file uses fixed-length records,
there are two
for the output file:

If the PRO/SORT command file has WRITE commands, the size of
the output file equals the total length of all fields
specified by the WRITE commands.

If the PRO/SORT command file has no WRITE comman~s,
the
• entire
record is copied.
Therefore the input and output
record sizes are identical.
The maximum record length for a RECORD sort is 400 bytes.
The
maximum record length for a TAG sort is 1005 bytes. The maximum
record length for an INDEX sort is 1005 bytes.
The default is
PROCESS RECORD.
If you use a record that is too long, PRO/SORT
returns an appropriate error message.

11-2

PRO/SORT COMMANDS AND COMMAND FILE

11.3

PRO/SORT COMMANDS AND COMMAND FILE

The following sections describe the commands supported
by
PRO/SORT.
Where appropriate,
the corresponding PDP-11 SORT
specification lines are also described.
If you are familiar with
PDP-11 SORT,
the comparison between SORT and PRO/SORT command
syntax will be helpful.
Figure 11-2 on page 11-18 illustrates the structure of a PRO/SORT
command file.
During program execution,
the command file is
passed to the sort program and the sort is performed.
The maximum command line length is 80 characters.
Table 11-1
lists the maximum number of commands allowed in a command file.

Table 11-1:

Number of PRO/SORT Commands per Command File

Command

Maximum Number of Commands per File

COLLATE
DEFAULT
FIELD
FORCE
INCLUDE
INPUT
OUTPUT
PROCESS
SORT
WRITE

no
1
20
30
20
1
1
1
16
30

limit

*
**
**
***

Notes for Table 11-1:

Each condition in an INCLUDE line counts as an INCLUDE
command.

You can use the INPUT and OUTPUT statements in the command
file only if no input or output file is specified in the
CALL PROSRT parameter list.

***

Each field name in a WRITE statement counts as a WRITE line.

Comment statements in a PRO/SORT command file are indicated by an
exclamation point (l) or semicolon(;) as their first character.
For example:
!This is a PRO/SORT comment.
;This is an alternate form of the PRO/SORT comment.
11-3

PRO/SORT COMMANDS AND COMMAND FILE
By comparison, SORT comments are indicated by an asterisk (*)
column seven.
For example:

*This is a SORT comment.
You can nest indirect command files within the PRO/SORT command
file,
to group related commands. To invoke an indirect command
file from within the PRO/SORT command file,
use the following
format:
@f ilespec
filespec

Is the name of the indirect command file
accessed. The default file type is ".CMD".

Indirect command files can be nested as many as ten levels.

11.4

COLLATE

Use the COLLATE command to sort and output specific characters in
a new position relative to the second value specified.
For
example, you can
use
the
COLLATE
command
to
perform
country-specific collating sequences by changing the logical
ordering of a character set. COLLATE operates on CHAR fields
only.
Format:
COLLATE entity,

The format of an entity is:

value

A number or a character.
single or double quotes.

Characters must be enclosed

BEFORE

Sorts the
value.

immediately

Sorts the first value as though it were the same
second value.

first

value

11-4

before

the

second

the

COLLATE
Sorts the first value immediately after the second value.

AFTER
Notes:

•

If you use the COLLATE command before the DEFAULT command,
the collating sequence specified by DEFAULT supersedes that
specified by COLLATE. See the DEFAULT command for details.

•

A command file can contain an
commands.

11.4.1

unlimited

number

COLLATE

COLLATE Compared to SORT ALTSEQ

SORT performs alternate sequencing of records in a specification
file through the ALTSEQ command. The format of an ALTSEQ record
in SORT is:
ALTSEQ aaabbbxxxyyy ...
aaa
bbb
xxx
yyy

The octal value of a character.
The value of the character to use in the sort.
The octal value of a character.
The value of the character to use in the sort.

The PRO/SORT COLLATE command provides
function.

superset

For example, to sort commercial "at"
characters you would type:

signs

(@)

of
as

the

same

ASCII

zero

ALTSEQ 100060
Using PRO/SORT, you would type:
COLLATE "@" AS "0"

11.5

COLLATE 100 AS 60

DEFAULT

Use the DEFAULT command to set up the default collating sequence.
If you use the COLLATE command before the DEFAULT command, the
collating sequence specified by DEFAULT will supersede that
specified by COLLATE.

11-5

DEFAULT
The DEFAULT command has one of two formats.
If you want to
specify a country-specific collating sequence, use the following
command format:
Format:
DEFAULT

language

Any of the national collating sequences supported by
PRO/SORT: MULTINAT (DEC Multinational), DANISH, DUTCH,
ENGLISH, FINNISH, FRENCH, GERMAN, ITALIAN, NORWEGIAN,
PORTUGESE, SPANISH, SWEDISH, and BINARY. The default
is MULTINAT.

USER

Specifies a user-defined collating sequence.

Is an integer representing the binary value of the
eight-bit character t~ be collated at this position.
Separate integers with commas or carriage returns.

The DEFAULT USER command is equivalent to specifying individual
COLLATE commands for all 256 values of an 8-bit character.
Therefore, the list must always have 256 integer values. If you
choose to have all characters treated distinctly (no "collate
as"), the value of "n" ranges from 0 to 255. For example,
DEFAULT USER
4,3,0,1,2,5,6,7,8,9
10,11,12, ...

... 248,249
250,251,252,253,254,255
In the above example, character 4 is collated first, followed by
character 3. The remaining characters are collated normally, in
order of increasing binary value up to the last character (255).
If you want to force a character to collate as the preceding
character in the collating sequence, you must add 1000 to its
normal value. For example,
DEFAULT USER
1,2,0,3,7,8,12,1013,14,15,4, ...
In this example, character 0 is collated after characters
2. Character 13 is collated equivalent to character 12.

You can specify only one DEFAULT command in the command file.
11-6

and

FIELD
11.6

FIELD

The FIELD command assigns a symbolic name to a positional range
within an input record. For example, you could assign the field
name "ZIP" to columns 5' through 9 in each record, the field name
"Address" to characters 10-25, and so on. You can define up to
20 fields with FIELD commands.
Once the FIELD command has assigned a symbolic name to a field,
other PRO/SORT commands reference that field by field name only.
You must define a field before it can be referenced by other
PRO/SORT commands.
Format:
FIELD fname datatype start end

fname

A field name (must be a character string).

datatype

One of the following six datatypes:
CHAR

Specifies character data. The field width for
this data type is equal to the number of
characters.

SINT

The
Specifies signed binary integer format.
field width must be given as two bytes per
number.

UNSINT

Specifies unsigned binary integer format.
The
field width must be given as two bytes per
number.

DBLINT

Specifies double precision
binary
integer
format.
The field width must be given as four
bytes per number.

SPFP

Specifies single precision floating point. The
field width must be given as four bytes per
number.

DPFP

Specifies double precision floating point. The
field width must be given as eight bytes per
number.

start

Is an integer representing the starting
of the field within the record.

end

Is an integer representing the ending column number
the field within the record.

11-7

column

number
of

FIELD
Figure 11-1 shows how PRO/SORT interprets bytes as they occur
the input data stream.

Bit

CHAR
8
( 1 byte/char.)

Bit
SINT
(2 bytes)

Bit
Byte 1

Byte 2

Bit

Bit
UNSINT
(2 bytes)

Byte 2

Byte 1

Bit
DB LINT
(4 bytes)

B:te 2

B:te 1

B te 4

B te 3

Bit

B:te 2

B:te 1

B te 4

B te 3

Bit

Bit
DPFP
(8 bytes)

Figure 11-1:

Bit

Bit
SPFP
(4 bytes)

B_y_te 2

B_yte 1

Byte 4

B_yte 3

B_yte 6

B_yte 5

Byte 8

B_yte 7

Mapping of Bytes to Fields in Input Data Stream

11-8

FIELD

Notes:
•

For both the SPFP and DPFP data types, the sign appears in
bit 16
(byte 2), the exponent appears in bits 8 through 15
(bytes 1 and 2), and the mantissa appears in the remaining
bits.
This conforms to the standard PDP-11 data type
convention.

•

For SINT, UNSINT, DBLINT, the most significant bit is 16, 16,
or 32,
respectively.
For SPFP and DPFP, bit 15 is the most
significant bit of the exponent and bit 7 is the most
significant bit of the mantissa.

11.6.1

Pseudo-Fields RRN and RFA

Two pseudo-fields are predefined as part of PRO/SORT:
relative
record number (RRN) and record file address (RFA).
The relative
record number is defined as if your command file included the
line:
FIELD RRN SINT x x+l
where x is the pseudo starting column of the field.
This
two-byte number identifies the record's position in the input
file.
Use RRN to perform random indexing of fixed length
sequential files.
The record file address of a record is defined as if your command
file included the line:
FIELD RFA CHAR x x+S
where x is the pseudo starting column of the field.
This
6-character identifier provides the block and byte offset of the
record in the input file.
RFAs assist in the random access
within a file that contains either fixed or variable length
records. You can use RFA access to retrieve records randomly.
Use RRN and RFA in any other PRO/SORT command to obtain pointers
to desired records.
For example, the following commands would
select the first 19 records in the input file and then write the
each record's location (RFA) and key (KEYFIELDNAME) to the output
file.
INCLUDE RRN < '20'
FIELD KEYFIELDNAME CHAR 1 10
WRITE RFA, KEYFIELDNAME

11-9

FORCE
11.7

FORCE

Use the FORCE command to force any record containing a particular
field (or a field with a particular value) to a specified
position in the collating sequence.
Format:
FORCE fname TO val IF val

f name

The field name (must be a character string).

val

A number or a character.
single or double quotes.

Characters must be enclosed

You can use FORCE only on CHAR fields. While COLLATE affects all
fields equally, FORCE operates only on the first character of the
specified field. FORCE IF operates on that field only if its
current value is equal to the value specified in the IF clause of
the command.
For example, you could sort an input containing zip codes so that
all zip codes appear at the top of the output file:
FORCE ZIP TO "0"
You could also sort such an input file so that only the zip codes
beginning with 5 appear at the top of the list; all other zip
codes would be sorted as usual:
FORCE ZIP TO "0" IF "5"
You can specify up to 30 FORCE commands in the command file.

11.7.1

FORCE Compared to SORT F

With the SORT F field record specification, you specify the
column to be forced and the character that column should be
forced to. An optional trigger character specifies that the
force should not occur unless the indicated column contains that
character.
The SORT "F" field specifier can also
logically
combine
conditions through a FORCE command. PRO/SORT cannot do this.
For example, using SORT to sort all X characters in column 50
if they were Ys, you would type:
F

50XY
11-10

FORCE
To perform a similar sort in PRO/SORT, you would type:
FIELD NAME CHAR 50 59
FORCE NAME TO 'Y' IF 'X'

11.8

INCLUDE

Use the INCLUDE command to sort and write to the output file only
records containing fields that match certain conditions.

Format:
INCLUDE condition, ...
The format of a condition is:

fname operator
The format of an operator is:
(equal to)
(not equal to)
(less than)
(less than or equal to)
(greater than)
(greater than or equal to)
f name

A field name (must be a character
single or double quotes).

string

enclosed

For example, to select and sort all records whose in an input
file whose zip code field, ZIP, begins with 0, you could use the
command:
INCLUDE ZIP

< "10000"

Fields of data type CHAR can only be compared to other CHAR
fields.
Numeric fields can be compared to any other numeric
fields.
If a constant is specified along with a numeric field,
it is assumed to be numeric.
When you specify more than one condition with a single INCLUDE
command, PRO/SORT will combine the conditions logically with AND.
Only records that meet all the
INCLUDE line's conditions will
appear in the output file.

11-11

INCLUDE
You can specify up to 20 INCLUDE conditions in a command file.
When you specify more than one condition with multiple INCLUDE
lines, PRO/SORT will combine the conditions logically with OR. A
record need only match one of the INCLUDE lines to appear in the
output file.
For character fields, INCLUDE can also be used as follows,
but
only in the case of an EQ or NE comparison.
It cannot be used
for LT, LE, GT, or GE. The following examples will illustrate
this special case.
INCLUDE fname = 'XYZ ... '
Include any record that has a field starting with 'XYZ'.
INCLUDE fname

= ' ... XYZ'

Include any record that has a field containing 'XYZ'.

11.8.1

INCLUDE Compared to SORT 0 and

SORT and PRO/SORT use the same logical relationship tests to
determine whether an output file will omit or include a given
record. When you use the SORT I specification, you may either
omit or include portions of the input file to be sorted.
PRO/SORT provides one way to achieve either result through an
INCLUDE command.
For example, using SORT to omit all records with column 10 to
equal to XYZZY you would type:
0 C

14EQXYZZY

With PRO/SORT, you would type:
FIELD PLUGH CHAR 10 14
INCLUDE PLUGH NE "XYZZY"
or:
INCLUDE PLUGH <> "XYZZY"

11-12

INPUT AND OUTPUT

11.9

INPUT AND OUTPUT

The INPUT command specifies which input file contains the data to
be sorted.
The OUTPUT command specifies which file the sorted
records (or indices to sorted records,
for the PROCESS INDEX
command) are to be written to. You can use the INPUT and OUTPUT
statements in the command file only if no input or output file is
specified in the CALL PROSRT parameter list.
Format:

INPUT filespec
OUTPUT f ilespec
filespec

A string that
written to.

specifies

the

file

being

sorted

terminal

screen

The PROCESS command specifies whether PRO/SORT uses a
TAG sort.

RECORD

You can specify that file be output to your
using TI: as the filename.

11.10

PROCESS

Format:
PROCESS

For a RECORD or TAG sort, the PROCESS command operates like the
/PR switch in SORT.
For an INDEX sort, the PROCESS command
operates like the SORTA address routing sort.
In a RECORD sort, PRO/SORT manipulates actual records.
Use a
RECORD sort for small sorting jobs. In a TAG sort, PRO/SORT
manipulates pointers to records.
The TAG option
can
be
significantly faster; use it for longer records. Switch to TAG
if RECORD fails.
The default is PROCESS RECORD.

11.11

SORT

The SORT command specifies the key fields which will be used to
reorder the records in the output file.
Specify the key fields
11-13

SORT
in the order of their importance to the sort (primary, secondary,
etc.).

Format:
SORT

field, . ..

The format of a field is:
f name

f name

The field name (must be a character string).

A leading plus or minus sign before the field name controls the
order of the sort for the field.
A leading plus sign indicates
that the sort of that field should be performed in ascending
order.
A leading minus sign indicates that the sort should be
performed in descending order.
To specify multiple key fields, you can use more than one SORT
command or combine more than one key field on a line. Up to 16
key fields can be specified in a command file.

11.11.1

SORT Compared to SORT N and 0

Both SORT and PRO/SORT permit key structures (primary, secondary,
etc.).
However, with SORT you can specify a maximum of 10 key
fields.
SORT uses N ("normal") and O ("opposite") in column 7 of
the specification file to indicate ascending or descending sort
per key.
PRO/SORT uses the plus (+) and minus (-) signs.
For example, using SORT to sort the primary key ascending from
columns 1 to 5,
secondary descending from 34 to 37, you would
type:
FNC
FOC

1
34

5
37

Using PRO/SORT, you would type:
FIELD PRIMARY CHAR 1 5
FIELD SECONDARY CHAR 34 37
SORT +PRIMARY, -SECONDARY

11-14

WRITE

11.12

WRITE

The WRITE command creates an output file with a different
arrangement of fields from the input file.
You can use the WRITE
command to omit a field from the output file, for example, or you
can retain all the fields but output them in a new order.
Format:
WRITE fname, ...

f name

A field name (must be a character string).

You can specify up to
command file.

11.12.1

fields

with

WRITE

commands

the

WRITE Compared to SORT D

Both SORT and PRO/SORT permit the creation of an output file
whose records differ in field order from the input file.
In
SORT, for example, if the input consists of a name in columns 1
to 19, address in 20 to 39, and zip in 40 to 44, the output
records could be rearranged in the order <zip>, <address>, <name>
by typing:
FDC 1
FDC 20
FDC 40

19
39
44

Using PRO/SORT, you would type:
FIELD NAME CHAR 1 19
FIELD ADDRESS CHAR 20 39
FIELD ZIP CHAR 40 44
WRITE ZIP, ADDRESS, NAME

11.13

PRO/SORT ERROR CODES

When PRO/SORT returns control to your program, the first element
of the status array (element 0) contains one of the following
codes:
1
-1

-2

normal successful completion
error occurred in processing
could not invoke PRO/SORT

PRO/SORT is a separate task image on

11-15

the

P/OS

system.

PRO/SORT ERROR CODES
could not be invoked, the spawn has probably failed.
Check that
you have listed the following lines (in the order shown)
in the
application installation file:
INSTALL [ZZSYS]PASRES.TSK/LIBRARY/CLUSTER
INSTALL [ZZSYS]PROSORT.TSK/TASK/CLUSTER
If an error occurred in processing, the second element
status array (element 1) contains an error code.

the

A code that is greater than zero indicates a PRO/SORT
error. Refer to the PDP-11/SORT Reference Manual.

internal

A code that is less than zero indicates an error detected by the
PRO/SORT task.
Table 11-2 lists the error codes (decimal) and
descriptions.

Table 11-2:

Decimal
Error Code

PRO/SORT Error Codes

Description of Error Condition

-1

A command in the sorting command file contains an
invalid parameter, for example a string parameter
where a numeric parameter is needed.

-2

The sort command file contains a line that is not
recognized as a valid sort command.

-3

Can't open the specified sort command file.

-4

An INCLUDE command describes a relation between
two fields of different data type.

-5

Two FIELD commands use the same name for their
field.

-6

Multiple INPUT commands.
Either the parameter
list and the command file both contain an INPUT
command or the the command file contains more than
one.

-7

Multiple OUTPUT commands. Either the parameter
list and the command file both contain an OUTPUT
command or the the command file contains more than
one.

11-16

PRO/SORT ERROR CODES
Decimal
Error Code

Description of Error Condition

-8

A command has spurious text following the normal
end of the command.

-9

A fatal error has been found in the logic of the
PR.0/SORT utility. Call the Hot Line.

-10

Too many FIELD commands have been given.

-11

Too many FORCE commands have been given.

-12

Too many INCLUDE commands have been given.

-13

Too many SORT commands have been given.

-14

Too many WRITE commands have been given.

-15

Ellipses were used with a relational operator
other than = or <>.

-16

No INPUT command was found in the command file
stream.

-17

No OUTPUT command was found in the command file
stream.

-18

A command omitted a required parameter.

-19

FORCE commands may only be used on fields of type
character, but a FORCE command was found in
violation of this.

-15

The PRO/SORT data file be opened
(SYSDISK:[ZZSYS]PROSORT.SYS).

-21

The input file is empty.

-22

Can't open the input file.

-23

Can't open the output file.

-24

The total size of all key fields added up
large.

-25

The user's command file pool has too
of indirect command files.

levels

11-17

many

too

PRO/SORT ERROR CODES

Decimal
Error Code

Description of Error Condition

-26

A field name that does not yet exist has been
referred to.

-27

More than one PROCESS command in file.

-28

Too few characters specified in the DEFAULT USER
command.

-29

An input record larger than 1005 bytes was found.

-30

Insufficient disk space for temporary files.

-100
to
-5200

An internal error reported by the PASCAL run-time
system used by PRO/SORT.

11.14

PRO/SORT EXAMPLE

Figures 11-2 through 11-5 show several files associated with a
sorting example.
Figure 11-2 shows the PRO/SORT command file.
It is designed to sort the information in the input file
INPUT.DAT
(Figure 11-3),
rearrange it, and output it in a new
order to the output file OUTPUT.DAT (Figure 11-5). The indirect
command file FIELDS.CMD (Figure 11-4) is invoked by the PRO/SORT
command file.
Command file for sorting the INPUT.DAT file.
Define the Fields:
@FIELDS
Set up sorting parameters:
INPUT INPUT.DAT
OUTPUT OUTPUT.DAT
SORT Type, LastName
INCLUDE Type <> "Heral"
FORCE Type to "0" if "V"
WRITE Type, Space, FirstName, LastName

Figure 11-2:

Sample PRO/SORT Command File

11-18

PRO/SORT EXAMPLE
Name2 Hxyzzy
Fake
Fake
Name
Hardy
Dick
Tracy Hero
Mary
Worth Normal
Clark Kent
Hero
Peter Parker Herol
Luther Villain
Lex
Green Hornet Hero
Lane
Lois
Heroine
Bruce Wayne Herol
King
Tut
Villain
Zod
Gen.
Villain
Scooby Doo
Herol
David Banner Hero
Perry White Normal
Comm. Gordon Normal
Mary
Jane
Normal
The
Joker Villain
Miss
Piggy Normal
Darth Vader Villain
Leia
Organa Heroine

Figure 11-3:

Sample Input File INPUT.DAT

The PRO/SORT command file begins with two comment lines:
Command file for sorting the INPUT.DAT file.
Define the Fields:
The first comment identifies the PRO/SORT command
second introduces the next command line, which
executes the indirect command file FIELDS.CMD to
fields in the input file:

file.
The
invokes and
define the

@FIELDS
FIELDS.CMD
Field specification for the input file INPUT.DAT
Field FirstName Char 1,7
Field LastName Char 8,14
Field Type Char 15,21
Field Space Char 7,7
------------------------------------------------------------------------------------~

Figure 11-4:

Sample Indirect Command File FIELDS.CMD

11-19

PRO/SORT EXAMPLE
FIELDS.CMD defines each field in INPUT.DAT and assigns it a
symbolic name.
The field of characters 1-7 receives the field
name FirstName; the field of characters 8-14 receives the field
name LastName, and so on.
Once PRO/SORT has executed this
indirect command file, the program can refer to any field in the
input file by the field name alone.
The next line in the PRO/SORT command file is another comment:
Set up sorting parameters:
This line identifies the subsequent commands as those which set
up the sorting parameters for the ~ata file.
The sorting
parameters determine how fields in the data file will be sorted.
The first sorting parameter specifies the input file:
INPUT INPUT.DAT
It identifies INPUT.DAT as the file containing the data to be
sorted. The next sorting parameter specifies the output file:
OUTPUT OUTPUT.DAT
It identifies OUTPUT.DAT as the file to which the sorted
will be written.

records

If INPUT.DAT and OUTPUT.DAT are specified in the CALL PROSRT
parameter list,
they can't be specified also in the PRO/SORT
command file.
The next sorting parameter is a SORT command:
Sort Type, LastName
It specifies which key fields in the input file are pertinent to
this sort,
and in what order they will be sorted. The symbolic
names Type and LastName have already been assigned by the
indirect command file FIELDS.COM. They are now identified as the
primary and secondary fields,
which will be sorted in the
default, or ascending, order.
The next line is an INCLUDE command:
Include Type

<> "Herol"

It specifies which records will be sorted and written to the
output file.
In this case, only records whose field "Type" is
not equal to "Herol" will be handled by PRO/SORT.
Records with
the Type "Herol" will be ignored.

11-20

PRO/SORT EXAMPLE
The next line is a FORCE command:
Force Type to "0" if "V"
It specifies that any record with a field type that begins with V
should be sorted and written to the top (0) of the output file.
The last line is a WRITE command:
Write Type, Space, FirstName, LastName
Using this command, the programmer could have omitted any of the
fields from the output record.
Instead,
the programmer has
retained all fields but specified that they appear in the new
order.
PRO/SORT
When this program is run,
OUTPUT.DAT.
(See Figure 11-5.)
Villain The
Villain Lex
Villain King
Villain Darth
Villain Gen.
Fake
Hardy
Hero
David
Green
Hero
Hero
Clark
Hero
Dick
Heroine Lois
Heroine Leia
Hxyzzy Fake
Normal Comm.
Normal Mary
Normal Miss
Normal Perry
Normal Mary

Figure 11-5:

creates

Joker
Luther
Tut
Vader
Zod
Name
Banner
Hornet
Kent
Tracy
Lane
Organa
Name2
Gordon
Jane
Piggy
White
Worth

Resulting Output File OUTPUT.DAT

11-21

the

output

file,

APPENDIX A
APPLICATION DISKETTE BUILDER ERROR MESSAGES

The Application Diskette Builder displays an error message if it
cannot continue building a diskette or if it finds an error in
the installation command file.
In the latter case, ADB may
respond with more than one error message for the same error.
For
example, if the RUN command has an error, then two error messages
result:
Invalid task name
A 'RUN' line must be present.

The normal ADB error messages are listed in alphabetic
Section A.1.

order

Some error messages report conditions that you might not be able
to resolve.
These error messages indicate that a serious error
has occurred.
In most cases, the errors are the result of a
failed file operation.
These errors are listed in Section A.2
and appear in the following form:
ADB<xxx,yyy> - Message text

The values xxx and yyy represent error status numbers.
These
numbers correlate to a specific error, which is generally
described by the message text.
These values are positive.
Look
up the error status code in the PRO/RMS-11 manual set.
If you
cannot determine the cause of the error,
submit a Software
Performance Report (SPR) to DIGITAL.
Record on the SPR the error
message exactly as it was displayed on the terminal,
including
the values represented here as <xxx,yyy>.

A-1

ADB NORMAL ERRORS
A.1

ADB NORMAL ERRORS

A 'NAME' line must be present

The application installation file does not contain a
name" line.

NAME

"menu

A NAME "menu name" must be present in
each
application
installation file.
The NAME "menu name" line assigns a default
name to this application. Correct the application installation
file and restart ADB;
A 'RUN' line must be present

The application installation file does not contain a RUN taskname
line.
The application installation file must have, as the last line of
the file, a RUN taskname line. When the application is invoked,
P/OS executes the task listed in the RUN line.
Correct the
application installation file and restart ADB.
An 'INSTALL/TASK' line must be present

the application installation file does not contain
INSTALL line, or the INSTALL line(s) contain syntax errors.

Ei~her

INSTALL lines list all the programs that P/OS must install to run
this application. Correct the application installation file and
restart ADB.
At least one 'FILE' line must be present

Either the application installation file does not contain a
line or the FILE line(s) contain syntax errors.

FILE

FILE lines list all the files that must be copied to the target
diskette.
Correct the application installation file and restart
ADB.
Copy aborted

An error occurred while ADB was copying files.

A-2

ADS NORMAL ERRORS
Error <xxx,yyy> creating directory <dirname>.

ADB could not create a directory specified in the FILE or REQUIRE
command line.
Check the installation file and try again.
Invalid number or too large.

The number of blocks
entered incorrectly.

-- Try again.

allocate

for

checkpoint

file

was

Invalid switch for this command line

The application installation file has an invalid switch.
Correct the application installation file and restart ADB.
Invalid syntax for this command

The
application
installation
characters at the end of a line.

file

contains

unrecognized

Correct the application installation file and restart ADB.
Invalid task name

A line in the application installation
filenames lists an invalid task name.

that

accepts

task

Task names can be no more than 6 characters long.
application installation file and restart ADB.

Correct

the

/LIBRARY and /COMMON switches
INSTALL lines

switches

must

file

precede

/TASK

An INSTALL/TASK line in the application installation file
before an INSTALL/LIBRARY or INSTALL/COMMON line.
Correct the application installation file and restart ADB.

A-3

occurs

ADB NORMAL ERRORS
Not enough contiguous space on the volume for <filename>

The file <filename> requires contiguous space and could
copied to the remaining free space on the diskette.

not

use a different diskette with more free space on it, or try to
use the same diskette by changing the order in which files are
copied.
To reorder the which file copying, list task images and files
that are built to reside in contiguous or adjoining blocks first
in the FILE lines of the application installation file.
After
contiguous files are copied, the remaining fragmented space can
be used to store files that do not require a contiguous area.
Not enough room on this diskette for the application directory

The main ADB screen is displayed.
Not enough space left on the diskette for <filename>

During the copy operation the diskette filled up before the
<filename> could be copied to it.

file

Start over with another diskette.
Only one 'ASSIGN HELP' line is allowed

The application installation file contains multiple
lines. Only one line of this type is permitted.

ASSIGN

HELP

The ASSIGN HELP line assigns a default help definition file to
this application. Correct the application installation file and
restart ADB.
Only one 'ASSIGN MENU' line is allowed

The application installation file contains multiple
lines. Only one line of this type is permitted.

ASSIGN

The ASSIGN MENU line assigns a default menu definition file to
this application. Correct the application installation file and
restart ADB.

A-4

ADB NORMAL ERRORS
Only one 'NAME' line is allowed

The application installation file contains
name" lines.

multiple

NAME

"menu

Only one line of this type is permitted. The NAME "menu name"
line assigns a default menu name to this application. Correct
the application installation file and restart ADB.
Only one 'RUN' line is allowed

The application installation file contains multiple RUN
lines.

taskname

The application installation file must have, as the last line of
the file, a RUN taskname line. When the application is invoked,
P/OS executes the task listed in the RUN line.
Correct the
application installation file and restart ADB.
Please enter a valid alphanumeric name

Either no characters or invalid characters were entered.
The filename is invalid

A filename in the application installation file is not a
PRO/RMS-11 file specification.

correct

Correct the application installation file and restart ADB.
The frame identifier is incorrect

A frame identifier (frameid) in the application installation file
is not in the correct format.
Check the help definition file to make sure you are spelling
frameid
correctly.
Correct
the frame identifier in
application installation file and start again.

the
the

The Installation file command lines are in an incorrect order

The application installation file contains lines that are not
correct order.

Review the application installation file format and
errors in the file. Restart ADB.

the

A-5

correct

ADB NORMAL ERRORS
The string must be quoted and within length boundaries

A string, such as the "menu name" string in the NAME line, is not
surrounded by quotes, or it contains too many characters.
See the description of string syntax for strings appearing in the
offending
command
in Chapter 6.
Correct the application
installation file and restart ADB.
The volume name is invalid

The volume name in a MOUNT line is not a
alphanumeric string.
A volume name in
include a colon(:).

1- to 12-character
a MOUNT line cannot

Correct your volume name and try again.
This command is invalid

An invalid command is
file.

listed

the

application

installation

Check the list of valid commands in the section on application
installation files.
Correct the application installation file
and restart ADB.
Unable to bad block the diskette in <drive>

The diskette in the named drive could
blocks as part of the initialization.

not

Try another

checked

for

bad

Replace the diskette and try the operation again.
Unable to locate the file <filename>

The application installation file could not be located in
the current directory or in the specified new directory.
Make sure the installation file is in the specified
Specify the correct application installation file.

A-6

either

directory.

ADB SERIOUS ERRORS
A.2

ADB SERIOUS ERRORS

ADB<xxx,yyy> - Cannot access menu file
ADB menu file could not be accessed.
Try running ADB again.
submit an SPR.

If you receive the

same

error

message,

ADB<xxx,yyy> - Error creating this directory -- Try another
The destination di rectory could not be cre-ated on the target
diskette, possibly because the diskette has bad blocks or format
errors. The error code corresponds to either a PRO/RMS-11 error
code or an I/O error code.
Either try another directory, or restart ADB with a new diskette.

ADB<xxx,yyy> - Error while gathering additional user directories
An error occurred
directories.

while

ADB

was

gathering

additional

user

Submit an SPR.

ADB<xxx,yyy> - RMS error accessing the installation file
The application installation file could not be opened because
a record access error.

Check the diskette to make sure it contains an installation
command file.
If it does, make sure you have named the
installation command file with the .INS or .INB file type.
Look
up the PRO/RMS-11 I/O error codes in the PRO/RMS-11 manual set,
and restart ADB.
If you receive the same error message,
submit
an SPR.

ADB<xxx,yyy> - RMS error connecting to <filename>
ADB could not access the file listed as <filename>.
Look up the PRO/RMS-11 I/O error codes in the PRO/RMS-11 manual
set.
Try running ADB again.
If you receive the same error
message, follow the procedures for submitting an SPR.

A-7

ADB SERIOUS ERRORS

ADB<xxx,yyy> - RMS error creating <filename>
ADB could not create the file listed as <filename>.
Look up the PRO/RMS-11 I/O error codes in the PRO/RMS-11 manual
set.
Try running ADB again.
If you receive the same error
message, follow the procedures for submitting an SPR.

ADB<xxx,yyy> - RMS error opening <filename>
ADB could not open the file listed as <filename>.
Look up the PRO/RMS-11 I/O error codes in the PRO/RMS-11 manual
set.
Try running ADB again.
If you receive the same error
message, follow the procedures for submitting an SPR.

ADB<xxx,yyy> - RMS error while reading <filename>
ADB could not read the file listed as <filename>.
Look up the PRO/RMS-11 I/O error codes in the PRO/RMS-11 manual
set.
Try running ADB again.
If you receive the same error
message, follow the procedures for submitting an SPR.

ADB<xxx,yyy> - RMS error while writing to <filename>
ADB could not write to the file listed as <filename>.
Look up the PRO/RMS-11 I/O error codes in the PRO/RMS-11 manual
set.
Try running ADB again.
If you receive the same error
message, follow the procedures for submitting an SPR.

ADB<xxx,yyy> - Unable to access directory listing
The directory of the specified device could not be
fatal error message is displayed.

obtained.

Check to be sure the directory resides on the specified device
and that the device is properly loaded. Try the operation again.
If you receive the message again, submit an SPR.

A-8

APPENDIX B
FDT ERROR MESSAGES

FDT displays two
internal errors.

types

error

messages:

user

errors

and

User error messages are intended to be self-explanatory. If you
need
clarification
or
advice, this appendix contains an
alphabetic* list of user error messages and possible solutions.
A symbol enclosed in left and right angle brackets (< and >)
represents a field name, frame identifier, or file specification
that FDT has copied from your command or retrieved from stored
information. Internal error messages indicate that a serious
error has occurred in FDT processing. In most cases, it results
from a file operation failure.
Error messages appear in the
following form:
FDT<xxx,yyy> - Message text.

The values xxx and yyy represent PRO/RMS-11 I/O error status
numbers and correlate to a specific error which is generally
described by the message text. When you see an internal error
message, do the following:
1.

Record the error message exactly as it was displayed on your
terminal, including the numbers enclosed in angle brackets.

Exit FDT (enter the SAVE or EXIT command).

Invoke FDT and use the REPORT command to
listing of the file.

The error messages

~re

obtain

sorted by text, not symbols.
B-1

hardcopy

FDT Error Messages
4.

Look up the error status code in the PRO/RMS-11 manual set.
If you cannot determine the cause of the error, submit a
Software Performance Report (SPR) to DIGITAL.
Include a
detailed description of the user-FDT dialogue up to and
including the error message, and the report file.

8.1

USER ERRORS

Action form deleted.

An option description line was deleted or the keyword in an
option description line was divided onto two lines on a Display
form. The Action form for the option description line was
deleted by FDT.
An Action form is deleted if the option it
describes no longer exists.
If you deleted the option description line, create
When you create the new one, an Action form will
it. If you divided a keyword onto two lines on the
enter it on only one line. A new Action form will

another one.
be set up for
Display form,
be set up for

it.

<Frame-id> already exists - name of frame unchanged.

The NAME command specified a previously assigned frame identifier
as a new frame identifier.
Use the LIST or REPORT commands to check the
frame identifiers.

names

existing

<Frame-id> already exists - no new frame created.

The frame identifier of an existing frame was specified in an ADD
command.
Use the MODIFY command to alter the existing frame or
enter a unique frame identifier.
<filename> already saved.

The current file was not changed, so no new copy of the file
been created. Control returns to host system command level.

B-2

has

USER ERRORS
Default option is not in the range 0 to xx.
The default option field on a Profile form has a value outside
the valid range. The valid range is zero to xx, where xx is the
total number of option description lines on the Display form.
This error condition is detected after use of the CONVERT
command.
Use the MODIFY command to alter the Profile
value in the range.

form

contain

Default option specified with no options.
A value was specified in the default option field on the Profile
form, but no options were listed on the Display form. This error
condition is detected after use of the CONVERT command.
Create two or more options in a Display form. Check to make sure
the default option field on the Profile form is correct.
<frame-id> does not exist.
A frame identifier was specified with the Modify, Name, or DELETE
command, but it does not exist in the current file.
Check for typograhical errors in the frame identifier.
To
display the list of frames contained in the current definition
file, press RETURN. Then use the LIST command to display the
frame identifiers.
Enter "H", "M• or "S" to select a file type, or a return.
A character other than H, M, or S was entered in response to
previous prompt.

the

To select a file type, respond to the prompt by entering the
single· character in parentheses in the message. The file type
determines the type of frames that may be created and stored in
the current definition file. To specify a new definition file,
press RETURN. The prompt Filename: will be displayed.
Field <name> invalid in action form <number>.
The named field, which is on the Action form with
number, does not contain valid information.
detected after use of the CONVERT command.

B-3

the indicated
This error is

USER ERRORS
The most
Use the MODIFY command to fix the specified field.
likely reason for this error message is a blank value for a
required field.
Field <name> invalid in display form.

The named field, which is on a Display form, does not contain
valid information.
This error is detected after use of the
CONVERT command.
Use the MODIFY command to fix the specified field.
The most
likely reason for this error message is a blank value for a
required field.
Field <name> invalid in profile form.

The named field, which is on the Profile form, does not contain
valid information.
This error is detected after use of the
CONVERT command.
Use the MODIFY command to fix the specified field.
The most
likely reason for this error message is a blank value for a
required field.
File <filename> is empty.

DELETE command is invalid.

An attempt was made to delete a frame
frame is deleted.

exist.

There are no frames in a file that was to be saved. The file
not saved and control returns to host system command level.

File <filename> is empty.

that

doesn't

File not written.

Make sure the correct file was specified or use the QUIT
to leave FDT after opening an empty file.
File <filename> is empty.

command

MODIFY command is invalid.

The MODIFY command was typed, but no
modification.

B-4

frames

are

available

for

USER ERRORS

File <filename> is empty.
The NAME command was
rename.

NAME command is invalid.

typed,

but

frames

are

available

File <filename> is not an FDT source file - try again.
The specified file is not a valid FDT definition file.
prompt you again for the filename.

FDT

will

File <filename> not found.
Either the specified file is not a valid FDT definition file,
the file does not exist.

Create a new FDT definition file using the
press RETURN to enter a different filename.

specified

name

No frames written to converted file.
The CONVERT command specified a definition file but it contains
no valid frames that may be converted. All frames in the current
definition file contain errors.
Fix the errors in the frames, and then use the CONVERT command to
convert the file.

Frame identifier may only have alphanumeric characters.
The specified frame identifier contained characters that are
in the ASCII alphanumeric character set.
Frame identifiers must be specified by ASCII
characters only (A through z and 0 through 9).

not

alphanumeric

Frame <frame-id> not converted.
The named frame was not converted because it contained invalid
information or it lacked required information in one or more
fields.
Use the MODIFY command to fix the listed errors.
CONVERT command to convert the frames.

B-5

Then

use

the

USER ERRORS
Invalid command.

Enter HELP for a list of commands.

An invalid command was entered.
Review the list of valid commands in the FDT documentation,
type HELP to display the list of valid commands.

Invalid file specification <filename>.
An error was made in the format of the file specification.
Check for typographical errors in the file specification and
retype if necessary. Refer to the Tool Kit User's Guide or your
host system documentation for
more
information
on
file
specifications.
Invalid identifier.
A frame identifier was specified with more than eight characters,
or with characters that are not from the ASCII alphanumeric
character set.
Enter a frame identifier with no more than eight characters in
the ASCII alphanumeric character set (A through z and 0 through
9) •

Keyword deleted.
The keyword for the option description line that was just altered
was deleted. Keywords are deleted whenever the keyword no longer
matches the option description line.
Enter a new keyword for the new option description line.
Keyword does not match description line.
The value entered in the keyword field on an Action form is
invalid.
It does not match any segment of contiguous characters
in the option description line on the Display form.
You must either leave the option keyword field blank or
unique, matching keyword in the keyword field.

B-6

enter

USER ERRORS

Keywords not unique for options xx and yy.
Two matching keywords were specified for the named options.
Either keyword xx is a subset of keyword yy or vice versa, or
they are identical.
For example, "cat" is a subset of "catch"
and the number 1 is a subset of the number 10. This error
condition is detected after use of the CONVERT command.
Alter the keyword for one or both of the specified options.
Do
not delete an option description line on the Display form to
alter it.
If you delete the line, the Action form for the option
will be deleted.

No action form found for option xx.
An Action form was not filled in for the named option.
This
error condition is detected after use of the CONVERT command.
Use the MODIFY command to fill in the Action form.

No frames to report.
A report on the current definition file was
file contains no frames.

requested,

but

the

Review

the

Make sure that the correct file is open.

No matching option found.
A nonexistent option was specified in the ACTION command.
Check for typograhical errors in the command
list of options on the Display form.

line.

No new options found.
The ACTION NEW command
assigned actions.

was

specified,

Use ACTION ALL or ACTION
options.

option-number

B-7

but

all

options

modify

the

were

desired

USER ERRORS
No option lines defined.

The ACTION command was used but no option description lines
specified.

were

use the DISPLAY command to enter the option description lines,
and then use the ACTION command to assign actions to each option.
No value entered for required field.

This is a warning message indicating that the previous
requires a value before this frame can be converted.

field

Determine what the value for the previous field should be and
enter that value in the field before attempting to convert the
file.
Not enough room to insert a line.

There is not enough room in the field to open a new line.
Use the ARROW keys, or the NEXT and PREV FIELD keys
editor keypad to make room.

the

FDT

You have responded incorrectly to a prompt requiring a Yes or
response.

Please answer Yes or No.

Respond with a Y for Yes, or an N for No.
Please enter FULL, TOP, BOTTOM.

The value entered for the field is not one of
listed.

the

valid

values

You cannot proceed to the next field without entering a correct
response.
Enter Full, Top, or Bottom to specify the display
location of a help text frame.
Initially, FULL is the value in
the location field.
To replace FULL or an entered value, use the
ARROW keys to position the cursor on the F, then press the DELETE
WORD key on the FDT keypad and enter a correct value.

B-8

USER ERRORS
Please respond with an "M" or "T".

Before you can add a frame in a help definition file, you must
specify whether you are adding a help menu or a help text frame.
Enter an "M" to add a menu, a "T" to add a text
carriage return to display the file command prompt.

frame,

Value must be between 0 and 12.

A value was entered for the default option field but the value is
neither an integer between zero and 12, nor a blank.
You cannot proceed to the next field without entering a correct
response.
The maximum number of options on a menu is 12. You
can assign any one of the 12 options to be the default option.
If you assign an option to be a default, when the menu is
displayed the selector will rest by the default option. Enter a
valid numeric value for the field or leave it blank.

8.2

INTERNAL ERRORS

FDT<xxx,yyy> - Cannot create output file.

The output file specified in the CONVERT
written because of a processing error.

command

cannot

FDT<xxx,yyy> - Cannot create temporary file.

The file specified cannot be opened because of a processing erro:
in the file manager.
FDT<xxx,yyy> - Cannot display graphics frame.

A processing error occurred while FDT was attempting to display
form.
FDT<xxx,yyy> - Cannot read frame <frame-id>.

An attempt to read the specified frame failed.

B-9

INTERNAL ERRORS
FDT<xxx,yyy> - Cannot read frame from temporary file.

A a record is not accessible to the MODIFY command.
FDT<xxx,yyy> - Cannot read record.

A record in the current file cannot be accessed for conversion.
FDT<xxx,yyy> - Cannot read record <frame-id> from temporary file.

The named frame cannot be converted because of a processing
error.
FDT continues to convert the remaining records in the
file.
FDT<xxx,yyy> - Cannot update index record for frame <frame-id>.

The named frame cannot be converted because of a processing
error.
FDT continues to convert the remaining records in the
file.
FDT<xxx,yyy> - Cannot write index of converted file.

The output file from the
Under no circumstances
Professional.

Convert process has been corrupted.
should the output file be used on the

FDT<xxx,yyy> - Cannot write record <frame-id>.

The named frame cannot be converted because of a processing
error.
FDT continues to convert the remaining records in the
file.
FDT<xxx,yyy> - Closing original file after copy.

The specified file cannot be opened because of a processing error
in the file manager.
FDT<xxx,yyy> - Could not read file index zz.

The specified file cannot be opened because the file index cannot
be read.

B-10

INTERNAL ERRORS

FDT<xxx,yyy> - Frame <frame-id> unreadable.
The specified frame exists in the file but it cannot be read.
FDT<xxx,yyy> - Index not written to data file.
The current file cannot be saved in a permanent file because of a
processing error.
FDT<xxx,yyy> - New file cannot be created.
The current file cannot be saved in a permanent file because of a
processing error.
FDT<xxx,yyy> - Read izz during initial copy.
The specified file cannot be opened because of a processing error
in the file manager.
FDT<xxx,yyy> - Record <frame-id> could not
file.

written

The named frame cannot be saved in the permanent file because
a processing error.

data
of

FDT<xxx,yyy> - Record <frame-id> unreadable from temporary file.
The named frame cannot be saved in the permanent file because
a processing error.

FDT<xxx,yyy> - Unable to write record.
The frame editor cannot write the last record to the file.
FDT<xxx,yyy> - Write izz during initial copy.
The specified file cannot be opened because of a processing error
in the file manager.

B-11

APPENDIX C
POSRES STATUS BLOCK CODES

POSRES uses the status block parameter to return error and status
information to the calling program. It is recommended that your
task check the status block after each POSRES call.
Decimal status values are returned to the calling task in a
two-word integer array. The first column of Table C-1 shows the
values returned in the first word of the status array.
The
second column lists the values returned in the second word of the
status array, except for menu routine errors, which are shown in
Table C-2.
In Table C-1, the numbers one and two represent the first and
second status block words, respectively. In your application,
the first word may be array element zero, one, or n, depending on
which
programming
language
you are using.
For example,
BASIC-PLUS-2 numbers arrays from zero while PASCAL lets you
define your own numbering scheme.

Table C-1:

POSRES Status Values

Status
Word 1

Status
Word 2

Description

1 through 12

For menus: option selection was
successful, and the second word
contains the ordinal option
number.

ASCII code

For GETKEY, the second word
contains an ASCII decimal code
representing a keyboard key.
C-1

POSRES STATUS BLOCK CODES
Status
Word 1

Status
Word 2

Description

Undefined

For other routines, there was no
error.

A record or field was truncated.

-6

A message sent to the message
board was truncated to 59 or
fewer characters and displayed.

Key code

For GETKEY, the second word
contains one of the function key
codes listed in Appendix D.

Key value

For PRSCSI routine, a valid CSI
sequence was entered.

-1

DSW

RSX DSW error. See the P/OS
System Reference Manual for error
codes.

-2

I/O code

I/O status error code returned
from a QIO$ directive. See the
P/OS System Reference Manual.

-3
-1
-2
-3

-4
-5

File access error:
Index record not 256 bytes long.
No match during index operation.
File index record is greater than
one block.
File is not open.
Frameid is not in Radix-50
character set.

-4

See Table C-2

Error executing help routine.

-5

See Table C-2

Error executing menu routine.

-6

See Table C-2

Error executing dynamic menu
routine.

-7
-7
-7

-11
-12

Invalid CSI sequence found
No CSI sequence found.
File extension error.

-13

Calling parameter error.

-9

-10

Insufficient buffer space.

C-2

POSRES STATUS BLOCK CODES
Status
Word 1

Status
Word 2

Description

Short message error.

-11
-1

No matching entry number.

-12

RMS error code

PRO/RMS-11 File access error. See
the PRO/RMS-11 manual set for
error codes.

-13

See Table C-2

Error executing menu unpack
routine.

-14

Key code

Option selection failed. The
second word contains one of the
function key codes listed in
Appendix D. For example, the
value 14 indicates that the user
pressed the ADDTNL OPTIONS key.

-15

See Table C-2

Error displaying frame specified
with frameid.

-16

See Table C-2

Error executing multiple-choice
menu routine.

-17

See Table C-2

Error executing menu pack or
unpack routine.

-18
-1

-2
-3

-19
-20

Error executing OLDFIL routine:
No choices made.
No files found.
Error in wildcard selection.
Buffer error. The buffers FL$BUF
and MM$BUF are not large enough.

-1

Message rejected. The Message/
Status Display is full. The
Display lists up to 255 messages.

C-3

POSRES STATUS BLOCK CODES
Table C-2:

Menu Service Routine Errors

Status
Word 2

Description of Error

-1

Option number greater than maximum.

-2

Multiple once-only fields.

-4

Error in.keyword definition.

-5

Title or text field length error.

-6

Text field length error.

-8

Argument error or unknown fieldid.

-9

Buffer error.

-10

Text or option line number greater than maximum.

-11

Error in menu packing.

-12

No options for multiple-choice menu.

-13

Multiple-choice menu limits responses to zero.

-14

More responses allowed than options.

-15

No help available.

C-4

APPENDIX D
FUNCTION KEV NAMES AND CODES

Table D-1 shows the function keys on the Professional
The table gives the following information:
o

Decimal code: The POSRES routine GETKEY returns
in the status array parameter.

PRO label:

P/OS label: The keyboard label strip that
provides alternative names for each key.

Table D-1:

keyboard.
this

value

The Professional keyboard names each key.

Function Key Names and Codes

Code

PRO Label

P/OS Label

BREAK

SETUP

Reserved

RESUME

CANCEL

MAIN SCREEN
b ... 1

comes

with

P/OS

FUNCTION KEY NAMES AND CODES

Code

PRO Label

P/OS Label

FlO

EXIT

Fll

F12

F13

F14

ADDTNL
OPTIONS

HELP

F17

F18

F19

F20

FIND

INSERT HERE

REMOVE

SELECT

PREV SCREEN

NEXT SCREEN

UP ARROW

LEFT ARROW

DOWN ARROW

RIGHT ARROW

PFl

PF2

PF3

D-2

FUNCTION KEY NAMES AND CODES
Code

PRO Label

P/OS Label

PF4

{Application Mode only)
35
36
37
38

ENTER

D-3

APPENDIX E
P/OS ERROR CODES

P/OS displays error codes in the following situations:
•

An application cannot be started.
In this case, P/OS
displays an error code in the form of two decimal numbers.
These error codes are listed in Section E.1.

•

An application task exits abnormally (with exit status other
than EX$SUC).
P/OS displays (in decimal numbers) the first
two words of the exit status block. If the exit status (the
first word) is 4 (EX$SEV), something in the task caused the
system to abort. In that case, the second word is also
significant.
The error codes for this case are listed in
Section E.2.

E.1

APPLICATION CANNOT BE STARTED

Table E-1:

Elements of the Status Array

First
Word

Second
Word
Meaning

-1

The installation command file is missing or
cannot be opened.

-2

nxx

The installation command file contains errors.
The status number in the error code lists the
installation command file line (n) which contains
the error followed by numbers (xx) that mean the
following:

E-1

APPLICATION CANNOT BE STARTED
First
Word

Second
Word

Meaning
00
01
02
03
05
06
07
08

-3

nxx

RUN line expected
Invalid parameter count
Invalid first keyword
Invalid filename spec
Invalid string on line (improperly quoted)
Invalid f rameid
Extra characters on line
Invalid task name

An application task cannot be installed.
The status number in the error code lists the
installation command file line (n) which contains
the error followed by PROTSK error numbers (xx).
01
02
03
04
07
08
09
11
13
14
15
16
18
20
22
23
24
26
27
29
30
31
32
33
34
35
36
37
39
40
41
43

Task name in use
File not found
Specified partition too small
Task and partition base mismatch
Length ·mismatch common block
Base mismatch common block
Too many common block requests
Checkpoint area too small
Not enough APRs for task image
File not a task image
Base address must be on 4K boundary
Invalid first APR
Common block parameter mismatch
Common block not loaded
Task image virtual address overlaps common blocl
Task image already installed
Address extensions not supported
Checkpoint space too small, using
checkpoint file
No checkpoint space, assuming not
checkpointable
Invalid UIC
No pool space
Invalid use of partition or region
Access to common block denied
Task image I/O error
Too many LUNs
Invalid device
Task may not be run
Task active
Task fixed
Task being fixed
Partition busy
Common/task not in system
E-2

APPLICATION CANNOT BE STARTED
First
Word

Second
Word

Meaning
44
45
47
48
49

50
51
99

Region or common fixed
Cannot do receive
Invalid request
Cannot return status
Error encountered on file open operation
Error encountered on file close operation
Cannot get file LBN to process label blocks
Too many INSTALL commands in installation
command file (maximum is 31)

-4

Reserved for internal use

-5

Reserved for internal use

-6

Error occurred during Main Menu display

-7

Error occurred while loading PRO/Communications
software driver

-8

Error occurred while loading OPTIONS Graphics
software

E.2

SYSTEM ABORTED TASK

Word 2 is reported to the end user as positive, but
P/OS as a negative number.

Table E-2:

First
Word

returned

Elements of Status Array

Second
Word

Meaning

4
0
2
4
6
8

10
12

Odd address and other traps to 4
Memory protect violation
Break point instruction (BPT) or trace trap (T-bit)
IOT instruction
Invalid or reserved instruction
NonRSX EMT instruction
TRAP instruction
E-3

SYSTEM ABORTED TASK

First
word

Second
word
14
16
18
20
22
24
26
28

30
32
34
36

Meaninq
11/40 floating point exception
SST abort - bad stack
AST abort - bad stack
Abort via directive (ABRT$)
Task load read failure
Task checkpoint read failure
Task exit with outstanding I/O
Task memory parity error
Task aborted with PMD request
TI: virtual terminal was eliminated
Task installed in 2 different systems
Task aborted due to bad affinity (required
Bus runs are off-line or not present)
Task has run over its time limit

E-4

INDEX

Action form, 5-10
help menu, 5-25
single-choice menu, 5-21
Action string
global, 8-26
option, 8-3, 8-16, 8-26
ADB
see Application Diskette
Builder
Additional Options flag, 8-3, 8-4,
8-16 I 8-21
ALUN$ directive
Communications, 2-2
APPL$DIR, 6-8
APPL$DST, 6-13, 6-17
Application
multiple diskette, 1-5
Application directory, 1-1
and Fast Install, 3-1
Application Diskette Builder, 1-1
to 1-5, 6-23
and Fast Install, 3-3
and installation command file,
1-1
bad block checking, 1-3
Application installation file
see Installation
Background task, 6-22
Bad block
checking by ADB, 1-3
BASIC-PLUS-2, 6-27
CALLABLE PRO/SORT, 11-1
CET
see PROSE
Checkpoint file, A-3
COBOL-81, 6-27
CODEC input on TMS line, 2-45
Collating sequence
PRO/SORT I 11-6
Communications
Base System Services, 2-1
CCANS routine, 2-18, 2-45, 2-46
CCATA routine, 2-2, 2-10, 2-11,
2-46, 2-48
CCATT routine, 2-10, 2-11

CCAUXK routine, 2-46
CCBRK routine, 2-24
CCDET routine, 2-11
CCDIAL routine, 2-15
CCDTMF routine, 2-48
CCFLSH routine, 2-23
CCGMC routine, 2-7, 2-12
CCHNG routine, 2-21, 2-48
CCKILL routine, 2-25
CCLCRG routine, 2-7, 2-9, 2-13
CCLCRP routine, 2-7, 2-9, 2-13
CCMODE routine, 2-45
CCMTT routine, 2-9, 2-14
CCORG routine, 2-19, 2-45, 2-46
CCPTGV routine, 2-47
CCRXD routine, 2-22
CCSMC routine, 2-7, 2-11
CCSPWN routine, 2-27
CCTXD routine, 2-21
COMLIB, 2-1, 2-2, 2-3, 2-9
CPHREC routine, 2-28
CPHSEL routine, 2-29
device names, 2-2
FTATT routine, 2-35, 2-40
FTDET routine, 2-32, 2-36, 2-40,
2-42
FTLISN routine, 2-44
FTNTFY routine, 2-38, 2-40
FTOPRN routine, 2-36, 2-40
FTOPTG routine, 2-33
FTOPTP routine, 2-33
FTSERV routine, 2-43
FT SYNC routine, 2-32, 2-40,
2-41
FTUNPK routine, 2-32, 2-40,
2-41
getting line characteristics,
2-12
line characteristics, 2-5
line descriptor block, 2-4
modem support, 2-8
service categories, 2-1
status value, 2-2, 2-4
translate table, 2-8
XKDRV, 2-1, 2-9, 2-10
Copying application to Public
Library, 6-1

Index-1

INDEX
CPRNT
condition codes, 9-2
error codes, 9-3
CSI sequence
parsing, 8-32
Deleting application from Public
Library, 6-2
DIBOL, 6-27
Diskette
labelling, 1-4
Display form, 5-5, 5-11, 5-14
help menu, 5-24
help text frame, 5-27
message frame, 5-28
Dynamic menu
displaying, 8-3
Escape sequence
PROSE, 10-3
Event flag
Communications, 2-2
Fast Install, 3-1 to 3-3
and Application Diskette
Builder, 3-3
Fatal error handling, 8-8
FCS
see File Control Services
FDT
see Frame Development Tool
File Control Services, 4-1 to 4-3
and Micro/RSX, 4-2
support for various languages,
4-2
File Selection Menu, 8-30
File specification
P/OS default, 8-13, 8-19
use of, 8-28, 8-30
Filename
input routine, 8-28
selection routine, 8-30
FORTRAN-77, 6-27
Frame
computing buffer size, 5-5
Frame Development Tool, 5-1 to
5-31
ACTION command, 5-1, 5-10, 5-12,
5-14' 5-30
ADD command, 5-1, 5-4, 5-13,
5-29

and POSRES, 5-1
CONVERT command, 5-4
DELETE command, 5-1, 5-5
DISPLAY command, 5-11, 5-14,
5-30
DISPLAY commmand, 5-1
error messages, B-1
Errors, 5-29
EXIT command, 5-5, 5-11
FILE command, 5-1, 5-6
file types, 5-6
HELP command, 5-1, 5-6, 5-12
LIST command, 5-1,- 5-7
MODIFY command, 5-1, 5-7, 5-13,
5-30
NAME command, 5-1, 5-7
on PRO/Tool Kit, 5-3
on RSX-11M/M-PLUS, 5-3
on VAX/VMS, 5-2
PROFILE command, 5-1, 5-12,
5-14' 5-30
QUIT command, 5-1, 5-3, 5-8,
5-10' 5-12' 5-31
REPORT command, 5-1, 5-8
SAVE command, 5-1, 5-8, 5-13,
5-30
use of keypad, 5-16
WINDOW command, 5-9
Function key
codes, D-1
GBLDEF option
Communications, 2-35
Help file
closing, 8-10
opening, 8-12
Help frame
default, 8-12, 8-13
specifying, 8-14
displaying, 8-11
I/O status block
Communications, 2-3
Input
single keystroke, 8-9
Installation
and Application Diskette
Builder, 6-1
and running, 6-1
Application, 6-2

Index-2

INDEX
ASSIGN HELP command, 6-8, A-4
ASSIGN LOGICAL command, 6-9
ASSIGN MENU command, 6-10, A-4
ASSIGN MESSAGE command, 6-11
command file, 6-1 to 6-27
and Fast Install, 3-2
errors, A-1
format, 6-2
PRO/SORT, 11-2
PROSE, 10-2
used by ADB, 1-1
comment delimiter, 6-12
EXECUTE command, 6-12
FILE command, 1-4, 6-3, 6-12,
6-19, 6-23, A-2
INSTALL command, 6-3, 6-21, A-2,
A-3
options, 6-26
MOUNT command, 1-3, 1-4, 6-23,
A-6
NAME command, 6-24, A-2, A-6
of application, 6-1
optimization, 6-26
order of commands, 6-3
RUN _co_mm_and, 6-25 ,_ A-1, A-2,
A-5
Keypad
use with FDT, 5-1
Keystroke
input routine, 8-9
Library
Public, 6-1, 6-2
Line descriptor block
Communications, 2-4
Logical name
in Installation Command File,
6-9
Logical unit number
Communications, 2-2
MACR0-11, 7-1
and FCS, 4-2
and PRO/SORT, 11-2
Menu file
closing, 8-15
opening, 8-18
reading from, 8-20
Message
sending, 8-25

Message file
reading from, 8-33
Message/Status Display, 8-25, C-2,
C-3
Micro/RSX
and FCS, 4-2
Mini-Exchange
code characters, 2-17
Modem
support for, 2-8
Multiple diskette application
P/OS Hard Disk, 1-4
Multiple-choice menudisplaying, 8-21
packing, 8-23
New File Specification form, 8-28
P/OS
error codes, E-1
PASCAL, 6-27
PMA
see Professional Macro
Assembler
POSRES, 8-1 to 8-35
and FDT, 5-1
and registers, 8-1
DMENU routine, 8-3
DPACK routine, 8-5
FATLER routine, 8-8
GETKEY routine, 8-9, C-1, c-2
HCLOSE routine, 8-10
HELP routine, 8-11
HFILE routine, 6-8, 8-12
HFRAME routine, 8-14
MCLOSE routine, 8-15
MENU routine, 8-16
MFILE routine, 6-10, 8-18
MFRAME routine, 8-20
MMENU routine, 8-21
MPACK routine, 8-23
MSGBRD routine, 8-25
MUNPK routine, 8-26
NEWFIL routine, 8-28
OLDFIL routine, 8-30, C-3
omitting parameters, 8-2
parameter checking, 8-2
parameter format, 8-2
parameter types, 8-1
PRSCSI routine, 8-32, C-2
RDMSG routine, 6-11, 8-33

Index-3

INDEX
status block, 8-1
status codes, C-1
valid frame identifiers, 5-4
WTRES routine, 8-35
Print Services, 9-1 to 9-9
CPRINT routine, 9-1
CPRV3 routine, 9-4
P/OS Hard Disk, 9-4
PRO/Communications Services, 2-1
PRO/RMS-11, 4-1
and Fast Install, 3-3
PRO/SORT
calling, 11-1
COLLATE command, 11-3, 11-4,
11-5, 11-10
command file
nesting, 11-4
specifying, 11-1
comment, 11-3
data types, 11-8
DEFAULT command, 11-3, 11-5
error codes, 11-15
event flag number, 11-2
example, 11-18
FIELD command, 11-3, 11-7, 11-9
FILE command, 11-2
FORCE command, 11-3, 11-10
INCLUDE command, 11-3, 11-11
INPUT command, 11-3, 11-13
maximum record lengths, 11-2
OUTPUT command, 11-3, 11-13
PROCESS command, 11-2, 11-3,
11-13
pseudo-fields, 11-9
record formats, 11-2
SORT command, 11-3, 11-13
WRITE command, 11-2, 11-3, 11-9,
11-15
Professional Application Builder,
6-25, 8-1
Communications, 2-3
Professional Macro Assembler, 7-1
to 7-2, 8-1
PRO/Tool Kit, 7-1
RSX-llM/M-PLUS, 7-1
VAX/VMS, 7-2
Profile Form, 5-14
Profile form, 5-4, 5-12

Index-4

help menu, 5-23
help text frame, 5-26
message frame, 5-28
single-choice menu, 5-18
PROSE, 10-1 to 10-6
Callable Editor Task, 6-27,
10-1
event flag number, 10-1
margin settings, 10-3
status codes, 10-3
PROTSK routine (POSSUM), 6-22
Public Library
copying applicatiori to, 6-1
deleting application from, 6-2
RD MSG
default, 8-34
REMOVE command (DCL), 6-22
RESUME key
programming, 8-35
RSX-llM-PLUS
and FCS, 4-2
Single-choice menu
displaying, 8-16
dynamic
packing, 8-5
static
unpacking, 8-26
SORT-11
ALTSEQ command, 11-5
SYSLIB, 8-25
Task name, A-3
TASK option, 6-25
Telephone Management System, 2-1,
2-9
Terminal
detaching, 10-2
TMS
see Telephone Management System
code characters, 2-16
Translate table
format, 2-8
Wildcard
use of, 8-30, 8-31

Tool Kit Reference Manual
AA-BT748-TH

READER'S COMMENTS

NOTE: This form is for document comments only. DIGIT AL
will use comments submitted on this form at the company's discretion. If you require a written reply and
are eligible to receive one under Software Performance Report (SPA) service, submit your comments
on an SPA form.
Did you find this manual understandable, usable, and well-organized?
Please make suggestions for improvement.

Did you find errors in this manu·a1? If so, specify the error and the page number.

Please indicate the type of reader that you most nearly represent.
0 Assembly language programmer
0 Higher-level language programmer
0 Occasional programmer (experienced)
0 User with little programming experience
0 Student programmer
DOther(pleasespecify)------------------------~

Name------------------------- Date----------Organization--------------------------------Street-----------------~·---------------~
\_

C i t y - - - - - - - - - - - - - - ' - - - State--~---- Zip C o d e - - - - - - or
Countrv

I
Do Not Tear - Fold Here and Tape - - - - - - - - - - . . ; . - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 1

111111

~amaama

111 111

No Postage
Necessary
if Mai led in the
United States

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

Professional Workstations Publications
DIGITAL EQUIPMENT CORPORATION
146 Main Street, ML021-2/T76
Maynard, Massachusetts 01754-2571

- Do Not Tear - Fold H e r e - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

: :I