Digital PDFs

AA-5580A-TC

May 1979

144 pages

Original

5.4MB

Document:	IAS/RSX-11 System Library Routines Reference Manual
Order Number:	AA-5580A-TC
Revision:	0
Pages:	144
Original Filename:	http://bitsavers.org/pdf/dec/pdp11/rsx11m_s/RSX11M_V3.2_Jun79/3B_ProgramDevelopment/AA-5580A-TC_RSX-11M_V3.2_System_Libr_Routines_197905.pdf

OCR Text

IAS/RSX-11
System Library Routines
Reference Manual
Order No. AA-5580A-TC
and
Update Notice No.1 (AD-5580A-T1)

RSX-11M V3.1
IAS V2.0
RSX-110 V6.2
RSX-11M V3.2

order additional copies of this document, contact the Software Distribution
L..::mter, Digital Equipment Corporation, Maynard, Massachusetts 01754

digital equipment corporation . maynard, massachusetts

First Printing, December 1977
Updated, May 1979
The information in this document is subject to change without notice
and should not be construed as a conunitment 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 for the use or reliability of software on
equipment that is not supplied by DIGITAL or its affiliated companies.

1977, 1979 by Digital Equipment Corporation

The postage-prepaid READER'S COMMENTS form on the last page of this
document requests the user's critical evaluation to assist us in preparing future documentation.
The following are trademarks of Digital Equipment Corporation:

DIGITAL
DEC
PDP
DEC US
UNIBUS
COMPUTER LABS
COMTEX
DDT
DECCOMM
ASSIST-11
VAX
DECnet
DA TAT RIEVE

DECsystem-lo
DECtape
DIBOL
EDUSYSTEM
FLIP CHIP
FOCAL
INDAC
LAB-8
DECSYSTEM-20
RTS-8
VMS
IAS
TRAX

3/80-14

MASS BUS
OMNIBUS
OS/8
PHA
RSTS
RSX
TYPESET-8
TYPESET-11
TMS-11
ITPS-10
SBI
PDT

CONTENTS

Page
PREFACE

vii

CHAPTER

INTRODUCTION

1-1

CHAPTER

2-1

2.1
2.2
2.3
2.4

SAVE ALL REGISTERS
SAVE REGISTERS 3 SAVE REGISTERS 0 SAVE REGISTERS 1 -

2-2
2-3
2-4
2-S

ARITHMETIC ROUTINES

3-1

3.1
3 .1.1
3.1. 2
3.1. 3
3.2
3.2.1
3.2.2
3.2.3

INTEGER ARITHMETIC ROUTINES
Integer Multiply Routine ($MUL)
Integer Divide Houtine ($DIV)
Example
DOUBLE-PRECISION ARITHMETIC ROUTINES
Double-precision Multiply Routine ($DMUL)
Double-precision Divide Routine ($DDIV)
Example

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

INPUT DATA CONVERSION ROUTINES

4-1

4.1
4.1.1

4-1

4.3.3

ASCII TO BINARY DOUBLE-WORD CONVERSIONS
Decimal to Binary Double-word Routine
(.DD2CT)
Octal to Binary Double-word Routine
(. OD2CT)
Example
ASCII TO BINARY CONVERSIONS
Decimal to Binary Conversion Routine
($CDTB)
Octal to Binary Conversion Routine ($COTB)
Example
ASCII TO RADIX-SO CONVERSIONS
ASCII to Radix-50 Conversion Routine ($CATS)
ASCII with Blanks to Radix-50 Conversion
Routine ($CAT5B)
Example

OUTPUT DATA CONVERSION ROUTINES

S-1

S.l
S.1.1
s .1. 2

BINARY TO DECIMAL CONVERSIONS
Binary Date Conversion Routine ($CBDAT)
Convert Binary to Decimal Magnitude
Routine ( $CBDMG)

5-1
5-2

CHAPTER

4 .1. 2
4 .1. 3

4.2
4.2.1
4.2.2
4.2.3
4.3
4.3.1
4.3.2

CHAPTER

iii

ROUTINE ($SAVAL)
S ROUTINE ($SAVRG)
2 ROUTINE ($SAVVR)
S ROUTINE (.SAVRl)

4-1
4-2
4-3
4-4
4-4
4-S
4-S
4-6
4-6
4-8
4-9

5-3

May 1979

•

CONTENTS

Page

5.4

Convert Binary to Signed Decimal Routine
( $CBDSG)
Convert Double-precision Binary to Decimal
Routine ( $CDDMG)
Examples
BINARY TO OCTAL CONVlmSION
Convert Binary to Octal Magnitude Routine
($CBOMG)
Convert Binary to Signed Octal Routine
( $CBOSG)
Convert Binary BytE~ to Octal Magnitude
Routine ( $CBTMG)
Example
GENERAL PURPOSE BINARY TO ASCII CONVERSION
ROUTINE ( $CBTA)
RADIX-SO TO ASCII CONVERSION ROUTINE {$CSTA)

OUTPUT FORMATTING ROUTINES

6-·l

6.1
6.2
6.2.1
6.2.2

6-·l

6.3.1
6.3.2

UPPER CASE TEXT CONVlmSION ROUTINE ( $CVTUC)
DATE AND TIME FORMAT CONVERSION
Date String Converf>ion Routine ($DAT)
Time Conversion Routine ($TIM)
Example
GENERALIZED FORMATTING
Edit Message Routine ($EDMSG)
Examples

DYNAMIC MEMORY MANAGEMENT ROUTINES

7-·l

7.1
7.2
7.3
7.4

USAGE CONSIDERATIONS
INITIALIZE DYNAMIC MEMORY ROUTINE ($INIDM)
REQUEST CORE BLOCK ROUTINE ($RQCB)
RELEASE CORE BLOCK ROUTINE ( $ RLCB)

7-·2
7-2
7-3
7-·4

VIRTUAL MEMORY MANAGEMENT ROUTINES

8-·l

8.1
8.Ll
8.1. 2
8.2

GENERAL USAGE CONSIDERATIONS
User Error Handlinq Requirements
Task Building Requirements
VIRTUAL MEMORY INITil\LIZATION ROUTINE ($INIVM)
CORE ALLOCATION ROUTINES
Allocate Block Routine ($ALBLK)
Get Core Routine ( ~?GTCOR)
Extend Task Routine! ( $EXTSK)
Write Page Routine ($WRPAG)
VIRTUAL MEMORY ALLOCl\TION ROUTINES
Allocate Virtual ME~mory Routine ( $ALVRT)
Allocate Small Virtual Block Routine
($ALSVB)
Request Virtual Core Block Routine ($RQVCB)
PAGE MANAGEMENT ROUTINES
Convert and Lock Page Routine ($CVLOK)
Convert Virtual to Real Address Routine
( $CVRL)
Read Page Routine i( $RDPAG)
Find Page Routine i($FNDPG)
Write-marked Page Routine ($WRMPG)

8-·2
8-·2

5.L 3
5.1. 4
5.1. 5

5.2
5.2.l
5.2.2
5.2.3
5.2.4
5.3

CHAPTER

6.2.3
6.3

CHAPTER

8.3
8.3.1
8.3.2

8.3.3
8.3.4
8.4
8.4.1
8.4.2
8.483
8.5
8.5.1
8.5.2

8.5.3
8.5.4
8.5.5

5-·4
5-·5
5-6
5-7

5-7
5-·8
5-·9
5-·10
5-10

5-11

6-·2
6-·2
6-·3
6-·4

6-·5
6-·5
6-·14

8-·3
8-·5
8-·8
8-·9
8-·ll

8-·13
8-·14
8-·16

8-·16
8-·18
8-20
8-·21
8-·22

8-24
8-26

8-·27
8-·29

CONTENTS

Page
8.5.6
8.5.7

Lock Page Routine ($LCKPG)
Unlock Page Routine ( $UNLPG)

8-31
8-32

SUMMARY PROCEDURES

9-1

APPENDIX A

SYSTEM REFERENCE BIB:LIOGRAPHY

A-1

APPENDIX B

UNIVERSAL LIBRARY ACCESS

B-1

CHAP'l~ER

FIGURES
FIGURE

2-1
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

Control Swapping of the Register Handling
Routines
General Block Diagram of the $INIVM Routine
General Block Diagram of the $ALBLK Routine
General Block Diagram of the $GTCOR Routine
General Block Diagram of the $EXTSK Routine
General Block Diagram of the $WRPAG Routine
General Block Diagram of the $ALVRT Routine
General Block Diagram of the $ALSVB Routine
General Block Diagram of the $RQVCB Routine
General Block Diagram of the $CVLOK Routine
General Block Diagram of the $CVRL Routine
General Block Diagram of the $RDPAG Routine
General Block Diagram of the $FNDPG Routine
General Block Diagram of the $WRMPG Routine
General Block Diagram of the $LCKPG Routine
General Block Diagram of the $UNLPG Routine

2-2
8-7
8-10
8-12
8-14
8-15
8-17
8-19
8-21
8-24
8-25
8-27
8-29
8-30
8-32
8-33

TABLES
TABLl~

1-1
6-1
8-1
9-1
9-.2
9-3

9-4
9-5
9-6
9-7

Program Section Names for SYSLIB Routines
$EDMSG Foutine Editing Directives
Content of the Virtual Memory Management
Library File
Register Handling Routines Summary
Arithmetic Routines Summary
Input Data Conversion Routines Summary
Output Data Conversion Routines Summary
Output Formatting Routines Summary
Dynamic Memory Management Routines Summary
Virtual Memory Management·Routines Sununary

1-3
6-7
8-4
9-1
9-2
9-3
9-4
9-5
9-7
9-8

May 1979

PREFACE

MANU,l\.L OBJECTIVES

The IAS/RSX-11 System Library Routines Reference Manual describes the
usage and function of the system library routines that may be called
from MACR0-11 assembly language programs.

INTENDED AUDIENCE
This manual is intended
language programmers.

for

use

experienced

MACR0-11

assembly

STRUCTURE OF THIS DOCUMENT

I
I

Chapter 1 presents a general description of the services provided
the system library routines and their functional relationships.
Chapter 2 describes the usage and function of
routines.

the

handling

Chapter 3 describes the usage and function of the arithmetic routines.
Chapter 4 describes
conversion routines.

the

usage

and

function

the

input

data

Chapter 5 describes
conversion routines.

the

usage

and

function

the

output

data

Chapter 6 describes the usage and function of
routines.

the

Chapter 7 describes the usage
management routines.

and

function

the

dynamic

memory

Chapter 8 describes the usage
management routines.

and

function

the

virtual

memory

calling

sequences

the

system

library

Chapter 9 summarizes the
routines.

output

formatting

Appc~ndix

A presents a cross-reference system bibliography of other
manuals that describe routines available to IAS/RSX-11 systems users.
Appendix B describes a routine that allows a program to access modules
in a universal library as if they were files.

vii

May 1979

ASSOCIATED DOCUMENTS
The following manuals are
readers of this manual:

prereguisite

sources

information

for

IAS/RSX-11 MACR0-11 Reference Manual.

•

The Task Builder Reference Manual for the appropriate system.

•

The manuals referenced in Appendix A.

The reader should refer to the applicable documentation directory
descriptions of other documents associated with this manual.

viii

for

May 1979

CHAPTER 1
INTRODUCTION

The routines described in this manual were written to provide commonly
needed capabilities for DIGITAL-supplied utilities. We are happy to
supply documentation for them, because the routines are general enough
to be used regularly by most MACR0-11 programmers. Note, however,
that the basic functionality of the routines described in this manual
cannc)t be changed, due to the potentially widespread effect it may
have on our system utilities.
The :system library routines may be called by MACR0-11
language programs to perform the following services:

assembly

•

Save and restore register content to enable transfers of
control between the calling program and called subroutines.

•

Perform integer
division.

•

Convert ASCII input
format.

•

Convert internal binary and
data.

•

Convert and format output data to produce text for a
printout or display.

•

Manage the dynamic memory space available to the task that
requires a small-to-moderate amount of resident memory for
data.

and

double-precision
data

internal
Radix-50

multiplication
binary
data

and

Radix-SO

ASCII

output
readable

memory and disk file storage to accommodate tasks that
• Manage
require large amounts of memory for data that must be
transferred between memory and a disk work file.
This manual describes the procedures for calling the library routines
from within the source program, the outputs that are returned to the
executing task, and the interaction between the library routines and
the executing task.
The system library routines interface with each other to perform their
various services. For example, the data conversion routines call the
arithmetic routines to perform the required multiplication
and
division.
All library routines preserve the contents of the calling
task's registers, generally by calling the appropriate register
handling routine to:

1-1

May 1979

INTRODUCTION
•

Push register contents to the stack.

•

Subsequently pop the contents back into the registers.

•

Return control to the calling task.

The data conversion and format control functions performed by the Edit
Message Routine require calls to the output data conversion routines,
which in turn call other routines.
The virtual memory management routines function as an automatic
control system to allocate and deallocate memory, maintain page
addresses and status, and swap pages between memory and disk storage
to accommodate large amounts of data in a limited amount of physical
(dynamic) memory.
The system library routines communicate with the calling task via
registers in which outputs are returned and/or settings of the C bit
in the Condition Code of the Processor Status Word. The calling task
can usually determine whether a requested service was successfully
performed by examining the output register(s) and/or testing the C bit
setting when control is returned from the library routine. Exceptions
to this procedure are described in the detailed discussions of given
routines.
The system library routines are supplied to users as
two files:
•

I
•

The system
following:

library

file

(SYSLIB.OLB),

object

which

code

contains

the

•

the register handling routines, described in Chapter 2.

•

the arithmetic routines, described in Chapter 3.

•

the input and output data conversion routines,
in Chapter 4 and Chapter 5.

•

the output formatting routines, described in Chapter 6.

•

the dynamic memory allocation
descriibed in Chapter 7.

and

•

the universal
Appendix B.

routines

library

access

release

described

routines

described

The memory management routines file
(VMLIB.OLB),
which
contains the dynamic and virtual memory management routines.

At task build time, the Task Builder will automatically search the
system library file for any referenced routines.
However, the
VMLIB.OLB file must be specified at task build time if a task has
referenced the dynamic memory initialization routine described in
Chapter 7, or any of the virtual memory management routines, described
in Chapter 8 of this manual.
Summarized p~ocedures for using the system library routines are
presented, in tabular format, in Chapter 9. This is quick-reference
material, provided for the MACR0-11 assembly language programmer who
has become familiar with the detailed procedures that are explained in
Chapters 2 through 8 of this manual.
Additional Executive and I/O routines available to IAS/RSX-11 systems
users
are
described
in other manuals.
The System Reference

1-2

May 1979

INTRODUC 1UON

Bibliography in Appendix A presents a cross-reference listing of these
manual titles,
and functional descriptions of types of services
described in the respective manual.
If the task that includes system library routines also references a
position-independent resident library, the possibility of a conflict
of program section names exists.
Routines included in a task cannot
reside in the same program section as routines referenced in the
position-independent resident library. Table 1-1 lists the program
section names and the system library routines that reside in each
program section.
If your task includes a routine that uses a program
section
listed
in Table 1-1 and the task also references a
position-independent resident library routine that uses the same
program section,
the Task Builder generates a fatal error. To
determine how to include the code in your task and avoid a conflict of
program section names, refer to Chapter 3 of the RSX-llM/M-PLUS Task
Builder Manual.
Table 1-1
Program Section Names for SYSLIB Routines
p rogram

s ection
Name

SYSLIB Routines
Module
Routine
Name
Name(s)

BLK.
CATB

SAVAL
SAVVR

$CDTB
$COTB
$CATS
$CAT SB
$CBDAT
$CBDMG
$CBDSG
$CBOMG
$CBOSG
$CBTA
$CBTMG
$CDDMG
$CVTUC
$CSTA
$DAT
$TIM
$EDMSG
.DD2CT
.OD2CT
$SAVAL
$SAVVR

SAVRG
SAVRl

$SAVRG
.SAVRl

AR ITH

$DIV
$MUL
$DDIV
$DMUL

CATS
CAT SB
CBTA

CDDMG
CVTUC
CSTA
ED DAT
EDTMG
OD2CT

$ $RESL

$ $RESM
DARI TH

1-3

May 1979

CHAPTER 2
REGISTER HANDLING ROUTINES

are four register handling routines in the system library:

Ther4~

•

Save All Registers Routine ($SAVAL), which
saves
and
subsequently
restores registers 0 - 5, as described in
Section 2.1.

•

Save Registers 3 - 5 Routine ($SAVRG),
subsequently
restores registers 3 - 5,
Section 2.2.

which saves and
as described in

•

Save Registers 0 - 2 Routine ($SAVVR),
subsequently
restores registers 0 - 2,
Section 2.3.

which saves and
as described in

•

Save Registers 1 - 5 Routine (.SAVRl)'
subsequently
restores registers 1 - 5,
Section 2.4.

which saves and
as described in

The register handling routines function as co-routines to enable
control swapping between themselves, a subroutine, and the original
caller of the subroutine.
To illustrate the effect of using the register handling routines,
assume the following:
an original caller calls a subroutine. The
subroutine calls a register handling co-routine.
The co-routine
pushes the contents of the specified registers to the stack, and
issues a co-routine call back to the subroutine.
The subroutine
executes to completion, then a RETURN instruction is executed to swap
control back to the co-routine.
The co-routine pops the initial
contents of the registers from the st~ck and returns to the original
caller.
Figure 2-1 illustrates the control swapping function performed by
register handling routines.

the

The iregister handling routines are called by other
system library, as noted throughout this document.

the

2-1

routines

May 1979

$$AVAL

SAVE ALL REGISTERS

ORIGINAL CALLER
START
Legend
CALL (subroutine)= JSR PC, subroutine
RETURN
= RTS PC

I
CALL (Subroutine) - - - 1...
.,(Subroutine)

JSR r,$SAVxx ------~ $SAVxx (save registers)

n______

{(issue co-routine call
to subroutine)

~(restore

:
RETURN--_j

END

registers)

•

RETURN (to original caller)

i..i.--------J
Figure 2-1

2 .1

Control Swapping of the Register Handling Routines

SAVE ALL REGISTERS ROUTINE

($SAVl~L)

The $SAVAL routine saves and subsequently restores registers 0 - 5 for
a subroutine.
The $SAVAL routine functions as a co-routine which
swaps control between itself, a subroutine, and the original caller.
To call the $SAVAL routine, the subroutine must contain the
Jump to Subroutine instruction:
JSR

following

PC,$SAVAL

The subroutine must return control to the $SAVAL routine with a RETURN
source statement.
On entry to the $SAVAL routine, the program stack contains the return
address to the original caller and the return address of the
subroutine. The $SAVAL routine pushes the contents of registers 4 - 0
to the stack.
The $SAVAL routine moves the subroutine's return address to the
position following Register
O's contents,
and moves the current
contents of RS to the stack above the contents of R4.
The $SAVAL routine issues a co-routine call, in the form CALL @(SP)+,
to swap control back to the subroutine. The co-routine call replaces
the subroutine's return address with the return address to the $SAVAL
routine.
When control returns to the subroutine the stack pointer
points to $SAVAL 1 s return address.
The stack contains the following:

2-2

May 1979

SAVE ALL REGISTERS
SAVE REGISTERS 3-5

$SAVAL
$SAVRG

Return Address to Original Caller
t----·

Return Address to $SAVAL
The subroutine executes until a RETURN
('RTS PC')
instruction is
executed, which swaps control back to the $SAVAL routine. The
contents of RO - RS are restored
(popped from the stack)
and the
$SAVAL routine RETURNs, via an 'RTS PC' instruction, to the original
caller.
NOTE
For $SAVAL to work properly
(that is,
return control to the original caller),
the routine that calls $SAVAL
must
itself have been invoked by the CALL
is,
JSR
PC,
instruction
(that
subroutine) •

2.2

SAVE REGISTERS 3 - 5 ROUTINE ($SAVRG)

The $SAVRG routine saves and subseguently restores registers 3 - S for
a subroutine.
The $SAVRG routine functions as a co-routine which
swaps control between itself, a subroutine, and the original caller.
To call the $SAVRG routine, the subroutine must contain the
Jump to Subroutine instruction:

following

JSR R5,$SAVRG
The subroutine must return control to the $SAVRG routine with a RETURN
source statement.
On entry to the $SAVRG routine, the program stack contains the return
address to the original caller and the contents of RS of the original
caller. The $SAVRG r'outine pushes the contents of registers 4 and 3
to the stack, then pushes the current contents of RS (return address
to the subroutine) to the stack.
The $SAVRG routine copies the original contents back into RS and
in the form CALL @(SP)+, to swap control
issues a co-routine call,

2-3

May 1979

$SAVRG
$SAVVR

SAVE REGISTERS 3.5
SAVE REGISTERS 0-2

back to the subroutine. The co-routine! call replaces the subroutine's
return address with the return address to the $SAVRG routine. When
control returns to the subroutine,
the stack pointer points to
$SAVRG's return address. The stack contains the following:
Return Address to Original Caller
Register 5 contents of Original Caller
Register 4
Register 3
Return Address to $SAVRG
The subroutine executes until a RETURN
('RTS PC')
instruction is
executed, which swaps control back to the $SAVRG routine. The
contents of registers 3 - 5 are restorc~d (popped from the stack)
and
the $SAVRG routine RETURNs, via an 'RTS PC' instruction, to the
original caller.
NOTE
For $SAVRG to work properly
(that is,
return control to the original caller),
must
the routine that calls $SAVRG
itself have been invoked by the CALL
is,
JSR
PC,
instruction
(that
subroutine).

2. 3

SAVE REGISTERS 0 -

2 ROUTINE

( $SA'\7VR)

The $SAVVR routine saves and subsequently restores registers 0 - 2 for
a subroutine.
The $SAVVR routine functions as a co-routine which
swaps control between itself, a subroutine, and the original caller.
To call the $SAVVR routine, the subroutine must contain the
Jump to Subroutine instruction:

following

JSR R2,$SAVVR
The subroutine must return control to the $SAVVR routine with a RETURN
source statement.
On entry to the $SAVVR routine, the program stack contains the return
address to the original caller and the contents of R2 of the original
caller. The $SAVVR routine pushes the contents of registers 1 and 0
then pushes the current contents of R2 {the return
to the stack,
address to the subroutine) to the stack.
The $SAVVR routine copies the original contents back into R2 and
issues a co-routine call,
in the form CALL @(SP)+, to swap control
back to the subroutine. The co-routine call replaces the subroutine's
return address with the return address to the $SAVVR routine. When
control returns to the subroutine,
the stack pointer points to
$SAVVR's return address. The stack contains the following:

2-4

May 1979

SAVE REGISTERS 0-2
SAVE REGISTERS 1-5

$SAVVR
• SAVR1

r--·

Retur·n Address to Original Caller
Register 2 contents of Original Caller
I---·

The subroutine executes until a RETURN ('RTS PC') instruction is
executed, which swaps control back to the $SAVVR routine. The
contents of registers 0 - 2 are restored (popped from the stack) and
the $SAVVR routine RETURNs, via an 'RTS PC' instruction, to the
original caller.
NOTE
For $SAVVR to work properly (that is,
return control to the original caller),
must
the routine that calls $SAVVR
itself have been invoked by the CALL
is,
JSR
PC,
instruction
(that
subroutine).

2•4

SAVE JREC;ISTERS l - 5 ROUTINE ( • SAVRl)

The .SAVRl routine saves and subsequently restores registers 1 - S for
a subroutine.
The .SAVRl routine functions as a co-routine which
swaps control between itself, a subroutine, and the original caller.
To call the oSAVRl routine, the subroutine must contain the
Jump to Subroutine instruction:

following

JSR R5,oSAVRl
The subroutine must return control to the .SAVRl routine with a RETURN
source statement.
On E~ntry to the .SAVRl routine, the program stack contains the return
address to the original caller and the contents of RS of the original
caller. The .SAVRl routine pushes the contents of registers 4, 3, 2,
and l, and the current contents of RS (the return address to the
subroutine) to the stack.
The .SAVRl routine copies the original contents back into RS and
issues a co-routine call, in the form CALL @(SP)+, to swap control
back to the subroutine. The co-routine call replaces the subroutine's
return address with the return address to the .SAVRl routine. When
control returns to the subroutine, the stack pointer points to
.SAVRl's return address. The stack contains the following:

2-S

May 1979

• SAVR1

SAVE REGISTERS 1-5

Return Address to Original Caller
Register

c·
~'

contents of Original Caller

...
"l

Return Address to .SAVRl

The subroutine executes until a RETURN
('RTS PC')
instruction is
executed, which swaps control back to the .SAVRl routine. The
contents of registers 1 - 5 are restored (popped from the stack)
and
the .SAVRl routine RETURNs, via an
'RTS PC' instruction, to the
original caller.
NOTE
For .SAVRl to work properly
(that is,
re~urn
control to the original caller),
tha routine that calls
.SAVRl
must
itself have been invoked by the CALL
instruction
(that
is,
JSR
PC,
subroutine).

2-6

May 1979

CHAPTER 3
ARITHMETIC ROUTINES

The system library contains four
arithmetic routines that perform
unsigned integer multiplication and division. This chapter describes
the usage and function of these arithmetic routines.

3. 1

IN~l'EGE:R

ARITHMETIC ROUTINES

The system library contains two routines which
operations on 16-bit unsigned integer values:

perform

arithmetic

•

The Integer Multiply Routine ($MUL) , which multiplies
values.

integer

•

The Integer
values.

integer

Divide

Routine

The usage of these routines
following paragraphs.

3.1.l

($DIV),

described

which
and

divides

illustrated

the

Integer Multiply Routine ($MUL)

The $MUL routine multiplies two single-word unsigned
values to produce an unsigned double-word product.

integer

input

To call the $MUL routine:
•

•

Specify two input arguments:
o

in Register O, the multiplier.

in Register 1, the multiplicand.

Include the statement
CALL $MUL
in the source program.

Registers 2 - 5 of the calling task are preserved.
The output from the $MUL routine is:

high order part of result.

low order part of result.

The $MUL routine does not return any error indications to the caller.
3-1

$DIV

INTEGER DIVIDE

3 .1. 2

Integer Divide Routine ($DIV)

The $DIV routine performs unsigned integer division.
To call the $DIV routine:

• Specify two input arguments:
• in Register 0' the divid1end.
• in Register 1, the divisor.
•

Include the statement
CALL $DIV
in the source program.

Registers 2 - 5 of the calling task are preserved.
The output from the $DIV routine is:
e

quotient.

the remainder.

The $DIV routine does not return any c~rror indications to the caller.

3.1.3

Example

The following source statements call
multiplication and store the results.

MOV
MOV
CALL
MOV
MOV

#1200 ,RO
NDV,Rl
$MUL
RO,WORK
Rl,WORK+2

the

$MUL

routine

pe~form

;PUTS MULTIPLIER IN RO.
;PUTS THE MULTIPLICAND AT.NOV IN RI.
;CALLS $MUL ROUTINE.
;STORES HIGH ORDER PART OF RESULT IN WORK.
;STORES LOW ORDER PART OF RESULT IN
;WORK+2.

(continue)

3.2

DOUBLE-PRECISION ARITHMETIC ROUTINES

There are two double-precision
system library:

intege~r

arithmetic

routines

The
Double-precision
Multiply
Routine
($DMUL) ,
• multiplies
an
unsigned
double-precision
value
single-precision
product.

multiplier

3-2

produce

the

which
by
a
double-precision

•

$ DM uL

DOUBLE-PRECISION DIVIDE

$DD Iv

The Double-precision Divide Routine ($DDIV), which divides an
unsigned
double-precision
dividend
by
an
unsigned
single-precision divisor to produce a double-precision result.

The usage of these routines
following paragraphs.

3.2.1

DOUBLE-PRECISION MULTIPL y''

described

and

illustrated

the

Double-precision Multiply Routine ($DMUL)

The $DMUL routine multiplies an unsigned double-precision value by a
single-precision
value
to produce an unsigned double-precision
product.
To call the $DMUL routine:
•

•

Specify two input arguments:
•

in Register 0, the single-precision ~agnitude multiplier.

•

the double-precision magnitude multiplicand, where:
•

•

Include the statement
CALL $DMUL
in the source program.

Registers 4 and 5 of the calling task are preserved.
3 are destroyed on return to the calling task.

Registers 2

and

The outputs from the $DMUL routine are:
•

The double-precision magnitude product, where:
e

high order part.

low order part.

The $DMUL routine does not return any error indications to the caller.

3.2.2

Double-precision Divide Routine ($DDIY)

The $DDIV routine divides an unsigned double-precision
integer
dividend by an unsigned single-precision diviso~ to produce an
unsigned double-precision result.
To call the $DDIV routine:
•

Specify two input arguments:
•

in Register 0, the unsigned divisor.

•

the double-precision dividend, where:
•

•

$001V

DOUBLE-PRECISION DIVIDE

•

Include the statement
CALL $DDIV
in the source program.

The content of R~gister 3 of the calling task is saved
Registers 4 and 5 are not used.

and

restored.

The outputs from the $DDIV routine are:
•

RO = remainder.

•

Quotient, where:
e

high order part of quotient.

low order part of quotient.

The $DDIV routine does not return any error indications to the caller.

3.2.3

Example

The following source statements call
division and store the results.

MOV
MOV

USO ,RO
DVD,Rl

MOV

DVD+2,R2

CALL
MOV
MOV
MOV

$DDIV
Rl,QUOT
R2,QUOT+2
RO,RMAIN

the

$DDIV

routine

perform

;PUTS DIVISOR IN RO.
;PUTS THE HIGH ORDER PART OF THE DIVID;END, STORED IN DVD, IN Rl.
;PUTS LOW ORDER PART OF DIVIDEND, STORED
;IN DVD+2, IN R2.
;CALLS $DDIV ROUTINE.
;PUTS HIGH ORDER PART OF QUOTIENT IN QUOT.
;PUTS LOW ORO:E:R PART OF QUOTIENT IN QUOT+2.
;PUTS REMAINDE:R IN REMAIN •

(continue)

3-4,

CHAPTER 4
INPUT DATA CONVERSION ROUTINES

The system library input data conversion routines accept ASCII data as
input and convert it to the specified numeric representation. There
are three types of routines that perform input data conversion:

4. 1

•

ASCII to binary double-word conversion routines, which accept
ASCII decimal or octal input numbers and convert them to
double-word binary numbers, as described in Section 4.1 of
thii:; chapter.

•

ASCII to binary conversion routines, which accept ASCII
decimal or octal input numbers and convert them to single-word
binary numbers, as described in Section 4.2.

•

ASCII to Radix-50 conversion routines, which accept ASCII
alphanumeric input characters and convert them to Radix-50
internal format, as described in Section 4.3.

A:SCU

'l~O

BINARY DOUBLE-WORD CONVERSIONS

There are two system library routines that convert ASCII input numbers
to double-word binary numbers:

4.1.1

•

The Decimal to Binary Double-word Routine
(.DD2CT), which
accepts ASCII decimal numbers as input, and converts them to
double-word binary format, described in Section 4.1.1.

•

The Octal to Binary Double-word Routine
(.OD2CT), which
accepts ASCII octal numbers as input and converts them to
double-word binary format, described in Section 4.1.2.

Decimal to Binary Double-word Routine (.DD2CT)

The .DD2CT routine converts a signed ASCII decimal number string to
double length (two-word) signed binary number.

The routine accepts leading plus
(+)
or minus
(-)
signs, and a
trailing decimal point. A preceding # symbol is acceptable, but will
force octal conversion. A # symbol and a period in the same input
string is invalid.
Acceptable characters in the string are the
numbers 0 - 9. Any other characters in the string will cause the
.DD2CT routine to terminate the conversion procedure. The value range
of a decimal number to be converted is -231 to +231 -1.

4-1

. DD 2

c T DECIMAL TO BINARY DOUBLE WORD

.Q02CT OCTAL TO BINARY DOUBLE WORD
To call the .DD2CT routine:
•

•

Supply three input arguments in the task's source code:
•

in Register 3, the address of the two-word field in which
the converted number is to be stored.

•

in Register 4, the number of characters in the string
be converted.

•

in Register 5, the address of the character string to
converted.

Include the statement
CALL .DD2CT
in the source program.

The .DD2CT routine saves and restores all of
registers. Outputs from the .DD2CT routine are:

the

calling

•

The converted number, where the high order 16 bits are stored
in word 1 of the field specified in R3 input, and the low
order 16 bits are stored in word 2 of the field.

•

Condition Code:

c bit

clear if conversion was successful.

c bit

set if an illegal character was found
was incomplete.

and

The user can determine, in the task, whether conversion
by testing the C bit in the Condition Code.

4.1.2

task's

conversion

was

complete

Octal to Binary Double-word Routine {.OD2CT)

The .OD2CT routine converts an ASCII octal number string to
length (two-word) binary number.

double

The routine accepts leading plus (+)
or minus
(-)
signs, and the
numbers 0
7.
A preceding # symbol is legal in the octal number
string. A # symbol and a period in the same input string is invalid.
A trailing decimal point will be accepted in the input string, but
will cause the decimal, rather than octal, radix to be used.
This
condition exists because the .OD2CT routine is an entry point in the
.DD2CT routine, which converts decimal number strings to binary
double-word values (see Section 4.1.1).
Any other characters in the ASCII octal number string will
.OD2CT routine to terminate the conversion procedure.
The value range of
+231 -1.

octal

number

4-2

converted

cause
is

-2 31

the
to

OCTAL TO BINARY DOUBLE WORD

.Q02CT

To call the .OD2CT routine:
•

•

Supply three input arguments in the task~s source code:
•

in Register 3, the address of the two-word field in which
the converted number is to be stored.

•

in Register 4, the number of characters in the string
be converted.

•

in Register 5, the address of the character string to
converted.

Include the statement
CALL .OD2CT
in the source program.

The .OD2CT routine saves and restores all of
registers. Outputs from the .OD2CT routine are:

the

task's

•

The converted number, where the high order 16 bits are stored
in word 1 of the field specified in R3 input, and the low
order 16 bits are stored in word 2 of the field.

•

Condition Code:

c bi.t

clear if conversion was successful.

c bit

set if an illegal character was found
was incomplete.

The user can determine, in the task, whether conversion
by testing the C bit in the Condition Code.

4.1.3

calling

and
was

conversion
complete

Example

The following source statements illustrate a way of calling the .OD2CT
routine and checking the results on return.
BOUT:

.BLKW

MOV

#BOUT,R3

MOV

#7,R4

MOV

#ICHR,RS

CALL
BCS

. OD2CT
100$

(continue)

100$:

CAIJL ERR

;PUTS THE ADDRESS OF THE 2-WORD OUTPUT
;FIELD (BOUT) IN R3.
;PUTS THE NUMBER 7 (NUMBER OF INPUT
;CHARACTERS) IN R4.
;PUTS THE ADDRESS OF THE INPUT CHARACTER
;STRING (ICHR) IN RS.
;CALLS THE .OD2CT ROUTINE •
;BRANCHES TO 100$ IF C BIT SET (INPUT STRING
;CONVERSION WAS NOT SUCCESSFUL).
;IF C BIT CLEAR CONVERSION WAS SUCCESSFUL
;AND THE PROGRAM CONTINUES.

;CALL ERR ROUTINE TO OUTPUT MESSAGE.
4-3

$C0T8
4.2

DECIMAL TO BINARY CONVERSION

ASCII TO BINARY CONVERSIONS

There are two system library routines that convert
input numbers to single-word unsigned binary numbers:

unsigned

ASCII

•

The Decimal to Binary Conversion Routine
($CDTB), which
accepts ASCII decimal numbeirs as input and converts them to
single-word binary format, described in Section 4.2.1.

•

The Octal to Binary Conversion Routine ($COTB), which accepts
ASCII octal numbers as input and converts them to single-word
binary format, described in Section 4.2.2.

These routines call the Integer Multiply Routine ($MUL) to perform the
multiplication required for the conversion.

Decimal to Binary Con~ersion Routine ($CDTB)

4.2.1

The $CDTB routine converts an unsigned ASCII decimal number to binary.
Valid characters in the input decimal number are the characters 0 - 9.
All other input characters are invalid and are not converted by this
routine.
The end of a string of numbers must be marked by a terminating
character, which may be any ASCII character except the numbers 0 - 9.
Examples of terminating characters are:
blank, tab
character,
alphabetic character, and a special symbol. Leading blanks and tab
characters are ignored.
The maximum value of a decimal number that can be converted by the
$CDTB routine is 65,535.
Numbers of greater value will cause
indeterminate results, since the $CDTB routine does not check the
value range of an input number. No significant condition code setting
is returned to the calling task.
To call the $CDTB routine:
•

Input, in Register 0, the address of the
ASCII characters to be converted.

•

Include the statement

first

byte

the

save

and

restore

CALL $CDTB
in the source program.
The $CDTB routine calls the $SAVRG
registers 3 - 5 of the calling task.

routine

The outputs returned from the $CDTB routine are:
e

the address of the next byte in the input buffer.

•

the converted number.

the terminating character.

The user can determine, in the task, whether an input string was
successfully converted by testing the content of R2.
If the content
is other than the expected terminating character, the conversion was
incomplete, since some other invalid character was found in the input
string.
4-4

DECIMALTOBINARYCONVERSION:
OCTAL TO BINARY CONVERSIQN

$C0T8
SCOTB

Since the $CDTB routine returns the address of the next byte in the
input buffer to the calling task, successive input string conversion
may be effected by setting up a processing loop back to the CALL $CDTB
statement, as shown in Section 4.2.3.

4.2.2

Octal to Binary Conversion Routine ($COTB)

The $COTB routine converts an ASCII octal number to
characters in the number to be converted are 0 - 7.

binary.

Valid

The end of a string must be marked by a terminating character, which
may be any ASCII character except the numbers 0 - 7. Examples of
terminating characters are: blank, a tab character, an alphabetic
character, and a special symbol. Leading blanks and tab characters
are :ignored.
The maximum value of an octal number that
$COTJB routine is 177777.

can

converted

the

To call the $COTB routine:
Input, in Register 0, the address of the
• ASCII
characters to be converted.
•

first

byte

save

and

restore

Include the statement
CALL $COTB
in the source program.

The :$CO'l'B routine calls the $SAVRG
registers 3 - 5 of the calling task.

routine

The outputs returned from the $COTB routine are:

•

RO = the address of the next byte in the input buffer.

the converted number.

the terminating character.

The user can determine, in the task, whethe' an input string was
successfully converted by testing the content of R2.
If the content
is other than the expected terminating character, the conversion was
incompl•te, since some other invalid character was found in the input
string.
Successive input string conversion may be effected by setting up a
prociessing loop as shown in the example for the $CDTB routine in
Section 4.2.3.

The following source statements define a processing loop,
using the
$CDTB routine, to convert a series of ASCII decimal character strings
to binary numbers. The character strings stored in the input buffer
(IBUF) are in the format
xxx: (TAB) KXXX (TAB) xx (Tl\B) xxxxx (SPl~CE)

4-5

$ c AT 5' ASCII TO RADIX-60 CONVERSION
where the TAB character is used as the terminating character of each
string, and the SPACE character is used as the terminating character
of the input buffer. If converted successfully, the binary numbers
are to be stored in the buffer, BNUM.
MOV
MOV

; PUTS THE OUT'PUT BUFFER ADDRESS IN R4.
;PUTS INPUT BUFFER ADDRESS IN RO (REQUIRED
;INPUT ARGUMENT FOR $CDTB ROUTINE).
CALL $CDTB
;CALLS CONVERSION ROUTINE
MOV Rl,(R4)+
;PLACE CONVER.TED NUMBER IN BNUM
CMP ill,R2
;COMPARE ASCII TAB (HT) VALUE TO TERMINATING
;CHARACTER RETURNED IN R2.
BEQ LOOP
;IF EQUAL, STRING SUCCESSFULLY CONVERTED;
;GO BACK THROUGH LOOP TO CONVERT NEXT. INPUT
;STRING POINTED TO BY RO.
CMP #40,R2
;COMPARE SPACE VALUE (40) WITH TERMINATING
;CHARACTER IN R2.
BEQ 10$
;IF EQUAL, CONTINUE PROGRAM (ALL INPUT
;HAS BEEN CONVERTED SUCCESSFULLY).
JMP ERR
;IF NOT EQUAL, ILLEGAL CHARACTER IN INPUT
;STRING CAUSED CONVERSION TO TERMINATE; HENCE
;INPUT IS ERRONEOUS; GO TO ERROR ROUTINE.
(continued source program)

LOOP:

10$:

4.3

#BNUM, R4
#IBUF,RO

ASCII TO RADIX-SO CONVERSIONS

There are two system library routines that convert ASCII
input characters to 16-bit Radix-SO values:

alphanumeric

•

The ASCII to Radix-SO Conversion Routine
($CATS), which
accepts input characters from the ASCII subset and converts
them to Radix-SO format, described in Section 4.3.1.

•

The ASCII With Blanks to Radix-SO Conversion Routine ($CATSB) ,
which accepts input characters from the ASCII subset and blank
characters and converts them to Radix-SO format, described in
Sec ti on 4. 3. 2.

The Integer Multiply Routine
($MUL)
is
multiplication required for the conversion.

4.3.1

called

perform

the

ASCII to Radix-SO Conversion Routine ($CATS)

The $CATS routine converts from one to three
16-bit Radix-SO value.

ASCII

characters

Valid characters in the ASCII string to be converted are:
•

Alphabetic characters A -

•

Numeric characters 0 - 9.

•

The characters:

dollar sign ($) and period (.).

For complete conversion the string must
contain
three
valid
characters.
Invalid characters will cau~e the $CATS routine to
terminate conversion. When an invalid character is found in the input
string, the converted value will represent the valid character(s) and
trailing blank(s).

4-6

ASCII TO RADIX-60CONVERSION

$CAT5

NOTE
A blank character (space) in the ASCII
character string will cause the $CATS
routine to terminate. If blanks are to
be included as valid characters in the
string, the $CATSB routine should be
called to perform the conversion (see
Section 4.3.2).
To call the $CATS routine:
•

Input , in Register 0, the address of the first
the ASCII string to be converted.

character

•

Input, in Register 1, the period disposition flag, as follows:
Rl = 0 to specify that the period is a conversion terminator
(terminating character).
Rl

•

1 to specify that the period is to be accepted as a
valid character and used in the conversion to Radix-SO.

Include the statement
CALL $CATS
in the source program.

The $CATS routine calls the $SAVRG routine to save and restore
registers 3 - S of the calling task. Outputs from the $CATS routine
are:
•

RO = the address of the next character in the input string.

•

R2
the terminating character.
(This is the last character
in the string that was converted, or the invalid character
that caused conversion termination.)

•

Condition Code:

the converted Radix-SO value (1 - 3 characters).

C bit = set if fewer than three characters were converted.
C bit

clear if conversion was complete.

The useir can determine, in the task, whether conversion was complete
by testing the C bit in the Condition Code or the content of Register
2. Since the address of the next character in the input string is
returned in Register 0, successive input string conversion may be
effected by resetting Rl and setting up a processing loop back to the
CALL $CATS statement.

4-7

c AT 58

4.3.2

ASCII V'allTH BLANKS TO RADIX-60 CONVEIFtSION

ASCII with Blanks to Radix-SO Conversion Routine ($CATSB)

The $CATSB routine converts an ASCII three-character string, including
blank characters, to a 16-bit Radix-SO value.
Valid characters in the ASCII string to be converted are:
•

Alphabetic characters A -

•

Numeric characters 0 - 9.

•

The characters:

dollar sign ($), period (.), and blank
(space).

For complete conversion,
the string must contain
three
valid
characters.
Invalid characters will cause the $CAT5B routine to
terminate conversion. When an invalid character is found in the input
string,
the converted value will represent the valid character(s) and
trailing blank(s).
To call the $CAT5B routine:
•

Input, in Register 0, the address of the
the ASCII string to be converted.

•

Input, in Register 1, the period disposition flag, as follows:

first

character

Rl = 0 to specify that the period is a conversion terminator
(terminating character).
Rl

•

1 to specify that the period is to be accepted as a
valid character and used in the conversion to the
Radix-50 value.

Include the statement
CALL $CAT5B
in the source program.

The $CATSB routine calls the $SAVRG
registers 3 - 5 of the calling task.
are:

routine to save and restore
Outputs from the $CATSB routine

the address of the next character in the input buffer.

the converted Radix-SO value.

•

R2
the terminating character.
(This is the last character
in the string that was converted, or the invalid character
which caused conversion termination.)

•

Condition Code:

c bit
c bit

set if conversion was incomplete.
clear if conversion was complete.

The user can determine, in the task, whether conversion was complete
by testing the C bit in the Condition Code or the content of Register
2. Since the address of the next character in the input string is
returned in Register 0, successive input string conversion may be
effected by resetting Rl and setting up a processing loop back to the
CALL $CATSB statement.

4-8

INPUT DATA CONVERSION ROUTINES
4.3.3

Example

The following source statements define a subroutine that calls
$CATS routine to convert ASCII input data to Radix-SO format.
CNVRTR: JSR
MOV

2$:

R2,$SAVVR
#ASDAT,RO

CLR

CALL

$CATS

BCC

JMP

INER

MOV
Rl,RADS
RETURN

;CALLS $SAVVR ROUTINE TO SAVE RO - R2.
;PUTS THE ADDRESS OF THE FIRST ASCII
;CHARACTER IN RO.
;SETS Rl TO ZERO TO SPECIFY THAT PERIOD
;IS CONVERSION TERMINATOR.
;CALLS $CATS ROUTINE TO CONVERT ASCII
;TO RADIX-SO.
;BRANCH TO 2$ IF C BIT IS CLEAR
; (CONVERSION COMPLETE) •
;JUMPS TO INPUT ERROR ROUTINE (INER) IF
;C BIT IS SET (CONVERSION INCOMPLETE).
;STORES CONVERTED CHARACTER IN RADS.
;RETURNS TO MAIN PROGRAM, VIA $SAVVR,
;WHEN CONVERSION COMPLETE.

4-9

the

CHAPTER 5
OUTPUT DATA CONVERSION ROUTINES

The output data conversion routines convert internally stored numeric
data to ASCII characters.
There are four groups of output data
conversion routines:
•

•

Binar.y to decimal conversion routines, described in
5.1, to convert binary data to one of the following:
•

a 2-digit day date, in the range 01-31.

•

a 5-digit unsigned decimal magnitude number.

•

a 5-digit signed decimal number.

a decimal number up to 9 digits in length.

Section

Binary to octal conversion routines, described in Section 5.2,
to convert binary numbers to one of the following octal
numbers:

a 6-digit unsigned octal magnitude number.

a 6-digit signed octal number.

a 3-digit octal number.

•

A general purpose binary conversion routine, to convert binary
data to ASCII format.
This routine may be called directly by
the user to perform converion from binary to ASCII according
to user-defined p~rameters, or it may be called indirectly be
calling the binary to decimal or octal routines which pass
predefined parameters to this routine, as described in Section
5.3.

•

A nadix-50 to ASCII conversion routine, to convert a Radix-SO
value to a 3-character ASCII stDing, as described in Section
5.4.

The output data routines described in this chapter are called by the
Edit Message Routine ($EDMSG), described in Chapter 6, to convert data
to be formatted for output to printers or display devices.

5. 1

BINARY i'O DECIMAL CONVERSIONS

There are four system library routines that convert
formatted binary numbers to external ASCII decimal format:

5-1

internally

$C80AT

BINARY DATE CONVERSION

•

Binary Date Conversion Routine! ($CBDAT), which converts an
internally stored binary date to a 2-digit decimal number, as
described in Section 5.1.1.

•

Convert Binary to Decimal Magnitude Routine ($CBDMG), which
converts an internally stored binary number to a 5-digit
unsigned ASCII decimal magnitude value, as described in
Section 5 .1. 2.

•

Convert Binary to Signed Decimal Routine ($CBDSG), which
converts an internally stored binary number to a 5-digit
signed ASCII dee imal number, as described in Section 5 .1. 3.

•

Convert Double-precision Binary to Decimal Routine ($CDDMG),
which converts a double-precision, unsigned binary nrimber to
an ASCII decimal number of 9 digits or less, as described in
Section 5 .1. 4.

These routines use predefined paramHters that are passed to the
general purpose conversion routine ($CBTA), which performs the actual
binary to ASCII conversion.

5.1.1

Binary Date Conversion Routine ($CBDAT)

The $CBDAT routine converts an internally
2-digit decimal number.
The $CBDAT
parameters:

routine

uses

the

stored

fo1lowing

binary

date

predefined

conversion

radix = 10.
field width = 2. characters
sign flag = UNSIGNED
leading zeroes flag = NOSUP (no suppression)
To call the $CBDAT routine:
•

•

Supply three input arguments in the task's source code:
•

in Register O, the starting address of the output area in
which the converted two-byte date is to be stored.

•

in Register 1, the binary date to be converted.

•

in Register 2, the zero suppression indicator, where:
R2 = 0 to specify suppression of leading zeroes in
converted date, which will be left-justified.

the

R2 = nonzero to specify that leading zeroes are not
be suppressed.

Include the statement
CALL $CBDAT
in the source program.

The predefined conversion parameters .are automatically pushed to the
stack on entry to the $CBDAT routine. If the user specifies, via R2 =
0, that leading zeroes are to be suppressed, the NOSUP parameter is
reset.
In any case, the $CBDAT routine passes the parameters in
Register 2 to the General Purpose Binary to ASCII Conversion Routine
($CBTA), which performs the actual conversion of the binary number.
5-2

BINARY DATE CONVERSION
CONVERT BINARY TO DECIMAL MAGNITUDE

$C80AT
$C80MG

The $CBTA routine calls the $SAVRG routine to save and restore
registers 3 - 5 of the calling task. Registers 1 and 2 are destroyed.
Outputs from the $CBDAT routine are:
•

The converted day date {in the range 01-31) in
output area.

the

specified

•

RO = the next available address in the output area
pointer to the location following the last digit stored).

{the

The $CBDAT routine does not return error conditions to the caller.

Convert Binary to Decimal Magnitude Routine {$CBDMG)

5.1.2

The $CBDMG routine converts an internally stored binary
5-digit unsigned ASCII decimal magnitude number.
The $CBDMG
parameters:

routine

uses

the

following

number

predefined

conversion

radix = 10.
field width = 5. characters
sign flag = UNSIGNED
lE~ading zeroes flag = NOSUP (no suppression)
To call the $CBDMG routine:
•

Supply three input arguments in the task's source code:
•

in Register 0, the starting address of the output area in
which the converted 5-digit number is to be stored.

•

in Register
converted.

•

in Register 2, the zero suppression indicator, where:

the

unsigned

binary

number

R2 = 0 to specify suppression of leading zeroes in the
converted number.
The output number will be
left-justified.
R2
•

nonzero to specify that leading zeroes are not
be suppressed.

Include the statement
CALL $CBDMG
in the source program.

The predefined conversion parameters are automatically pushed to the
stack on entry to the $CBDMG routine.
If the user specifies, via R2 =
O, that leading zeroes are to be suppressed, the NOSUP parameter is
reset.
In any case,
the $CBDMG routine passes the parameters in
Register 2 to the General Purpose Binary to ASCII Conversion Routine
{$CBTA), which performs the actual conversion of the binary number.
The $CBTA routine calls the $SAVRG routine to save and restore
registers 3 - 5 of the calling task. Registers 1 and 2 are destroyed.
Outputs from the $CBDMG routine are:

5-3

$C80MG
$C80SG

CONVERT BINARY TO DECIMAL MAGNITlJIDE
CONVERT BINARY TO SIGNED DECIMAL

•

The converted number, a maximum of five digits in
the specified output area.

lengthv

•

RO = the next available address in the output area
(the
pointer to the location following the last digit stored) •

The $CBDMG routine does not return error conditions to the callerD

5.1.3

Convert Binary to Signed Decimal Routine ($CBDSG)

The $CBDSG routine converts an internally stored binary
5-digit signed ASCII decimal number.
The $CBDSG
parameters:

routine

uses

the

following

number

predefined

conversion

radix = 10.
field width = 5.
characters
sign flag = SIGNED
leading zeroes flag = NOSUP (no suppression)
To call the $CBDSG routine:
•

Supply three input arguments in the task's source code:
•

in Register 0, the starting address of the output area in
which the converted 5-digit number is to be stored.

•

in Register 1, the binary number to be converted.

•

in Register 2, the zero
R2

supp~ession

= 0 to specify suppression of leading zeros
converted number.
left-justified.

R2
•

indicator, where:

The

output

number

in the
will be

nonzero to specify that leading zeroes are not
be suppressed.

Include the statement
CALL $CBDSG
in the source program.

The predefined conversion parameters are automatically pushed to the
stack on entry to the $CBDSG routine.
If the user specifies, via R2 =
0, that leading zeroes are to be suppressed, the NOSUP parameter is
reset.
In any case,
the $CBDSG routine passes the parameters in
Register 2 to the General Purpose Binary to ASCII Conversion Routine
($CBTA), which performs the actual conversion of the binary number.
The $CBTA routine calls the $SAVRG routine to save and restore
registers 3 - 5 of the calling task.
Registers 1 and 2 are destroyed.

5-4

CONVERT BINARY TO SIGNED DECIMAL
CONVERT DOUBLE-PRECISION BINARY TO DECIMAL

$C80SG
$C00MG

Outputs from the $CBDSG routine are:
•

The converted number, a maximum of five digits in
the specified output area.

length,

•

RO = the next available address in the output area {the
pointer to the location following the last digit stored) •

The $CBDSG routine does not return error conditions to the caller.

5.1.4

Convert Double-precision Binary to Decimal Routine ($CDDMG)

The $CDDMG routine converts a double-precision, unsigned binary number
to an ASCII decimal number of 9 digits or less.
If the number
contains more than 9 digits, the routine inserts a string of five
ASCII asterisk symbols in the output area.
To call the $CDDMG routine:
•

Supply three input arguments in the task's source code:
•

in Register O, the starting address of the output area.

•

in Register 1, the address of the two-word
containing the double-precision number.

•

in Register 2, the zero suppression indicator, where:

input

area

R2 = 0 to specify that leading zeroes are to be
suppressed. The number will be left-justified.
R2

nonzero, to specify that leading zeroes are not to
be suppressed.
NOTE
If the five most significant digits are
zeroes,
they
will
be
automatically
suppressed, regardless of the suppression
indicator setting.

•

Include the statement
CALL $CDDMG
in the source progra~.

The $CDDMG routine calls the $SAVRG routine to save and restore
registers 3 - 5 of the calling task. Registers 1 and 2 are destroyed.
The $DDIV routine is called to perform the double-precision division,
and the General Purpose Binary to ASCII Conversion Routine ($CBTA) is
called to perform the actual ASCII conversion.

5-!5

$ c DD MG

CONVERT DOUBLE-PRECISION BINARY TtO DECIMAL

Outputs from the $CDDMG routine are:
•

RO = the pointer to the next available address in
storage area.

•

The converted ASCII number, stored in the output area, or a
string of ASCII asterisks if more than 9 digits resulted in
the conversion attempt.
If the number was successfully
converted, the output area will contain from four to nine
digits.

5. 1. 5

the

output

Examples

Examples of the use of output conversion
this section.
EXA~PLE

presented

The following are source statements that illustrate
steps required to call the $CBDAT routine.

the

MOV
MOV
CLR

#ASDAT,RO
BDAT,Rl
R2

CALL

$CBDAT

routines

are

;PUTS THE ADDRESS OF OUTPUT AREA IN RO.
;PUTS THE BINARY DATE, AT BOAT, IN Rl.
;CLEARS R2 TO ZERO TO SPECIFY THAT LEADING
;ZEROES ARE TO BE SUPPRESSED.
;CALLS THE $CBDAT ROUTINE.

(continue)
EXAMPLE 2.

10$:

The following are source statements to call the $CDDMG
routine to convert a double-precision number to an ASCII
decimal number and check the result.

MOV
MOV

#ASDN,RO
#DPWRD,Rl

MOV

#4. ,R2

CALL
CMPB

$CDDMG
#'*,ASDN

BNE

10$

JMP

ERR

;PUTS. ADDRESS OF OUTPUT AREA IN RO.
;PUTS STARTING ADDRESS OF DOUBLE; PRECISION INPUT WORD IN Rl.
;PUTS NONZERO IN R2 (SETS THE ZERO
;INDICATOR FLAG TO 1) TO SPECIFY
;THAT LEADING ZEROES ARE NOT TO
;BE SUPPRESSED.
;CALLS THE $CDDMG ROUTINE.
;COMPARES AN ASCII ASTERISK SYMBOL WITH
;A BYTE OF THE CONVERTED NUMBER.
;IF NOT EQUAL CONVERSION WAS SUCCESSFUL
;AND PROGRAM CONTINUES.
;IF EQUAL, JUMP TO ERROR ROUTINE ERR (MORE
;THAN NINE DIGITS WERE CONVERTED AND THE
;OUTPUT DATA IS INVALID) •

(continue)

5-6

CONVERT BINARY TO OCTAL MA8NITUDE

5.2

SCBOMG

BINARY TC) OCTAL CONVERSION

There are three system library routines that convert
formatted binary numbers to external ASCII octal format:

internally

•

Convert Binary to Octal Magnitude Routine
($CBOMG) , which
converts an internally stored binary number to a 6-digit
unsigned ASCII octal magnitude number, as described in Section
5. 2. L

•

Convert Binary to Signed Octal Routine
($CBOSG) ,
which
converts an internally stored binary number to a 6-digit
signed ASCII octal number, as described in Section 5.2.2.

•

Convert Binary Byte to Octal Magnitude Routine ($CBTMG) , which
converts an internally stored binary byte to a 3-digit ASCII
octal number, as described in Section 5.2.3.

These routines use predefined parameters that are passed to the
general purpose conversion routine ($CBTA), which performs the actual
binary to ASCII conversion.

5.2.1

Convert Binary to Octal Magnitude Routine ($CBOMG)

The l?CBOMG routine converts an internally stored binary
6-digit unsigned ASCII octal magnitude number.
The $CBOMG
parameters:

routine

uses

the

following

number

predefined

conversion

radix = 8.
field width = 6. characters
sign flag = UNSIGNED
leading zeroes flag = NOSUP (no suppression)
To call the $CBOMG routine:
•

Supply three input arguments in the task's source code:
•

in Register 0, the starting address of the output area in
which the converted 6-digit number is to be stored.

•

in Register 1, the binary number to be converted.

•

in Register 2, the zero suppression indicator where:
R2

= 0 to specify suppression of leading zeroes in
converted numbero
left-justified.

R2
•

The

output

number

will

nonzero to specify that leading zeroes are not
be suppressed.

Include the statement
CALL $CBOMG
in the source program.

5-7

the
be
to

$C80MG
$C80$G

CONVERT BINARY TO OCTAL MAGNITUDE
CONVERT BINARY TO SIGNED OCTAL

The predefined conversion parameters are automatically pushed to the
stack on entry to the $CBOMG routine.. If the user specifies, via R2 =
O, that leading zeroes are to be suppressed, the NOSUP parameter is
reset.
In any case, the $CBOMG routine passes the parameters in
Register 2 to the General Purpose Binary to ASCII Conversion Routine
($CBTA), which performs the actual conversion of the binary number.
The $CBTA routine calls the $SAVRG routine to save and restore
registers 3 - 5 of the calling task. Registers 1 and 2 are destroyed.
Outputs from the $CBOMG routine are:
•

The converted number, a maximum of six digits
the specified output area.

length,

•

RO = the next available address in the output area
pointer to the location fpllowing the last digit stored)"

(the

The $CBOMG routine does not return error conditions to the caller.

5.2.2

Convert Binary to Signed Octal Routine ($CBOSG)

The $CBOSG routine converts an internally stored binary
6-digit signed ASCII octal number.
The $CBOSG
parameters:

routine

uses

the

following

predefined

number

convE~rsion

radix = 8.
field width = 6. characters
sign flag = SIGNED
leading zeroes flag = NOSUP (no suppression)
To call the $CBOSG routine:
•

Supply three input arguments in the task's source code:
•

in Register 0, the starting address of the output area in
which the converted 6-digit number is to be stored.

•

in Register 1, the binary number to be converted.

•

in Register 2, the zero suppression indicator, where:
R2 = 0 to specify suppression of leading zeroes in the
converted number.
The output number will be
left-justified.
R2 = nonzero to specify that leading zeroes are not
be suppressed.

•

Include the statement
CALL $CBOSG
in the source program.

The predefined conversion parameters are automatically pushed to the
stack on entry to the $CBOSG routine. If the user specifies, via R2 =
O, that leading zeroes are to be suppressed, the NOSUP parameter is
reset.
In any case, the $CBOSG routine passes the parameters in
Register 2 ~o the Gen~ral Purpose Binary to ASCII Conversion Routine
($CBTA), which performs the actual conversion of the binary number.

5-B

CONVERTBINARVTOSIGNEDOCTAL
CONVERT BINARY BYTE TO OCTAL MAGNITUDE

$C80$G
$CBTMG

The ~~CBTA routine calls the $SAV'RG routine to save and restore
registers 3 - 5 of the calling task. Regsiters 1 and 2 are destroyed.
Outputs from the $CBOSG routine are:

The

•

The converted number, a maximum of six digits
the specified output area.

•

RO = the next

length,

available address in the output area
(the
pointer to the location following the last digit stored) •

~iCBOSG

5.2.3

routine does not return error conditions to the caller.

Convert Binary Byte to Octal Magnitude Routine ($CBTMG)

The $CBTMG routine converts an internally
3-digit ASCII octal number.
The $CBTMG
parameters:

routine

uses

the

stored

following

binary

predefined

byte

conversion

radix == 8.
field width = 3 characters
sign flag = UNSIGNED
leading zeroes flag = NOSUP (no suppression)
To call the $CBTMG routine:
•

Supply three input arguments in the task's source code:
•

in Register 0, the starting address of the output area in
which the converted 3-digit number is to be stored.

•

in Register 1, the binary byte to be converted in the low
order byte.

•

'to

Include the statement
CALL $CBTMG
in the source program.

The predefined conversion parameters are automatically pushed to the
stack on entry to the $CBTMG routine.
If the user specifies, via R2 =
0, that leading zeroes are to be suppressed, the NOSUP parameter is
reset.
In any case,
the $CBTMG routine passes the parameters in
Register 2 to the General Purpose Binary to ASCII Conversion Routine
($CBTA), which performs the actual conversion of the binary byte.
The $CBTA routine calls the $SAVRG routine to save and restore
registers 3 - 5 of the calling task. Registers 1 and 2 are destroyed.

5-9

$C8TMG
$ c BTA

CONVERT BINARY BYTE TO OCTAL MAUNITUDE
GENERAL PURPOSE BINARY TO ASCII

Outputs from the $CBTMG routine are:
•

The converted number, a maximum of three digits in length,
the specified output area.

•

RO = the next available address in the output area
(the
pointer to the location following the last digit stored) •

•

Rl = low order byte is
by the $CBTMG routine.

unchanged~

high order byte is

cleared

The $CBTMG routine does not return error conditions to the caller.

5.2.4

Example

Following are source statements that illustrate the
of the binary to octal conversion routines.

MOV

#OCOUT,RO

MOV

BNUM,Rl

MOV

#7,R2

CALL

$CBOMG

calling

sequence

;PUTS THE STARTING ADDRESS OF THE OUTPUT
;AREA IN RO.
;PUTS THE BINARY NUMBER TO BE CONVERTED
; IN Rl.
; PUTS THE VA:LUE 7 IN R2 (SETS THE ZERO
; INDICATOR F:LAG TO 1) TO SPECIFY THAT
;LEADING ZEROES ARE NOT TO BE SUPPRESSED.
;CALLS THE $CBOMG ROUTINE.

(continue)

5.3

GENERAL PURPOSE BINARY TO ASCII CONVERSION ROUTINE ($CBTA)

The $CBTA routine converts internally stored binary numbers to ASCII
decimal or octal numbers when called by the binary to decimal and
binary to octal conversion routines described in Sections 5.1 and 5.2
of this chapter. The $CBTA routine converts the values according to
predefined parameters which the calling routine passes as an input
argument in Register 2.
The $CBTA routine may be called directly by the user to convert
internally stored binary values to .an external ASCII format according
to user-defined conversion parameters, as described in the following
paragraph.
To call the $CBTA routine:
•

Supply three input arguments in the task's source code:
•

in Register 0, the starting address of the output area in
which the converted ASCII number is to be stored.

•

in Register 1, the binary value to be converted.

•

in Register 2, the conversion parameters, as follows:

5-10

GENERAL PURPOSE BINARY TO ASCII
RADIX-SOTO ASCII CONVERSION

the

$C8TA
$C5TA

Bits 0 - 7:

(low byte} must contain
radix ( 2 • -1 O• } •

Bit 8:

must contain the unsigned flag ( = 0) if
unsigned value to be converted; or must
contain the sign flag ( = 1)
if signed
value to be converted.

Bit 9:

zero suppression flag
suppression flag = 1.

Bit 10:

blank fill
flag
=
1
to
specify
replacement
of
leading zeroes with
blanks only if nonzero suppression flag
= 1.

conversion

nonzero

blank fill
flag
O to specify no
replacement of leading zeroes if bit 9 =
1.
Note:

Bits 11-15:

•

When the
zero
suppression
flag = 0,
the blank fill flag
is ignored.

must contain a numeric value from 1 - 32
specifying the field width.

Include the statement
CALL $CBTA
in the source program.

The $CEiTA routine calls the $SAVRG routine to save and restore
registers 3 - 5 of the caller. Registers 1 and 2 are destroyed. The
Integer Divide Routine
($DIV}
is called to perform the required
division.
The outputs from the $CBTA routine are:
•

The converted number, from 1 to 32 digits in
specified output area.

length,

the

•

RO = the next available address in the output area
(the
pointer to the location following the last digit stored} •

The $CBTA routine does not return error conditions to the caller.

5.4

RADIX-SO TO ASCII CONVERSION ROUTINE ($C5TA)

The $C5TA routine converts an internally stored 16-bit Radix-SO
to an ASCII character string.

value

To call the $C5TA routine:
•

Supply two input arguments in the task's source code:
•

in Register 0, the address at which the first byte of the
converted string is to be stored.

•

in Register
converted.

the

Radix-SO

5-11

value

which

$C5TA
•

RADIX-50TOASCll CONVERSION

Include the statement
CALL $C5TA
in the source program.

The $DIV routine is called to perform the required division.
The $C5TA routine does not use
destroyed.

registE~rs

3 - 5.

Registers 1 and 2 are

The outputs from the $C5TA routine are:
•

The converted ASCII characters, stored in a maximum
consecutive bytes in the specified output area.

•

RO = the address of the next byte
stored.

character

after

the

last

The $C5TA routine does not return error conditions to the caller.

5-12

three

CHAPTER 6
OUTPUT FORMATTING ROUTINES

The output formatting routines convert internally stored data to
external ASCII characters and format the converted characters to
produce.readable output.
There are four output formatting routines:
•

The Upper Case Text Conversion Routine
($CVTUC),
which
converts lower case ASCII text to upper case, as described in
Section 6.1.

Date String Conversion Routine ($DAT), which converts a
• The
three-word binary date to a nine-character ASCII output
string, as described in Section 6.2.1.

6.1

•

The Time Conversion Routine ($TIM), which converts the binary
time to an ASCII output string, as described in Section 6.2.2.

•

The Edit Message Routine ($EDMSG), which converts internally
stored
data
to the user-specified type of ASCII data
(alphanumeric, octal, decimal) and formats the converted data
to produce meaningful output for
printing or display, as
described in Section 6.3.

UPPER CASE TEXT CONVERSION ROUTINE ($CVTUC)

The $CVTUC routine converts lower case ASCII text to upper case.
The
routine performs a byte-by-byte transfer of the input ASCII character
string, converting all lower case alphabetic characters to upper case,
and transferring all upper case characters.
To call the $CVTUC routine:
•

•

Supply three input arguments in the task's source code:
•

in Register 0, the address
converted.

•

in Register 1, the address of the
upper case string.

•

in Register 2, the number of bytes in the
converted.

Include the statement
CALL $CVTUC
in the source program.

6-1

the

text

string

output

area
string

to
for
to

be
the
be

$CV TUC
$DAT

UPPER CASE TEXT CONVERSION
DATE STRING CONVERSION

The $CVTUC routine does not use registers 3 - 5 of the calling task.
The content of R2 (byte count) is de:3troyed on return to the calling
task.
Registers 0 and 1 are not altered.
The $CVTUC routine converts all ASCII
alphabetic characters in the
input string
to upper case.
Any oth1~r characters are moved from the
input area to the output area in their sequential positions.
The user
may specify the
input area address as the output area address (RO =
Rl) when the $CVTUC routine is called.
In this
instance,
the lower
case alphabetic characters are converted to upper case in place in the
input area.
The original lower case content of the input area is,
of
course, destroyed.

6.2

DATE AND TIME FORMAT CONVERSION

These routines convert the binary date and
time to formatted ASCII
output strings.
The date
is converted and formatted for output as
follows:
day-month-year.
The time is
forms:

conve~ted

and formatted for output in one of the following

hour
hour:minute
hour:minute:second
hour:minute:second:tick
These routines and the procedures for
detail in the following sections.

6.2.1

using

them

are

described

Date String Conversion Routine ($DAT}

The $DAT routine converts the three-word internal binary date to the
standard eight- or nine-character ASCII output format, as follows:
dd-mmm-yy
where:

dd
mmm
yy

day
(one character for 1 through 9 and
through 31)
month (first 3 letters)
year (last 2 dig~ts)

two

characters for 10

To call the $DAT routine, the user must:
•

Supply two input arguments in the program's source code:
•

in Register 0, the address of the output
the converted date is to be stored.

•

in Register 1, the address of the three-word
input area
in which the binary date is stored.
The input area must
contain the following:
word l
word 2
word 3

area

which

last two digits of year
a number from 1 - 12 (month of year)
a numeric value 01 - 31 (day of month)

6-2

May 1979

DATE STRING CONVERSION
TIME CONVERSION

•

$0 AT
$TIM

Include the statement
CALL $DAT
in the source program.

NOTE:: The $DAT routine does
input.

not

perform

validity

checking

the

The $DAT routine calls the $SAVRG routine to save and restore the
content of registers 3 - 5 of the calling task.
The $DAT routine uses
Register 2 and possibly destroys its content. Hence, the calling task
should save any critical value in Register 2 before calling the $DAT
routine. Outputs from the $DAT routine are the following:
•

The converted date string,

stored

the

specified

output

•

RO = the address of the next available location in the
area;

output

•

Rl = the next address (input Rl + 6) in the input area.

an~a.

6.2.2

Time Conversion Routine ($TIM)

The $TIM routine converts the binary time, in a standard format, to an
ASCII output string of the form:
HH: MM:: SS. S
The standard format for $TIM input values is shown
table.

the

following

Word

Significance

Output
Format

WDl

Hour-of-Day

WD2

Minute-of-Hour

- 23
0 - 59

WD3

Second-of-Minute

WD4

Tick-of-Second

depends on clock frequency

WD5

Ticks-per-Second

.s
.s

Value Range
0

- 59

depends on clock frequency

To call the $TIM routine:
•

Supply three input arguments in the task's source code:
•

in Register 0, the address of the output area in which
the converted time is to be stoted.

•

in Register 1, the starting address of the input area in
which the time values are stored.

•

in Register 2, the parameter count, where:
R2

= 0 or 1, to specify that the hour {word 1) is to be
converted in the format HH.

6-3

$TIM

TIME CONVERSION

R2 = 2, to specify that the hour and minute (words
and 2) are to be converted in the format HH:MM.
R2

3, to specify that the hour,

(words 1, 2, and
format HH:MM:SS.
R2

minute, and second
3) are to be converted in the

4 or 5, to specify that the hour, minute,
second,
and tick are to be converted in the format
HH:MM:SS.S (where .s =tenth of second).
NOTE

For HH, the $TIM routine returns one
character for values between 1 and 9 and
two characters for values greater than
9.

• Include the statement
CALL $TIM
in the source program.
The $TIM routine calls the $SAVRG routine to save and restore
registers 3 - 5 of the calling task. The contents of registers 0 and
1 are updated and returned to the calling task.
Register 2,
containing the parameter count, is destroyed.
The outputs from the $TIM routine are the following:
•

The converted time string, which is stored
output area.

the

specified

•

RO = the address of the next available location in the
area.

•

Rl = the address of the next word in the input area.

output

The $TIM routine calls two system library routines:
•

The $DIV routine, which performs the
convert binary values to ASCII words.

division

required

•

The $CBDAT routine, which actually
conversion, two digits at a time.

performs

the

time

6-4

May 1979

TIME CONVERSION

6.2.3

$Tl M

Example

Assume a program contains the following:
The input area containing the three-word binary date and the five-word
binary time:
BDBLK:

.WORJD 77.
.WORD 11.
.WORD 01.
.WORD 10.
• WORD 15 •
.WORD 35.
.WORD xx
.WORD x

;YEAR
;llTH MONTH (NOV)
;DAY
;HOUR
;MINUTES
;SECONDS

The output area:
DTBLK:

.BLKB

20.

6-4 .. 1

May 1979

$Tl M

TIME CONVERSION

•

= 2, to specify that the hour and

minute
(words
and 2) are to be converted in the format HH:MM.

3, to specify that the hour, minute, and second
(words 1, 2, and 3) are to be converted in the
fbrmat HH:MM:SS.

4'br 5, to specify that the hour, minute, second,
and tick are to be converted in the format
HH:MM:SS.S (where .s = tenth of second).

Include the statement
CALL $TIM
in the source program.

The $TIM routine calls the $SAVRG routine to save and restore
registers 3 - 5 of the calling task. The contents of registers 0 and
1 are updated and returned to the calling
task.
Register 2,
containing the parameter count, is destroyed.
The outputs from the $TIM routine are the following:
•

The converted time string, which is stored
output area.

the

specified

•

RO = the address of the next available location in the
area.

•

Rl = the address of the next word in the input area.

output

The $TIM routine calls two system library routines:

6.2.3

•

The $DIV routine, which performs the
convert binary values to ASCII words.

division

required

•

The $CBDAT routine, which actually
conversion, two digits at a time.

performs

the

time

Example

Assume a program contains the following:
The input area containing the three-word binary date and the five-word
binary time:
BDBLK:

. WORD 77 .
.WORD 11.
.WORD 01.
. WORD 10 .
• WORD 15 .
.WORD 35.
.WORD xx
.WORD x

;YEAR
;llTH MONTH (NOV)
;DAY
;HOUR
;MINUTES
;SECONDS

The output area:
DTBLK:

.BLKB

20.

6-4

EDIT MESSAGE

$EDMSG

The source statements:

MOV
MOV
CALL
MOVB

#DTBLK,RO
#BDBLK,Rl
$DAT
Ul,(RO}+

MOV

# 3. , R2

CALL

$TIM

;PUTS ADDRESS OF OUTPUT AREA IN RO.
;PUTS ADDRESS OF INPUT BINARY DATE AREA IN Rl.
;CALLS THE $DAT ROUTINE.
;PUTS TAB AFTER DATE IN OUTPUT BUFFER.
;RO NOW CONTAINS NEXT ADDRESS IN DTBLK FROM
;$DAT.
;Rl NOW CONTAINS ADDRESS OF NEXT WORD (THE
;HOUR 10) IN BDBLK FROM $DAT.
;SPECIFIES THE HH:MM:SS FORMAT FOR
;CONVERTED TIME.
;CALLS THE $TIM ROUTINE.

I
After execution, the output buffer will contain:
l-NOV-77

10:15:35

I
I

The time and date fields are left-justified.

6.3

GENERALIZED FORMATTING

Generalized output formatting is provided by the Edit Message Routine
($EDMSG}.
The $EDMSG routine allows the user to request the
conversion of internally stored data to ASCII decimal,
octal,
or
alphanumeric characters and to control the layout of the converted
characters to produce formatted output to be printed or displayed as
meaningful,
readable text.
The user may request the conversion of
strings of data and their formatting in columns. Varying ASCII data
types can be incorporated in a given formatted line of the output.
Spacing within lines and between lines can be controlled by the user.
The procedures for converting data and producing formatted output with
the $EDMSG routine are described and illustrated in the following
section.

6.3.1

Edit Message Routine ($EDMSG)

The $EDMSG routine edits internally formatted data,
in an argument
block:,
to external format and stores it in the calling task's output
block:. The editing performed by the $EDMSG routine is specified by
user directives within an input string.
Input strings may contain
ASCII text as well as editing directives.
Any non-editing directive
characters are simply copied into the output block.
Any number of
directives may appear in an input string.
Input strings must be in
ASCI2: format.

6-5

May 1979

$EDMSG

EDIT MESSAGE

Editing directives are of two types:
data
control. The directives must be of the form:

conversion

and

format

editing

directive

%1, %nl or %Vl
where:
%

is a delimiter which identifies an
the $EDMSG routine.

is an optional repeat count
(decimal number}
specifying
the number of times the editing operation is to be
repeated by the $EDMSG routine.
If n
0 or
is not
specified, a repeat count of 1 is assumed.

specifies that the repeat count is a
word in the task's argument block.
repeat count of 1 is assumed.

is an alphabetic letter specifying one of the editing
operations to be performed by the $EDMSG routine, as shown
in Table 6-1.

I
I

See Section 6.3.2 for examples
strings.

editing

6-6

value in the next
If the value is 0, a

directive

use

input

May 1979

EDIT MESSAGE

$EDMSG

Table 6-1
$EDMSG Routine Editing Directives
Directive

Form

Operation

Move the ASCII character from address
in ARGBLK to OUTBLK.

%nA

Move the next n ASCII characters
address in ARGBLK to OUTBLK.

%VA

Use the value in the next word
in
ARGBLK as repeat count and move the
specified number of ASCII characters
from address in ARGBLK to OUTBLK.

(binary
byte to
octal
conversion)

Convert
the next binary byte from
address in ARGBLK to octal number
and store result in OUTBLK.

%nB

Convert the next n binary bytes from
address in ARGBLK to octal numbers,
and store results in OUTBLK;
insert
space between numbers.

%VB

Use the value in the next word in
ARGBLK as repeat count, convert the
specified number of binary bytes from
address in ARGBLK to octal numbers,
and store results in OUTBLK;
insert
space between numbers.

Convert the binary value in the next
word in ARGBLK to signed decimal and
store result in OUTBLK.

%nD

Convert the next n binary values in
ARGBLK to signed decimal and store
results in OUTBLK;
insert tab between
numbers.

%VD

Use the value in the next word
in
ARGBLK as repeat count, convert the
specified number of binary values to
signed decimal and store results in
OUTBLK;
insert tab between numbers.

(ASCII*
string)

(binary to
signed
decimal
no
suppression
conversion)

from

Extended ASCII characters consist of the printable characters in
the 7-bit ASCII code.
If non-printable characters appear in an
ASCII input string, the E directive replaces them with a space,
while the A directive transfers the non-printable characters to the
output block.
KEY:

ARGBLK

= The argument block containing the binary data

OUTBLK

= The output block in which $EDMSG is to store output.

to be
converted,
the addresses of ASCII and extended ASCII
characters or the address of a double precision
value.

(continued on next page)

6-7

May 1979

$EC~MSG

EDIT MESSAGE

Table 6-1 (Cont.)
$EDMSG Routine Editing Directives
Directive

Form

Operation

Move the extended ASCII character from
the address in ARGBLK to the OUTBLK.

%nE

Move n extended ASCII characters
the address in ARGBLK to OUTBLK.

%VE

Use the value in the next word in
ARGBLK as repeat count and move the
specified number of ASCII characters
from the address in ARGBLK to OUTBLK.

Insert
OUTBLK.

%nF

Insert n
OUTBLK.

%VF

Use the value in the next word in
ARGBLK as repeat count,
and insert
specified
number
of
form
feed
characters in OUTBLK.

Use the next value in ARGBLK
address of an ASCIZ string
logically included in
the
string at this point.

(binary to
decimal
magnitude,
Cl suppress
c:onver s :Lon)

Convert the binary value in the next
word in ARGBLK to decimal magnitude
with leading zeroes suppressed and
store the result in OUTBLK.

%nM

Convert the next n binary values in
ARGBLK to decimal
magnitude
with
leading zeroes suppressed and store
the results in OUTBLK;
insert tab
between numbers.

%VM

Use the value in the next word in
ARGBLK as repeat count, convert the
specified number of binary values to
decimal magnitude with leading zeroes
suppressed and store the results in
OUTBLK;
insert tab between numbers.

(extended
P.1SCI I*)

(form
feed)

(include
Jl~SCI Z
string)

from

form

feed

character

form

feed

characters

as the
to be
format

KEY:

ARGBLK = The argument block containing the binary data to be
converted,
the addresses of ASCII and extended ASCII
characters or the address of a double precision
value.
OUTBLK = The output block in which $EDMSG is to store output.
(continued on next page)

6-8

May 1979

EDIT MESSAGE

$EDMSG

Table 6-1 (Cont.)
$EDMSG Routine Editing Directives
r-··~~-~~~~·~·~~~~~~~--.-~~~~~--~~~~~~~~~~~~~~~~----.

Directive

Form

Operation

Insert
OUTBLK.

%nN

Insert n
OUTBLK.

%VN

Use the value in the next word in
ARGBLK as repeat count, and insert the
specified number
of
CR
and
LF
characters in OUTBLK.

(binary to
signed
octal
conversion)

Convert the binary value in the next
word
in ARGBLK to signed octal and
store the result in OUTBLK.

%n0

Convert the next n binary values in
ARGBLK to signed octal and store the
results in OUTBLK;
insert tab between
numbers.

%VO

Use the value in the next word
in
ARGBLK as repeat count, convert the
specified number of binary values to
signed octal and store the results in
OUTBLK;
insert tab between numbers.

(binary to
octal magnitude conversion)

Convert the binary value in the next
word in ARGBLK to octal magnitude and
store the result in OUTBLK.

%nP

Convert the next n binary values in
ARGBLK to octal magnitude and store
the results
in OUTBLK;
insert tab
between numbers.

%VP

Use the value in the next word
in
ARGBLK as repeat count, convert the
specified number of binary values to
octal magnitude, and store the results
in
OUTBLK;
insert
tab
between
numbers.

(new line-carriage return/line
feed)

KEY:

and
CR

and

characters in
LF characters in

ARGBLK = The argument block containing the binary data
to be
converted,
the addresses of ASCII and extended ASCII
characters or the address of a double precision
value.
OUTBLK

= The output block in which $EDMSG is to store output.
(continued on next page)

6-9

May 1979

$EDMSG

EDIT MESSAGE

Table 6-1 (Cont.)
$EDMSG Routine Editing Directives
Directive
R

Form

Operation

Convert the Radix-50 value in the next
word in ARGBLK to ASCII and store the
result in OUTBLK.

%nR

Convert the next n Radix-50 values in
ARGBLK to ASCII and store the results
in OUTBLK.

%VR

Use the value in the next word in
ARGBLK as repeat count, convert the
specified number of Radix-50 values to
ASCII,
and
store the results in
OUTBLK.

Insert a space in OUTBLK.

%nS

Insert n spaces in OUTBLK.

%VS

Use the value in the next word in
ARGBLK as repeat count, and insert the
specified number of spaces in OUTBLK.

Convert the double-precision unsigned
binary value at the address in ARGBLK
to decimal and store result in OUTBLK.

%nT

Convert the next n double-precision
binary values starting at the address
in ARGBLK to decimal and store results
in
OUTBLK:
insert
tab
between
numbers.

%VT

Use the value in the next word in
ARGBLK as repeat count, convert the
specified number of double-precision
binary values starting at the address
in ARGBLK to decimal,
and store the
results in OUTBLK:
insert tab between
numbers.

(Radix-50
to ASCII)

(space)

(double precision
binary to
decimal
conversion)

KEY:

6-10

May 1979

EDIT MESSAGE

$EDMSG

Table 6-1 (Cont.)
$EDMSG Routine Editing Directives
Dire?ctive

u
(binary to
de!c imal magnitude, no
0 suppress
conversion)

Form

Operation

Convert the binary value in ARGBLK to
decimal
magnitude with no leading
zeroes suppressed and store result in
OUTBLK.

%nU

Convert the next n binary values in
ARGBLK to decimal magnitude with no
leading zeroes suppressed and store
results in OUTBLK; insert tab between
numbers.

%VU

Use the value in the next word in
ARGBLK as repeat count, convert the
specified number of binary values to
decimal
magnitude with no leading
zeroes suppressed and store results in
OUTBLK; insert tab between numbers.

Convert Radix-50 file name string in
ARGBLK
to ASCII string :n format
NAME.TYP;
convert
octal
version
number, if present, to ASCII and store
results in OUTBLK.

%nX

Convert next n Radix-50 file name
strings in ARGBL~ to ASCII string in
format
NAME.TYP;
convert
octal
version numbers, if present, to ASCII
and store results in OUTBLK;
insert
tab between strings.

%vx

Use the value in the next word in
ARGBLK
as
repeat
count, convert
specified number of Radix-50 file name
strings to ASCII strings in format
NAME.TYP;
convert
octal
version
numbers, if present, to ASCII and
store results in OUTBLK;
insert tab
between strings.

Convert the next three binary words
in ARGBLK to ASCII date in format
dd-mmm-yy and store in OUTBLK.
In
this directive a repeat is acceptable,
but will be ignored.

(file na:me
string
conversion)

(date conversion)

KEY:

ARGBLK = The argument block containing the binary data to be
converted, the addresses of ASCII and extended ASCII
characters or the address of a double precision
value.
OUTBLK = The output block in which $EDMSG is to store output.
(continued on next page)

6-11

May 1979

$EDMSG

EDIT MESSAGE

Table 6-1 (Cont.)
$EDMSG Routine Editing Directives
Directive

z
(binary time
to ASCII
conversion)

Operation

%OZ
or

Convert binary hour-of-day in the next
word of ARGBLK to ASCII and store in
OUTBLK in format HH.

%1Z

%2Z

Convert the binary hour-of-day and
minute-of-hour in the next two words
of ARGBLK to ASCII and store in OUTBLK
in format HH:MM.

%3Z

Convert
the
binary
hour-of-day,
minute-of-hour,
and second-of-minute
in the next three words of ARGBLK to
ASCII and store in OUTBLK in format
HH:MM:SS.

%4Z
or
%5Z

Convert the binary
hour-of-day,
minute-of-hour,
second-of-minute, and
ticks-of-second or ticks-per-second in
the next five words of ARGBLK to ASCII
and store
in
OUTBLK
in
format
HH:MM:SS.S,
where
.s = tenth of
second.

%n<

Insert n ASCII spaces followed by a
field mark
(NUL) in OUTBLK to define
a fixed length byte field.
The output
pointer will point to the first space.

%n>

Increment the OUTBLK pointer until a
field mark
(NUL)
is located or the n
repeat count is exceeded.

(define
byte
field)
(locate
field
mark)

Form

KEY:

ARGBLK

= The argument block containing the binary data

to be
converted,
the addresses of ASCII and extended ASCII
characters or the address of a double precision
value.

OUTBLK = The output block in which $EDMSG is to store output.
Prior to calling the $EDMSG routine~,
appropriate argument block, as follows:

the

user

must

set

the

•

If ASCII or extended ASCII characters are to be moved to the
output block, the argument block must contain the addresses of
the ASCII characters.

•

If binary byte to octal conversion is to be performed,
the
argument block must contain the addresses of the binary bytes.

•

If binary values are to be converted, the argument block
contain the values.

6-12

must

May 1979

EDIT MESSAGE

•

If file name string conversion is to be
argument block must contain the following:

SEDMSG

specified,

the

Word 1
Radix-SO file name
Radix-SO file name
Word 2
Word 3
Radix-SO file name
Radix-SO file type
Word 4
Word 5 = binary version number
•

If the binary date is to be converted, the argument block must
contain the following:
Word l
year (last 2 digits)
Word 2 = number (1 - 12) of month
Word 3
day of month (1 - 31)
There is no validity checking of the date values.
If
erroneous date values are specified, output results will
be unpredictable.

•

If the binary time is to be converted, the argument block must
contain the following:
Word
Word
Word
Word
Word

1 = hour-of-day (0 - 23)
2
minute-of-hour (0 - S9)
3
second-of-minute (0 - S9)
4 = tick-of-second (depends on clock frequency)
5
ticks-per-second (depends on clock frequency)

To call the $EDMSG routine:
•

•

Supply three input arguments in the task's source code:
•

in Register 0, the starting address of the output block.

•

in Register 1, the address of the input string.

•

in Register 2,
block.

the

starting

address

the

argument

Include the statement
CALL $EDMSG
in the source program.

The $EDMSG routine calls the $SAVRG routine to save and restore
registers 3 - S of the calling task. The $EDMSG routine calls the
output data conversion routines described in Chapter S and in Section
6.2 of this chapter to convert binary data to the specified external
format.
See the detailed descriptions · of individual conversion
routines for specific output formats.
The $EDMSG routine scans the input string, character-by-character. If
non-directive or ("unknown" directive) characters are found, they are
transmitted directly to the task's output block. When a % delimiter
is found, the $EDMSG routine interprets the character(s) following the
delimiter. If a data conversion directive is encountered, the $EDMSG
routine accesses the argument block, converts the.specified data, and
transmits it to the output block. If a format control directive is
encountered, the routine generates the specified control(s)
and
transmits the data to the output block.
If the % delimiter is not
followed by a valid operator, or if multiple delimiters are found, the
$EDMSG routine transmits the first and any subsequent delimiters not
followed by a valid directive character to the output block.
6-13

$EDMSG

EDIT MESSAGE

Outputs from the $EDMSG routine are:
•

The converted/formatted data in the output block.

•

RO = the address of the next
block.

available

byte

•

Rl = the length of the output block
transferred to the output block) •

(the

number

•

R2 = the address of the next argument in the argument block.

The user may call an appropriate
converted/formatted data.

6.3.2

output

routine

the

output
of bytes

output

the

Examples

Examples of the use of the $EDMSG routine to convert and format output
data are presented in this section.
EXAMPLE 1:

Assume a program contains the following:

An input string (ISTRNG)
ISTRNG:

.ASCIZ

/%F%12S***TEXT***%3N%8S%VD%2N%12S***END****/

The argument block
ARGBLK: .WORD 3 •
• WORD 99 •
• WORD -37 .
• WORD 137.
The output block (OUTBLK)
OUTBLK:

.BLKB 100.

The source statements
START:

MDV #OUTBLK,RO
MOV #ISTRNG,Rl
MOV #ARGBLK,R2
CALL $EDMSG

The following output will be produced.
***TEXT***
99

-37

137

***END*****

6-14

OUTPUT FORMATTING ROUTINES

The editing directives, shown above, and their effect are:
%F

insert a form feed in OUTBLK (start a new page).

%12S

insert 12 spaces in OUTBLK and move the ASCII string to
OUTBLK
(indent the first line 12 spaces and insert the
header ***TEXT***).

%3N

insert 3 pairs of CR-LF characters in OUTBLK (generate
blank lines) •

%8S

insert 8 spaces in OUTBLK (inderit the next line 8 spaces).

%VD

use the first value (3) in ARGBLK as the repeat count and
convert the next 3 binary values in ARGBLK to signed
decimal; store each value, followed by a tab,
in OUTBLK
(output three signed decimal numbers in columnar format).

%2N

insert 2 pairs of CR-LF characters in OUTBLK (generate
blank line) .

%12S

insert 12 spaces at the beginning of a line in OUTBLK and
move the ASCII string to OUTBLK
(indent 12 spaces and
insert the text ***END****) •

EXAMPLE 2:

two

one

Assume a program contains the following:

An input string (INSTR)
INSTR:

.ASCIZ

/%FSS***B.

MABRY WORK REPORT FROM %Y TO %Y ***/

The argument block (IBLK)
IBLK:

.. WORD 77 •

;YEAR

,,WORD 8.

;8TH MONTH (AUG)

,,WORD 22.

;DAY

• WORD 77 •

;YEAR

·.WORD 9.

;9TH MONTH (SEP)

• WORD 16 •

;DAY

The output block (PRBLK)
PRBLK:

.BLKB 100.

The source statements
BEGIN:

MOV #PRBLK,RO
MOV #INSTR,Rl
MOV #IBLK ,R2
CALL $EDMSG

6-15

OUTPUT FORMATTING ROUTINES
The following output will be produced:
***B.

MABRY WORK REPORT FROM 22-AUG-77 TO 16-SEP-77***

The editing directives in the example and their effect are:
%F

insert a form feed in PRBLK (start a new page).

%SS

insert 5 spaces in PRBLK and move ASCII string to PRBLK
(indent the line 5 spaces and output the header ***B.
MABRY WORK REPORT FROM) •

convert the next three words in IBLK to formatted date and
store in PRBLK followed by ASCII text (insert 22-AUG-77 TO
in header line) •

convert next three words in IBLK to formatted date and
store in PRBLK followed by ASCII text (insert 16-SEP-77***
in header line) •

6-16

CHAPTER 7
DYNAMIC MEMORY MANAGEMENT ROUTINES

The dynamic memory management routines allow the user to manually
manage the space in a task's free dynamic memory.
The free dynamic
memory consists of all memory extending from the assembled code of the
task to the highest virtual address owned by the task, excluding
resident libraries.
Initially, free dynamic memory is allocated as one large block,
from
the highest available memory address downward.
Subsequent memory
block allocations are made within the available ·memory blocks.
Available memory blocks are maintained as a linked list of blocks in
ascending order, pointed to by a two-word listhead.
Each free memory
block contains a two-word control field, where:
•

The first word contains the address of the
block, or zero if there is not another block.

available

•

The second word contains the size of the current block.

Memory allocation is either on a first-fit or best-fit basis.
Allocation is always made from the top of the selected available
dynamic memory block. The second word of the block is adjusted to
reflect the new size of the current block of available dynamic memory.
As memory blocks are allocated completely, they are removed from the
free memory list.
When memory blocks are deallocated (released), they are returned to
the free memory l:lst.
The released memory blocks are relinked to the
free memory list in ascending address order.
If possible,
released
memory blocks are merged with adjacent memory blocks to form a single,
large block of free dynamic memory.
There are three routines that are called
management functions:

perform

dynamic

memory

•

Initialize Dynamic Memory Routine ($INIDM), which
the task's free dynamic memory.

•

Request Core Block Routine ($RQCB), a system library routine
which allocates blocks of memory in the free dynamic memory.

•

Release Core Block Routine ($RLCB), a system library routine
which
releases
(deallocates)
previously allocated memory
blocks in the executing task's free dynamic memory.

7-1

initializes

$1Nl0M
7.1

INITIALIZE DYNAMIC MEMORY

USAGE CONSIDERATIONS

To use the dynamic memory management routines, the user
the following in the source program:
•

provide

A two-word free memory listhead:
FREEHD:

•

must

.BLKW 2

The appropriate call argument(s) and statement for
the given
routine,
as described in Sections 7.2, 7.3, and 7.4 of this
chapter.

At task build time, the user must specify the following
LB: [l,l]VMLIB/LB:INIDM:EXTSK
to include the memory management modules INIDM and EXTSK in the task.

7.2

INITIALIZE DYNAMIC MEMORY ROUTINB ($INIDM)

The $INIDM routine establishes the initial state of the free dynamic
memory available to the executing task.
The free dynamic memory
consists of all memory extending from the end of the task code to the
highest
virtual
address used by the task,
excluding resident
libraries.
To call the $INIDM routine:
•

Specify, in
listhead.

•

Include the statement

the

address

the

free

memory

CALL $INIDM
in the source program.
The outputs from the $INIDM routine are:

the first address in the task.

the address following thE~ task image (the
address in the free dynamic memory) .

•

last

available

= the size of the free dynamic memory.

For the RSX-llM system, the $INIDM routine deallocates any previous
task memory extension made by issuing the EXTK$ executive directive or
by calling the $EXTSK routine (see Chapter 8).
The $INIDM routine performs the following:
•

Rounds the free dynamic
four-byte boundary.

memory

•

Initializes the free dynamic memory as a single large block of
memory.

7-2

base

address

the

May 1979

INITIALIZE DYNAMIC MEMORY
REQUEST CORE BLOCK

•

Computes the total size of the free dynamic memory.

•

Sets the outputs in Register 0 - 1 and returns to the
task.

$1NIDM
$RQC8

calling

Registers 3 - 5 are not used.
After the dynamic memory has been initialized,
the user's task may
call the system library routines: Request Core Block Routine ($RQCB)
to allocate memory blocks in the dynamic memory:
and subsequently
call the Release Core Block Routine ($RLCB) to release the allocated
blocks.

7.3

REQUEST CORE BLOCK ROUTINE ($RQCB)

The $RQCB system library routine determines whether there is enough
space available in the free dynamic memory to satisfy an executing
task's memory allocation request.
If memory is available, the $RQCB
routine allocates the requested memory block.
To use the $RQCB routine the user must initialize dynamic memory
(usually with the $INIDM routine) then:
•

Supply two input arguments in the task's source code:
•

in Register O, the address of the free memory listhead.

•

in Register 1, the size (number of bytes) of
block to be allocated, where:

the

memory

specify

Rl = a value greater than or equal
best fit allocation.
Rl

•

once

to specify first
fit
a value less than 0,
allocation.
(The value is negated to determine
block size.)

Include the statement
CALIJ $RQCB
in the source

pro~ram.

The $RQCB routinE~ calls the $SAVRG routine to save and restore
registers 3 - 5 of the calling task. Register 2 is destroyed.
The $RQCB routine returns the following output to the calling task:
•

•

Successful allocation:
dynamic memory address of the allocated block.

•

Rl
the actual size of the allocated block
size rounded to next two-word boundary.

•

Condition Code C bit = clear.

Unsuccessful allocation:
•

Condition Code C bit

set.

7-3

{requested

$RLC8
7.4

RELEASE CORE BLOCK

RELEASE CORE BLOCK ROUTINE ($RLCB)

The $RLCB system library routine releases a block of previously
allocated
dynamic
memory
to the free memory list, which is
sequentially ordered by the memory addicesses of the blocks themselves.
To call the $RLCB routine:
•

•

Supply three input arguments:
•

in Register 0, the address of the free memory listhead.

•

in Register 1, the size (number of bytes} of the block to
be released.

•

in Register 2, the memory address
released.

the

block

Include the statement
CALL $RLCB
in the source program.

The $RLCB routine calls the $SAVRG system routine to save and
subsequently restore Registers 3 - 5 of the calling task. Register 0
is unchanged. Registers 1 and 2 are destroyed.
The output from the $RLCB routine is the released block.
The $RLCB
routine searches the free memory list until the proper address slot is
found, then the released block is merged into the list.
If possible,
the memory block to be released is mer~red with adjacent blocks already
in the free memory list.

7-4

CHAPTER 8

VIRTUAL MEMORY MANAGEMENT ROUTINES

The virtual memory management routines perform memory allocation and
deallocation by paging to and from disk file storage to accommodate
tasks that require more memory than that available in the task's free
dynamic memory at any given time. That is, the routines allow the
user to bring pages into memory when they are needed, hold them there
until they are no longer needed, swap the pages out, and reallocate
thcair memory space to other pages. These routines do not require the
memory management hardware, and are not related to memory management
directives.
The virtual memory management routines
functions:
•

Virtual memory initialization.

•

Dynamic memory allocation.

•

Virtual memory allocation.

•

Page management.

perform

the

following

major

Although the user may call the individual virtual memory management
routines, greater efficiency is gained by using them as an automatic
control system by calling only key routines, as follows:
•

The Initialize Virtual Memory
Routine
($INIVM),
which
initializes the task's dynamic memory and the disk work file,
as described in Section 8.2@

•

The virtual memory allocation routines:
Allocate Virtual
Memory Routine
($ALVRT)
and Allocate Small Virtual Block
Routine ($ALSVB) , which manage the allocation of large and
small page blocks to enable page swapping to and from dynamic
memory, as described in Section 8.4.

•

Four page management routines:
•

The Convert and Lock Page Routine
($CVLOK) ,
which
converts a virtual address to a dynamic memory address
and sets a lock byte in the memory page to prevent its
being swapped out of memory until it is no longer needed.
(See Section 8.5.1.)

•

The Unlock Page Routine ($UNLPG), which clears the lock
byte in a memory-resident page so that it can be released
and its memory space reallocated to another page.
(See
Section 8.5.7.)

8-1

VIRTUAL MEMORY MANAGJ~MENT ROUTINES
•

The Convert Virtual to Real Address Routine
($CVRL),
which converts a virtual address to a dynamic memory
address.
(See Section 8.5.2).

Write-marked Page Routine ($WRMPG) , which sets the
• The
(See Section
"written into" flag of memory pages.
8.5.5).

8.1

GENERAL USAGE CONSIDERATIONS

To call the virtual memory management i:outines, the user must provide
the appropriate call arguments and statements in the source program,
as described in Sections 8.2 through 8 .. 5 of this chapter.
The user's task must contain an error handling routine,
in Section 8.1.1.

described

At task build time, the user must specify the file and the virtual
memory management modules required by the task, as described in
Section 8.1.2.

8.1.1

User Error Handling Requirements

There are four virtual memory management routines that detect fatal
error conditions for which a user-written error handling routine,
entitled $ERMSG, is required. The routines are:
•

Allocate Block Routine ($ALBLK) which is
other virtual memory management routines.

called

•

Allocate Virtual Memory Routine! ($ALVRT) which is called by
the user or by the Allocate Small Virtual Block Routine
($ALSVB).

•

Read Page Routine ($RDPAG) which is called
Virtual to Real Address Routine! ($CVRL).

•

Write Page Routine ($WRPAG) which is called by
Routine ($GTCOR).

the
the

several

Convert
Get

Core

In conjunction with the $ERMSG routine,
the user must include
definitions of three global error codes and one global severity code
in the task. The symbolic error codes are:
E$R4

(used by the $ALBLK routine when there
memory available for allocation.)

E$R73

(used by the $RDPAG and $WRPAG routines when a work
file I/O error occurs during an attempt to swap pages
between resident memory and disk storage.)

E$R76

(used by the $ALVRT routine when there
storage available for allocation.)

dynamic

virtual

The severity code is:
S$V2

(used by the four routines
fatal
error
that must
execution can resume.)

8-2

cited above to denote a
be corrected before task

VIRTUAL MEMORY MANAGEMENT ROUTINES
When a fatal error occurs, the detecting routine
arguments:
Register 1

sets

two

input

low byte: error code
high byte: severity code (always S$V2)

Register 2 = argument block address
and issues the call
CALL $ERMSG
If the user has not defined the error handling routine within the
task, the undefined global symbol diagnostic message will be output at
task build time.
A typical error handling routine would output a message to indicate
the specific error condition, close all files (including the work
file), and exit.
The user's error handling routine should not attempt to return to the
virtual memory management routine that detected the fatal error, since
no meaningful output would result.

8.1.2

Task Building Requirements

TherE~

are two versions of the virtual memory management routines:
the
statistical version and the non-statistical version. Each version
consists of twelve program modules, containing one or more routines,
and a data storage module. Individual routines in the virtual memory
management routines library may reference other routines.
The
relationship of the modules and routines in the library is shown in
Table 8-1.

8-3

VIRTUAL MEMORY MANA.GEMENT ROUTINES

Table 8-1
Content of the Virtual Memory Management Library File
Module Name
Statistical

Name of
Routine(s}

Routines Referenced

Non-statistical

ALBLK

$ALBLK

$GTCOR, $EXTSK, $WRPAG

ALSVB

$ALSVB

$ALVRT, $WRMPG, $CVRL,
$ALBLK, $RQVCB, $FNDPG,
$RDPAG

CVRS

CVRL

$CVRL

$FNDPG, $ALBLK, $RDPAG

EXTSK

EXT SK

$EXTSK

(none)

FNDPG

$FNDPG

{none}

GTCOS

GTCOR

$GTCOR

$EXTSK, $WRPAG

INIDM*

$INIDM

$EXTSK

IN IVS

INIVM

$INIVM

$ALBLK, $GTCOR, $EXTSK,
$WRPAG

MRKPG

$LCKPG
$UNLPG
$WR.MPG

$FNDPG
$FNDPG
$FNDPG

RD PAS

RDPAG

$RDPAG
$WR.PAG

{none}

RQVCB

$RQVCB

{none}

VMUTL

$CVLOK

$CVRL, $LCKPG, $FNDPG,
$ALBLK, $RDPAG

VMDAS

VMDAT

Global data storage module

* The INIDM module is a dynamic memory management module {see Chapter
7)
that normally is used in conjunction with the virtual memory
management routines.

8-4

VIRTUAL MEMORY INITIALIZATION

$1NIVM

Four modules in the statistical version of the routines set up and/or
maintain statistics of the usage of the work file and memory.
These
modules and their associated statistical data fields are:
•

The INIVS modules, which initializes three double-word fields:
the total work file access field ($WRKAC);
the work file read
count field ($WRKRD);
and the wo~k file write count field
($WRKWR).
Each of these fields is a double word integer
contained in the global data storage module
(VMDAS)
for
the
statistical version of the routines.

•

The CVRS module, which maintains the count of total work
accesses in the $WRKAC field.

•

The RDPAS module, which maintains a total of the work file
reads in the $WRKRD field and a total of the work file writes
in the $WRKWR field.

•

The GTCOS module, which maintains a count of the total amount
of free dynamic memory in the $FRSIZ single-word field.
This
field must be defined and initialized in the source program.

file

The statistical version of the virtual memory management routines does
not
automatically
report these statistics.
It is the user's
responsibility to provide for the output of the statistical data in
the fields described above if the statistical version of the routines
is used.
To use the statistical routines, the user must specify, at task build
time,
the virtual memory management routines library file, the names
of all statistical modules whose routines will be used at task
execution time,
and the name of the global data storage module. The
only optional modules are ALSVB and INIDM.
Following
is
a
specification that identifies all modules of the statistical version
of the routines.
LB: [l,l]VMLIB/LB:ALBLK:ALSVB:ALVRT:CVRS:EXTSK:FNDPG:GTCOS
LB: [l,l]VMLIB/LB:INIVS:MRKPG:RDPAS:RQVCB:VMUTL:INIDM:VMDAS
The non-statistical routines use the global data storage module,
VMDAT.
To use the non-statistical routines, the user must specify, at
task build time, the virtual memory management routines library file,
the names of all non-statistical modules whose routines will be used
at task execution time, and the name of the global data storage
module.
The only optional modules are ALSVB and INIDM.
Following is
a specification that identifies all modules of the non-statistical
version of the routines.
LB: [l,l]VMLIB/LB:ALBLK:ALSVB:ALVRT:CVRL:EXTSK:FNDPG:GTCOR
LB: [l,l]VMLIB/LB:INIVM:MRKPG:RDPAG:RQVCB:VMUTL:INIDM:VMDAT

8.2

VIRTUAL MEMORY INITIALIZATION ROUTINE ($INIVM)

The $INIVM routine initializes the task's free dynamic memory, sets up
the page address control list, and initializes the user's disk work
file to enable memory-to-disk page swapping.
Disk work file capacity
is 64K words.

8-5

$1NIVM

VIRTUAL MEMORY INITIALIZATION

To use the $INIVM routine:
•

Define and initialize a two-word field named $FRHD.
the field, include the code

To define

$FRHD:: .BLKW 2.
in the source program. To initialize the field,
store
starting address of the free dynamic memory in $FRHD.
•

the

Define three global symbols in the source program:
W$KLUN

Logical unit number (LUN) to be used for
the work
file.
The user is also responsible for assigning
this LUN to a disk device.

W$KEXT

Work file extension size (in blocks).
A negative
number indicates that the extend should first be
requested as a contiguous allocation of disk blocks.
A positive number indicates that the extend need not
be contiguous.

N$MPAG

Fast page search page count.
If there is sufficient
dynamic memory to allocate at least the number of
pages specified, 512 words of dynamic memory will be
set
aside
to
speed
up
the
searching
of
memory-resident pages.

•

Specify, in Register 1, the highest address of the task's free
dynamic memory.

•

Include the statement
CALL $INIVM
in the source program.

NOTE: Before calling the $INIVM routine, the task may call the $INIDM
routine (see Chapter 7), which returns the last address of dynamic
memory and the total size of dynamic mE~mory.
The outputs from the $INIVM routine are:
•

Initialization successful:
Condition Code C bit

= clear.

and
RO
•

= 0.

Initialization failure:
Condition Code C bit

set.

and
RO
RO

-2 to indicate work file open failure.
-1 to indicate work file mark-for-deletion failure.

Also, the FCS error code may be examined at offset F.ERR
in the work file FOB. The address of the FOB is stored
in the word $WRKPT.

8-6

May 1979

VIRTUAL MEMORY INITIALIZATION

$1NIVM

The interaction of the $INIVM routine with the user's task and the
Allocate Block Routine ($ALBLK) is shown in Figure 8-1 and described
below.

s=)-------c~
Call $SAVRG tcj
save! task's
---11
.....(
R3- R5
_

$SAVRG

)
_

E
Set new high
dynamic memory
address

$SAVRG

ear

Clec1r memory
control fields and
lists; force old
pagos out of
memory

RO; clear C
t; transfer to
SAV RG to restore
3 - R5 and return

Set C bit; transfer
to $SAVRG to
restore R3 - R5
and return

yes

Set iup new
address control
list; call $ALBLK
to allocate
control list
page block

1----...

$ALBLK

E--·Call $ALBLK }
to allocate block
for 1first memory
page

· - -.......

~ALBLK

SetR0=-1

)

----..----

=~~E~~v }-i__w_O_~r_e~-f-~l_i;_k_~----<
Figure! 8-1

ark

file for
eletion after
ose

Set RO= -2

General Block Diagram of the $INIVM Routine

8-7

$1NIVM

VIRTUAL MEMORY INITIALIZATION

The $INIVM routine calls the $SAVRG routine to save
restore registers 3 - S of the calling task.

and

subsequently

Starting at the high address of the calling task's free dynamic
memory, the $INIVM routine clears control fields and the page address
control listhead. The $INIVM routine then sets up the heading for a
new page address control list and calls the Allocate Block Routine
{$ALBLK) to allocate a memory page block for the control list.
The
$INIVM routine then calls the $ALBLK routine to allocate a page block
for the first memory page for the calling task.
The $INIVM routine
links the first allocated page to the page control list.
The $INIVM routine initializes {opens) the user's disk work file.
If
the file is opened successfully, the~ $INIVM routine attempts to mark
it for deletion.
This ensures that the file will be deleted
automatically when it is closed, or if the task terminates abnormally
or exits. Note that the work file may be closed by the following
operation: CLOSE$ $WRKPT. If the routine is successful, the c bit in
the Condition Code is cleared, and control is transferred to the
$SAVRG routine to restore registers R3 - RS and return to the calling
task.
If the work file is not opened successfully, the $INIVM routine sets
the C bit in the Condition Code, sets RO = -2, and transfers to the
$SAVRG routine.
If the work file is not succ7ssfully :marked for deletion, the $INIVM
routine sets the C bit in the Condition Code, sets RO = -1, and
transfers to the $SAVRG routine.
The $SAVRG routine restores registers R3
RS and returns
calling task. The original content of RO - R2 is destroyed.

8.3

the

CORE ALLOCATION ROUTINES

The core allocation routines manage the allocation and deallocation of
space in the free dynamic memory of the executing task. The core
allocation routines are:
•

The Allocate Block Routine {$ALBLK) , which provides the
interface between the executing task and the other core
allocation routines. That is, the executing task is provided
all the services of the core allocation routines by simply
calling the $ALBLK routine, or those routines that call the
$ALBLK routine.

•

The Get Core Routine {$GTCOR) , which is always called by the
$ALBLK routine to perform the necessary processing to effect
allocation of the requested memory space from the free dynamic
memory.

•

The Request Core Block Routine {$RQCB), which is called by the
$GTCOR routine to allocate the requested memory space if it is
available in the free dynamic memory.

8-8

ALLOCATE BLOCK

$Al8LK

•

The Extend Task Routine
($EXTSK), which is called by the
$GTCOR routine to extend the size of the task region to make
enough memory available in the free dynamic memory to satisfy
the allocation request.

•

The Write Page Routine ($WRPAG), which is called by the $GTCOR
routine to transfer memory pages to the user's disk work file
to free enough memory space to satisfy the memory allocation
requc3st.

•

The Release Core Block Routine ($RLCB) , which is called by the
$GTCOR routine to release space previously allocated to a
memory page that has been transferred to the disk work file.

The processing performed by the core allocation routines is
in the following sections.

8.3.1

described

Allocate Block Routine ($ALBLK)

The $ALBLK routine determines whether a block of memory storage can be
allocated from the free dynamic memory. If ~o, the $ALBLK routine
clears (zeroes) the allocated block and returns the resident memory
address of the block to the calling task.
If there is insufficient
space in the free dynamic memory,
the requested block cannot be
allocated.
In this case, the $ALBLK routine sets the error/severity
code E$R4,S$V2 in Register 1, the address of the argument block $FRHD
(free memory header)
in Register 2, and calls the user's $ERMSG
routine (see Section 8.1.1).
To use the $ALBLK routine:
•

Input, in Register 1, the size (number of bytes less than or
equal to 512(10)) of the memory storage block to be allocated.

•

Include the statement
CALL $ALBLK
in the source program.

If allocation is successful, the output from the $ALBLK routine is
RO = the dynamic memory address of the allocated, cleared, block
and control returns to the caller.
user•s $ERMSG routine is called.

If allocation is unsuccessful, the

The interaction of the $ALBLK routine with the user's task and other
virtual memory management routines is diagrammed in Figure 8-2 and
described briefly below.

8-9

$ALBLK

ALLOCATE BLOCK

Caller

Task
$1NIVM routine
$CVRL routine
$ALVRT mutine

Call $GTCOR to
request memory
block

$ROCB

)

$EXTSK

)

$GTCOR

$WRPAG )

Clear block;
yes
set block address -----<
in RO; return

$RLCB

)

Call user's
$ERMSG routine

$ER MSG

Figure 8-2

General Block Diagram of the $ALBLK Routine

In addition to the user's task, the $ALBLK routine is
following virtual memory management routines:

called

the

•

Initialize Virtual Memory Routine ($INIVM), which calls $ALBLK
to allocate initial blocks of dynamic memory to enable page
swapping between disk and memory storage.

•

Convert Virtual to Real Address Routine ($CVRL), which calls
$ALBLK to allocate a block of dynamic memory for a virtual
page block.

•

Allocate Virtual Memory Routine ($ALVRT), which calls $ALBLK
to allocate a memory page block for a virtual page block that
is to be swapped from memory to disk storage.

The $ALBLK routine always calls the Get Core Routine
allocate the requested memory block, as follows:

8-10

($GTCOR)

$ALBLK
GET CORE $GTCOR

ALLOCATE BLOCK

•

RequE:!St allocation from the free dynamic memory.

•

If the request is not met, attempt to extend the
to increase the size of the free dynamic memory.

•

If the task cannot be extended, swap unlocked pages from
memory
storage to disk to deallocate memory space for
reallocation.

task

region

Get C<>re Routine ($GTCOR)

8.3 .. 2

The $GTCOR routine attempts
blocks in three ways:

allocate

requested

available

space

dynamic

memory

•

Allocation from the currently
dynamic memory.

the

free

•

Extension of the task region to increase the size of the
dynamic memory to accommodate the allocation request.

free

•

Swapping unlocked page blocks from dynamic memory to disk
free previously allocated memory space for reallocation.

To call the $GTCOR routine:
•

Input, in Register 1, the size (number of bytes less than or
equal to 512(10)) of the dynamic memory block to be allocated.

•

Include the statement
CALL $GTCOR
in the source program.

NOTE:
If the statistical module (GTCOS) is to be specified at task
build time,
the source program must define and initialize the $FRSIZ
field for use by the $GTCOR routine.
(See Section 8.1.2).
The outputs from the $GTCOR routine are:
•

RO = the memory
allocated.

•

Condition Code:

address

the

dynamic

memory

c bit

clear if the allocation was successful.

c bit

set if the allocation failed.

block,

The interaction of the $GTCOR routine with other system library and
virtual memory management routines is diagrammed in Figure 8-3 and
described briefly below.
The $GTCOR routine is always called by the Allocate Block Routine
($A1:..BLK).
~rhe
$GTCOR routine calls the $SAVRG routine to save and
subsequently restore registers 3 - 5 of the caller.

8-11

$GTCOR

GET CORE

$SAVRG

Task
}
$ALBLK

Caller

$GTCOR

$SAVRG

Clear C bit;
set memory
address in RO;
return

Call $RdCB
to request
memory block

$RQCB

yes

See if task can
be extended

Inhibit further
extensions

Check for
]
unlocked pages

Call $WRPAG
to write pages
out to disk

yes

Delete pages
from list; link
remaining pages;
call $RLCB to
release page
blocks

Figure 8-3

$EXTSK

)

Set C bit; return

$WRPAG

Call $EXTSK
to extend task

Update free
memory; update
top of memory;
call $RLCB to
release block

$RLCB

General Block Diagram of the $GTCOR Routine

The system library Request Core Block Routine ($RQCB}, described in
Chapter 7, is called to determine whether enough free dynamic memory
space is currently available to satisfy the allocation request.
If
so, the $GTCOR routine returns the memory address of the resident
bl9ck to the caller.
If the requested block cannot be allocated from the current free
dynamic memory, the $GTCOR routine! calls the Extend Task Rouitine
($EXTSK} to determine whether the task region can be extended to make
available the requested space in the free dynamic memory. If so, the
$GTCOR routine returns the memory address to the caller.

8-12

GETCORE
EXTEND TASK

$GTCOR
$EXTSK

If the task region cannot be extended, the $GTCOR routine searches for
unlocked pages currently resident in memory.
If any unlocked pages
are found, the "least recently used" (LRU) page is released, and its
memory space is allocated to the new page.
When an LRU page is found, the $GTCOR routine checks the page to see
if it has been written into.
If so, the Write Page Routine ($WRPAG)
is called to write the page to the disk work file.
The system library
Release Core Block Routine ($RLCB), described in Chapter 7, is called
to release the page and the Request Core Block Routine
($RQCB)
is
called to allocate the page. The memory address of the allocated page
is returned in RO to the caller.
If the $GTCOR routine is not able to
obtain sufficient memory for
the requested block, the C bit in the
Condition Code is set and control is returned to the caller.

8. 3. 3

Exten1d Task Routine ( $EXTSK)

The $EXTSK routine extends the current region of the task to increase
the amount of available memory for allocation. The task region is
extended by the specified size rounded to the next 32-word boundary.
To call the $EXTSK routine:
•

Input, in Register 1, the size (number of bytes less than or
equal to 512(10)) of the memory storage block to be allocated.

•

Include the statement
CALL $EXTSK
in the source program.

All registers of the caller are preserved except
output from the $EXTSK routine, as follows:
•

= actual extension size

(requested

Rl,

size

which
rounded

contains
to

32-word boundary) •
•

Condition Code:

c bit

clear if extension was successful.

c bit

set if extension failed.

The interaction of the $EXTSK routine with the $GTCOR routine is shown
in Figure 8-4 and described below.
The $EXTSK routine is called by the Get Core Routine
($GTCOR)
when
there is insufficient space in the current free dynamic memory to
satisfy a memory block allocation request. The $EXTSK routine rounds
the requested extension size to the next 32-word boundary.
If there
is enough memory space available, the task region is extended and the
total amount of the extension is returned, in Register 1, to the
$GTCOR routine.
If the task region cannot be extended,
the $EXTSK
routine sets the C bit in the Condition Code and returns to the $GTCOR
routine.
The $EXTSK routine may be called directly by the user. The routine is
called by the Initialize Dynamic Memory Routine ($INIDM), described in
Chapter 7.

8-13

$EXTSK
$WRPAG

EXTEND TASK
WRITE PAGE

Task
}
$GTCOR

Caller

$EXTSK

Round
extension to
32-word
boundary

yes

Convert to
32-word blocks;
set extension size i------.
in R 1; return
to caller

Set c bit;
return to caller

Figure 8-4

General Block Diagram of the $EXTSK Routine

Write Page Routine ($WRPAG)

8.3.4

The $WRPAG routine effects the transfer of a memory page to
work file.

the

disk

the

page

To call the $WRPAG routine:
•

Input, in Register 2, the dynamic memory address of
to be transferred.

•

Include the statement
CALL $WRPAG
in the source program.

The output from the $WRPAG routine is the transferred page, with
successful transfer indicated by a cleared C bit in the Condition Code
when control returns to the caller.
If the page transfer is
unsuccessful,
the
$WRPAG routine sets the error/severity code
E$R73,S$V2 in Register 1, and calls the user's $ERMSG routine
(see
Section 8 .1.1).
The interaction of the $WRPAG routine with the $GTCOR routine is shown
in Figure 8-5 and described below.
The $WRPAG routine is called by the Get Core Routine ($GTCOR)
when a
resident memory page that has been written into is to be transferred
to the user's disk work file.

8-14

WRITE PAGE

The $:wRPAG routine calls the $SAVVR routine to save and
restore the caller's registers 0 - 2. The routine then:
disk

work

file

address

the

$WRPAG

subsequently

•

Sets up the
transferred.

page

•

Initiates the page writing operation.

•

Checks the status of the write operation.

•

Indicates a successful transfer
(clears the C bit in the
Condit.ion Code) and returns control to the $SAVVR routine, or
calls the user's $ERMSG routine if a fatal work file I/O error
prevented the page transfer.

Cc_a. .

;~·~COR }

11-er_ _ .....- - - - - - - - - - - - - - - - - - - .

$WRPAG

$SAVVR

Set up disk
address for
page to be
transferred

Initiate page
writing
operation

ick status
write
eration

yes

I user's
RMSG
[ ]utine

Figure 8-5

Clear C bit;
return

$SAVVR

$ER MSG

General Block Diagram of the $WRPAG Routine

8-15

$AlVRT ALLOCATE VIRTUAL MEMORY
8.4

VIRTUAL MEMORY ALLOCATION ROUTINES

The virtual memory allocation routines manage the allocation of disk
and memory storage to enable page swapping from the free dynamic
memory to the user's disk work file. There are three virtual memory
allocation routines:
•

The Allocate Virtual Memory Routine ($ALVRT), which allocates
disk and memory page blocks, maintains page control and
address tables, and interfaces the executing task and the core
allocation and page management routines.

•

The Allocate Small Virtual Block Routine
($ALSVB), which
allocates small page blocks of disk and memory storage within
large page blocks to enable efficient usage of storage.
The
$ALSVB routine interfaces with the $ALVRT routine and page
management routines to ensure address and status control of
small pages in memory and disk storage.

•

The Request Virtual Core Block Routine ($RQVCB), which manages
page block allocation on the user's disk work file when it is
called by the $ALVRT routine.

The processing performed by the virtual memory allocation routines
described in the following sections.

8.4.l

Allocate Virtual Memory Routine ($ALVRT)

The $ALVRT routine determines whether a page block of virtual storage
can be allocated on the user's disk work file.
If so, the $ALVRT
routine ensures that an equal amount of memory storage is allocated,
updates page control and address tables, and returns the disk and
memory addresses of the allocated page blocks to the caller.
If the
$ALVRT
routine
cannot
allocate
the
requested
storage, the
error/severity code E$R76,S$V2 is stored in Register 1 and the user's
$ERMSG routine (see Section 8.1.1) is called.
To call the $ALVRT routine:
•

Input, in Register 1, the size (number of bytes less than or
equal to 512(10)) of the disk storage block to be allocated.

•

Include the statement
CALL $ALVRT
in the source program.

NOTE:

The maximum size of a page block is 512(10) bytes.

If allocation is successful, the $ALVRT routine returns the outputs:
e

memory address of allocated page block.

disk address of allocated page block.

The $ALVRT routine calls the $SAVRG routine to save and subsequently
restore registers 3 - 5 of the caller. Register 2 is destroyed.
The interaction of the $ALVRT routine with the user's task and other
virtual memory management routines is shown in Figure 8-6 and
described below.

8-16

ALLOCATE VIRTUAL MEMORY

In addition to the user's task, the $ALVRT routine is
Allocate Small Virtual Block Routine ($ALSVB).

$AlVRT

called

the

The $ALVRT routine calls the Request Virtual Core Block Routine
($RQVCB)
to determine whether the requested storage can be allocated
on the disk work file. If not, a fatal error is signalled and the
$ALVRT routine calls the user's $ERMSG routine.

Task
}
$ALSVB .

~Caller

---

~AVRG

Set memory
address of page
in RO; set disk
addre:;s of page
in A 1; transfer to
$SAVRG to
restore R3 - R5

$ALVRT

)

Call $SAVRG
to save
R3- R5

$SAVRG

Call $RQVCB
to request disk
storage block

$ROVCB

Call user's
$ERMSG
routine

$ERMSG

Call $ALBLK
to allocate
core page block

$ALBLK

Save disk page
address; see if
core page block
available

Update
paging/address
tables

Call $WRMPG
to flag page as
written into

Call $CVRL to
convert virtual
address to real
address

$CVRL

Figure 8-6

General Block Diagram of the $ALVRT Routine

8-17

$ALVRT
$ALSV8

ALLOCATE VIRTUAL MEMORY
ALLOCATE SMALL VIRTUAL BLOCK

If the disk storage can be allocated, the $RQVCB routine returns the
disk page block address to the $ALVRT routine, which determines
whether a page block of space is available in memory.
If not, the
Allocate Block Routine
($ALBLK) is called to allocate a page block.
The $ALVRT routine then calls the Convert Virtual to Real Address
Routine ($CVRL) to convert the virtual address to a memory address.
The $ALVRT routine calls the Write-marked Page Routine ($WRMPG) to set
the "written into" flag of the memory page.

8.4.2

Allocate Small Virtual Block :Routine ($ALSVB)

The $ALSVB routine allocates small page blocks within large page
blocks of disk and memory storage. Thus, the routine accommodates
variable user allocation size requirements and minimizes wasted
storage space.
The $ALSVB routine initially allocates a large page block, then
performs sub-allocation of requested small blocks within the large
block. When the space within a large block is exhausted, a new large
block is allocated by the $ALSVB routine.
To call the $ALSVB routine:
•

Define the following in the source program:
N$DLGH .WORD 512.

•

Normally, this is the size of a large memory block.
case, it must be less than or equal to 512(10).

any

Specify, in Register 1, the size
allocated, where:

the

page

block

zero (0) to force the allocation of a large virtual
block on the first call to $ALSVB.

page

Rl = a value less than or equal to 512
(10)
specifying
size, in bytes, of the small page to be allocated.

the

NOTE: the maximum size of a page block is 512(10) bytes.
•

Include the statement
CALL $ALSVB
in the source program.

The outputs from the $ALSVB routine are:
•

RO = the dynamic memory address of the allocated page block.

the virtual address of the allocated block.

Registers 3 - 5 are preserved.

The interaction of the $ALSVB routine with other virtual memory
management routines is diagrammed in Figure 8-7, and described briefly
below.

8-18

ALLOCATE SMALL VIRTUAL BLOCK

$ALSV8

.__T_•:Y--·--------------.

Round requested
block size to
word boundary;
check to see if
this is first call

yes

~:~r:~st~~I
[

Call $ALVIH to
allocate large
disk page block

$ALVRT

Return memory
address in RO;
virtual address
in R1

available small
block

~~
Call $CV Fl L to
convert virtual
address to memory 1----.---....
address and read
[
into page

:J____,

(

Call $WRMPG
to mark page as
written into

$WR MPG

$CVRL

Figure 8-7

General Block Diagram of the $ALSVB Routine

When a small page block is to be allocated within an existing large
page block, the $ALSVB routine calls the Convert Virtual to Real
Address Routine ($CVRL) to perform the following:

8-19

$ALSV8
$RQVC8

ALLOCATE SMALL VIRTUAL BLOCK
REQUEST VIRTUAL CORE BLOCK

•

Locate the allocated large page, if it is memory resident.
not resident, read the page from disk to memory.

•

Convert the virtual page

•

Transfer the large page block from disk into the large
page block.

addrc~ss

to a memory page address.
memory

The $ALSVB routine calls the Write-mairked Page Routine ($WRMPG) to set
the "written into" flag of the allocated memory page.
When a large page block is to be allocated,
Memory Routine ($ALVRT) is called to effect:

the

Allocate

Virtual

•

Disk and dynamic memory allocation of the requested large page
block.

•

Virtual address conversion to a memory address.

•

Transfer of the
dynamic memory.

•

Setting the "written into" flag of the allocated page block.

large

block,

necessary,

from

disk

Request Virtual Core Block Routine ($RQVCB)

8.4.3

The $RQVCB routine manages page block allocation on the user's disk
work file.
The $RQVCB routine is called by the Allocate Virtual
Memory Routine ($ALVRT) when a user's task has requested allocation of
a page block of a maximum of 512 (10) bytes in length.
The interaction of the $RQVCB routin1~ with the $ALVRT
diagrammed in Figure 8-8 and described briefly below.

routine

The $RQVCB routine rounds the request1~d number of bytes up to the
nearest word. If the rounded value cirosses a disk block boundary, the
$RQVCB routine allocates the page block beginning at the next disk
block.
If allocation is successful, the $RQVCB routine clears the C bit in
the Condition Code and returns the d:isk address of the allocated page
to the $ALVRT routine.
If allocation is not successful, the $RQVCB routine sets the C bit in
the Condition Code and returns control to the $ALVRT routine. Two
conditions cause allocation failure:
•

There is no more disk storage space available.

•

A page block
requested.

size

greater

8-20

than

512

(10)

bytes

has

been

REQUEST VIRTUAL CORE BLOCK

$RQVC8

Task

$ALVRT

$RQVCB

Check available
disk storage

Set C bit;
return to caller

Clear C bit;
round request;
check size

Put disk page
address in R 1;
clear C bit;
return

Allocate page
space within
disk block
boundary

Figure 8-8

8.5

General Block Diagram of the $RQVCB Routine

PAGE MANAGEMENT ROUTINES

The page management routines perform the processing required to
control page swapping between dynamic memory and disk file storage.
Required processing includes address conversion, page location, page
transfer from disk to memory, and page status handling, such as
time-stamping, flagging as "written into", and locking and unlocking
memory pages. The page management routines are:

8-21

$CVLQK CONVERT AND LOCK PAGE
•

The Convert and Lock Page Routine ($CVLOK), which converts a
virtual address to a dynamic memory address and locks the page
in memory when called by the user's task.

•

The Convert Virtual to Real Address Routine
($CVRL), which
converts a virtual address to a dynamic memory address when
called by:
•

the user task.

•

the Allocate Virtual Memory Routine ($ALVRT) when
disk page has been allocated.

•

the Convert and Lock Page Routine ($CVLOK), when a page
address is to be converted and the page is to be locked
in memory.

new

•

The Read Page Routine ($RDPAG)i, which is called by the $CVRL
routine to transfe~ a page from the user's disk work file to
dynamic memory.

•

The Find Page ($FNDPG), which determines whether
page is resident in d¥namic memory when called by:
•

the $CVRL routine.

•

the Lock Page Routine ($LCKPG).

•

the Unlock Page Routine {$UNLPG) .

•

the Write-marked Page Routine ($WRMPG).

virtual

•

The Write-marked Page Routine
($WRMPG), which sets
the
"written into" flag of memory pages when called by the user or
by the $ALVRT and $ALSVB virtual memory allocation routines.

•

The Lock Page Routine ($LCKPG;1, which is called by the $CVLOK
routine and the user's task to set a lock byte in a memory
page to prevent its being swapped from memory to the disk
file.

•

The Unlock Page Routine
($UNLPG), which is called by the
user's task to clear a lock byte in a memory page to allow it
to be swapped to disk storage to free memory space for
reallocation.

The processing performed by the page management routines is
in the following sections.

Convert and Lock Page Routine ($CVLOK)

8.5.1

The $CVLOK routine performs two functions:
•

Converts a virtual address to a memory address.

•

Locks the page in memory.

8-22

described

CONVERT AND LOCK PAGE

$CVLQK

To ca.11 the $CVLOK .routine:
•

Specify, in Register 1, the virtual address to be converted.

•

Include the statement
CALL $CVLOK
in the source program.

Outputs from the $CVLOK routine are:
•

RO - converted memory address.

•

Condition Code:

virtual address.

C bit = clear if
locked.
C bit

the

address

was

converted

and

the

page

= set if address conversion or page locking failed.

The contents of R2 are preserved.
the $CVRL routine.

Registers 3 - 5

are

preserved

The interaction of the $CVLOK routine with the calling task and
page management routines is shown in Figure 8-9.

other

The $CVLOK routine calls:
•

The Convert Virtual to Real Address Routine ($CVRL) to convert
the virtual address to a memory address.

•

The Lock Page Routine ($LCKPG) to lock the page in memory.

8-23

$CVLQK CONVERT AND LOCK PAGE
$CVRl CONVERT VIRTUAL TO REAL ADDRESS

Task

$CV LOK

Call $CVRL to
convert virtual
to memory
address

Call $LCKPG
to lock page
in core

--(

$LCKPG

Set C bit;
return

)

Clear C bit; set
RO= memory
address; set
R1 =virtual
address; return

Figure 8-9

8. 5. 2

General Block Diagram of the $CVLOK Routine

Convert Virtual to Real AddrE!SS Routine ($CVRL)

The $CVRL routine converts a
address.

virtual

address

To call the $CVRL routine:
•

Input, in Register 1, the virtual address.

•

Include the statement
CALL $CVRL
in the source program.

The output from the $CVRL routine is:
RO = memory address.

8-24

dynamic

memory

CONVERT VIRTUAL TO REAL ADDRESS

The $SAVRG routine is called to save and restore registers
Register 1 is unchanged. Register 2 is destroyed.

$CVRL
3

The interaction of the $CVRL routine with the caller and other virtual
memory management routines is shown in Figure 8-10 and described
br ief:ly below.
The $CVRL routine may be called by the user's task, and the
routines:

following

•

Allocate Virtual Memory Routine ($ALVRT), when a new disk page
has been allocated.

•

Conver·t and Lock Page Routine
($CVLOK), when the executing
task has specified that a virtual address is to be converted
to a memory address and the page is to be locked in memory.

The $CVRL routine calls the Find Page Routine
($FNDPG)
to determine
whether the specified page is resident in memory. If so, the virtual
address is converted to a memory address, which is returned to the
caller. If the page is not in memory, the Allocate Block
Routine ($ALBLK) is called to allocate a memory page block. The $CVRL
routine then calls the Read Page Routine ($RDPAG) to transfer the disk
page into dynamic memory. The page address is then converted to a
memory address. The memory address of the specified word in the page
is stored in RO, and control is transferred to the $SAVRG routine,
which restores registers 3 - 5 and returns to the caller.

Caller

Task
$ALVRT
{
$CV LOK

$CVRL

$SAVRG

Call $FNDPG
to find page

$FNDPG

$ALBLK

Call $RDPAG
to read disk
page into
memory page

Convert address;
set RO = memory
address; return

Figure 8-10

Call $ALBLK
to allocate
memory page
block

General Block Diagram of the $CVRL Routine
8-25

$RDPAG

READPAGE

Read Page Routine ($RDPAG)

8.5.3

The $RDPAG routine effects the transfer of a disk page from
file to the dynamic memory.

the

work

To call the $RDPAG routine:
•

Input, in Register 0, the disk
transferred.

•

Include the statement

address

the

page

CALL $RDPAG
in the source program.
The output from the $RDPAG routine is the transferred page, indicated
by a cleared C bit in the Condition Code when control returns to the
caller. If the page transfer is unsuccessful, the $RDPAG routine sets
the error/severity code E$R73,S$V2 in Register 1 and calls the user's
$ERMSG routine (see Section 8.1.1).
The interaction of the $RDPAG routine with the task
routine is shown in Figure 8-11 and described below.

and

the

$CVRL

The $RDPAG routine is called by the Conv~rt Virtual to Real Address
Routine
($CVRL)
when a disk page is to be transferred to dynamic
memory.
The $RDPAG routine calls the $SAVVR routine to save and
restore ~he caller's registers 0 - 2. The routine then:

subsequently

•

Sets up the address of the page to be transferred.

•

Initiates the page reading operation.

•

Checks the status of the read operation.

•

Indicates a successful transfer
(clears the C bit in the
Condition Code) and returns control to the $SAVVR routine, or
calls the user's $ERMSG routine if a fatal work file I/O error
prevented the page transfer.

8-26

READ PAGE
FIND PAGE

__,Ccaller

$RDPAG
$FNDPG

{Task
$CVRL

CRDPAG

$SAVVR

~i•t:read
erat1on

~ck

status

ead

Set c bit;
call user's
$ERMSG
routine

$ER MSG

Clear C bit;
transfer to
$SAVVR to
restore RO· R2
and return

----GAVVR
Figure 8-11

8.5.4

General Block Diagram of the $RDPAG Routine

Find Page Routine ($FNDPG)

The $FNDPG routine searches an internal page address list to determine
whether a virtual page has already been transferred into an allocated
memory page block.

8-27

$FNDPG

FIND PAGE

To call the $FNDPG routine:
•

Specify, in Register 1, the virtual page address.

•

Include the statement
CALL $FNDPG
in the source program.

The outputs from the $FNDPG routine are:
•

RO = the memory page
resident.

•

Condition Code:

block

address

which

the

page

C bit = cleared if page is resident.
C bit

set if page was not found.

The content of Register 1 is not changed.
The interaction 0£ the $FNDPG routine with the user's task and the
page management routines is shown in Figure 8-12 and described bE~low.
The $FNDPG routine
management routines:

called

the

following

virtual

memory

•

Convert Virtual to Real AddrE~ss Routine {$CVRL) when a virtual
address is to be converted to a memory address.

•

Lock Page Routine {$LCKPG) when a memory page is to be
in core memory.

locked

•

Unlock Page Routine {$UNLPG) when a lticked memory page
be unlocked.

•

Write-marked Page Routine {$WRMPG) when
flag is to be set in a memory page.

into"

the

"written

The $FNDPG routine determines whether the specified page is resident
in the task's dynamic memory. If so, the page is time-stamped, its
page block address is set in Register 0, the C bit in the Condition
Code is cleared, and control returns to the caller. If the page is
not resident in memory, the C bit in the Condition Code is set, and
control returns to the caller.

8-28

$FNDPG
WRITE-MARKED PAGE $WRMPG
FIND PAGE

Caller

;~~RL
$LCKPG
$UN LPG
$WR MPG

$FNDPG

Check page
address list to
see if page
in core

Set C bit;
return

Time-stamp
page; clear C bit;
set RO= page
address; return

Figure 8-12

General Block Diagram of the $FNDPG Routine

Write-marked Page Routine ($WRMPG)

8.5.5

The $WRMPG routine sets the "written into" flag of the specified
in dynamic memory.

page

To call the $WRMPG routine:
•

Specify, in Register 1, the virtual address in the page.

•

Include the statement
CALL $WRMPG
in the source program.

The output from the $WRMPG routine is a Condition Code setting:

c bit

cleared to indicate
successfully.

that

the

page

was

write

C bit = set to indicate that the specified memory page
resident in the task's free dynamic memory.

8-29

marked
was

not

$WRMPG WRITE-MARKED PAGE
The interaction of the $WRMPG routine with
memory management routines is shown in
below.
The $WRMPG routine
management routines:

called

the

the caller and virtual
Figure 8-13 and described
following

virtual

memory

•

Allocate Virtual Memory Routine ($ALVRT) when a disk page
been allocate~ in dynamic memory.

•

Allocate Small Virtual Block Routine
($ALSVB)
when a small
page block has been allocated within a large page block.

The $WRMPG routine calls the $SAVVR routine to save
restore registers 0 - 2 of the caller.

and

has

subsequently

The Find Page Routine ($FNDPG) is called to determine whether the
specified page is resident in the task's memory. If not, the C bit in
the Condition Code is set, and control is transferred to the $SAVVR
routine to restore registers 0 - 2 and return to the caller.
If the
page is resident in memory, its "written into" flag is set, the C bit
in the Condition Code cleared, .and control is transferred to the
$SAVVR routine to restore RO - R2 and return to the caller.

Task
$ALVRT
, $ALSVB

Caller

Call $FNDPG
to find page

$SAVVR

)

$FNDPG

)

Set C bit; return
to $SAVVR

Set write-mark
flag; clear C bit;
return to
$SAVVR

$SAVVR

Figure 8-13

General Block Diagram of the $WRMPG Routine

8-30

LOCK PAGE

8.5.6

$LCKPG

Lock Page Routine ($LCKPG)

The $LCKPG routine sets a lock byte in a memory-resident page to
prevent its being swapped from dynamic memory to the disk work file.
To call the $LCKPG routine:
•

Specify, in Register 1, a virtual address in the
locked in dynamic memory.

•

Include the statement

page

CALL $LCKPG
in the source program.
The output from the $LCKPG routine is a Condition Code setting:

c bit
c bit

cleared if the page was locked in memory.
set if the page was not found.

The interaction of
management routines
below.

the $LCKPG routine with the task and page
is shown in Figure 8-14 and described briefly

The $LCKPG routine may be called by the user's task and by the Convert
and Lock Page Routine ($CVLOK).
The $LCKPG routine calls the $SAVVR routine to save
restore the caller's registers 0 - 2.

and

subsequently

The Find Page Routine ($FNDPG) is called to determine whether the
memory page is resident.
If so, the page lock byte is set, the C bit
in the Condition Code is cleared and control is transferred to the
$SAVVR routine to restore RO - R2 and return to the caller.
If the specified page is not in memory, the C bit in the Condition
Codie is set and control is returned, via the $SAVVR routine, to the
caller.

8-31

$LCKPG
$UNLPG

LOCK PAGE
UNLOCK PAGE

Caller

$LCKPG

Task
$CV LOK

]1----11•~(

$SAVVR

)

Call $ F N D P : - i _ _
to find page

$FNDPG

$SAVVR

Set C bit; transfer
to $SAVVR to
restore RO - R2
and exit to caller

Lock it; clear
C bit; transfer
to $SAVVR to
restore RO - R2
and exit to caller

Figure 8-14

General Block Diagram of the $LCKPG Routine

Unlock Page Routine ($UNLPG)

8.5.7

The $UNLPG routine clears a lock byte in a memory-resident page to
allow the page to be swapped from dynamic memory to the disk work
file.
To call the $UNLPG routine:
•

Specify, in Register 1, the virtual address in the page to
unlocked.

•

Include the statement
CALL $UNLPG
in the source program.

8-32

UNLOCK PAGE

~he

$UNLPG

output from the $UNLPG routine is a Condition Code bit setting:

c bit

cleared if the page was unlocked.

c bit

set if the page was not found.

The interaction of the $UNLPG routine with the task is shown in Figure
8-15 and described briefly below.
The~

$UNLPG routine calls the $SAVVR routine to save
restore the caller's registers O - 2.

and

subsequently

The Find Page Routine ($FNDPG) is called to determine whether the
memory page is resident.
If so, the page lock byte and the C bit in
the Condition Code are cleared and control is transferred to the
$SA.VVR routi.ne to restore RO - R2 and return to the caller.
If the speci.fied page is not in memory, the C bit in the Condition
Code is set and control is returned, via the $SAVVR routine, to the
caller.

Task

$UN LPG

$SAVVR

Call $FNDPG
to find page

~VVR

$FNDPG

Set C bit; transfer
to $SAVVR to
restore RO - R2
and exit to caller

Unlock it; clear
C bit; transfer to
$SAVVR to
restore RO - R2
and exit to caller

Figure 8-15

General Block Diagram of the $UNLPG Routine

8-33

CHAPTER 9

SUMMARY PROCEDURES

The procedures fo~ using the system library routines a~e summarized in
tabular format in this chapter.
These summaries are presented as
quick reference guides for users who are familiar with the detailed
procedures
and
requirements for using individual routines, as
described in preceding chapters of this manual.
Table 9-1
Register Handling Routines Summary
Routi.ne NamE~/
Mnemonic

Function

Call Statement

Saves/restores RO - RS

JSR PC,$SAVAL

Saves/restores R3 - RS

JSR RS, $SAVRG

Save Registers 0 - 2
$SAWR

Saves/restores RO - R2

JSR R2,$SAWR

·saves/restores Rl - RS

JSR RS, .SAVRl

Save All Registers
$SAVAL
Save Registers 3 $SAVRG

Save Registers 1 .SAVRl

9-1

May 1979

SUMMARY PROCEDURES
Table 9-2
Arithmetic Rou tin,es Summary

Routine Name/
Mnemonic

Input Arguments and
Call Statement

Outputs

Integer Multiply
$MUL

RO = multiplier
Rl = multiplicand
CALL $MUL

Product:
RO = high order part
Rl = low order part
R2-R5 preserved

Integer Divide
$DIV

RO = dividend
Rl = divisor
CALL $DIV

RO = quotient
Rl = remainder
R2-R5 preserved

Double-precision Multiply
$DMUL

RO = rnul tiplier
Multiplicand:
R2 = high order part
R3 = low order part
CALL $DMUL

Double-precision Divide
$DDIV

RO = unsigned divisor
Dividend:
Rl = high order part
R2 = low order part

NOTE:

Product:
RO = high order part
Rl = low order part
C = clear
R4-R5 preserved
R2-R3 destroyed
RO = remainder
Quotient:
Rl = high order part
R2 = low order part
R3 preserved

The arithmetic routines accept unsigned inputs and produce unsigned results.

9-2

SUMMARY PROCEDURES
Table 9-3
Input Data Conversion Routines Summary

R0\;1tine Name/
Mne?monic

Input Arguments and Call Statement

Decimal to
Binary Doub le
WO I'd
.DD2CT

R3 == output address
R4 == number input characters
RS == input string address
CALI, .DD2CT

Successful:
Converted number at output
address:
Word 1 = high order part
Word 2 = low order part
C = clear
Unsuccessful:
c = set
All registers preserved

Octal to
Binary
Double
Word
.OD2CT

R3 == output address
R4 == number input characters
RS - input string address
CALI, .OD2CT

Successful:
Converted number at output
address:
Word 1 = high order part
Word 2 = low order part
C = clear
Unsuccessful:
C = set
All registers preserved

Decimal to
Binary
$CDTB

RO == address first input byte
CALI, $CDTB

RO = address first byte of
next string
Rl = converted number
R2 = terminating character
R3-RS preserved

Octal to
Binary
$COTB

RO = address first input byte
CALI. $COTB

RO = address first byte of
next string
Rl = converted number
R2 = terminating character
R3-RS preserved

ASCII to
Radix-SO
$CATS

RO = address first input character
Rl -· 0 (period is terminating
character)
Rl = 1 (period is valid cha:racter)
CALI, $CATS

Successful:
RO = address next input character
Rl = converted Radix-SO value
R2 = terminating character
C = clear
Unsuccessful:
R2 = illegal character
c = set
R3-RS preserved

ASCII with
Bla.nks to
Radix-SO
$C.P.1TSB

RO -· address first input character
Rl = 0 (period is terminating'
character)
Rl - 1 (period is valid character)
CALI. $CATSB

Successful:
RO = address next input character
Rl = converted Radix-SO value
R2 = terminating character
c = clear
Unsuccessful:
R2 = illegal character
c = set
R3-RS preserved

9-3

Outputs

SUMMARY PROCEDURES

Table '9-4
Output Data Conversion Routines Summary
Routine Name/
Mnemonic

Input Arguments and Call Statement

Outputs

Binary Date
Conversion
$CBDAT

RO = output address
Rl = binary date
R2 = 0 (zero suppress)
R2 = nonzero (no zero suppress)
CALL $CBDAT

Converted date at output
address
RO = next available output
address
R3-R5 preserved
Rl-R2 destroyed

Convert Binary
To Decimal
Magnitude
$CBDMG

RO = output address
Rl = binary number
R2 = 0 (zero suppress)
R2 = nonzero (no zero suppress)
CALL $CBDMG

Converted number at output
address
RO = next available output
address
R3-R5 preserved
Rl-R2 destroyed

Convert Binary
to Signed
Decimal
$CBDSG

RO = output address
Rl = binary number
R2 = 0 (zero suppress)
R2 = nonzero (no zero supp1~ess)
CALL $CBDSG

Converted number at output
address
RO = next available output
address
R3-R5 preserved
Rl-R2 destroyed

Convert DoublePrecision
Binary to
Decimal
$CDDMG

RO = output address
Rl = input address
R2 = 0 (zero suppress)
R2 = nonzero (no zero supp1::-ess)
CALL $CDDMG

Successful:
Converted number at output
address.
Unsuccessful:
String bf ASCII asterislcs at
output address
RO = next available output
address
R3-R5 preserved
Rl-R2 destroyed

Convert Binary
to Octal
Magnitude
$CBOMG

RO = output address
Rl = binary number
R2 = 0 (zero suppress)
R2 = nonzero (no zero suppicess)
CALL $CBOMG

Converted number at output
address
RO = next available output
address
R3-R5 preserved
Rl-R2 destroyed

Convert Binary
to Signed
Octal
$CBOSG

RO = output address
Rl = binary number
R2 = 0 (zero suppress)
R2 = nonzero (no zero suppicess)
CALL $CBOSG

Converted number at output
address
RO = next available output
address
R3-R5 preserved
Rl-R2 destroyed

Convert Binary
Byte to Octal
Magnitude
$CBTMG

RO = output address
Rl = binary byte
R2 = 0 (zero suppress)
R2 = nonzero (no zero supp:ress)
CALL $CBTMG

Converted byte at output
address
RO = next available output
address
R3-R5 preserved
Rl-R2 destroyed

(continued on next page)

9-·4

SUMMARY PROCEDURES
Table 9-4 (Cont.)
Output Data Conversion Routines Summary
Routine Name/
Mnemonic

Input Arguments and Call Statement

General Purpo se
Binary to
ASCII
$C:BTA

RO = output address
Rl = binary value
R2 = conversion parameters:
bits 0-7: radix (2 •. -10.)
bit 8:
bit 9:
bit 10:

= 0 = unsigned value
= 1 - signed value

Outputs
Converted number at output
address
RO = next available output
address
R3-R5 preserved
Rl-R2 destroyed

= 0 = ze:t·o suppress
= 1 = no zero suppress
= 1, replace leading
zeroes with blanks.

= o, do not replace
leading zeroes with
blanks.
bits 11-15: field width (value
1-32)
CALL $CBTA
Radix-SO to
ASCII
$C!5TA

RO = output address
Rl = Radix-SO word
CALL $CSTA

Converted number at output
address
RO = next available output
address
R3-RS not used
Rl-R2 destroyed

Table 9-5
Output Formatting Routines Summary
Routine Name/
Mnemonic

Input Arguments and Call Statement

Outputs

Upper Case
Text
$CVTUC

RO = input address
Rl = output address
R2 = number input bytes
CALL $CVTUC

Converted text at output
address
R3-R5 not used
R2 destroyed
RO-Rl not altered

Date String
Conversion
$0.1\.T

RO = output address
Rl = input address
CALL $DAT

Converted date string at
output address
RO = next available output
address
Rl = address of next input
word
R3-R5 preserved
R2 destroyed

Time Conve:rsion
$TIM

RO = output address
Rl = input address
R2 = parameter count:
= O or 1, hour (HH)
= 2, hour:minute (HH:MM)
= 3, hour:minute:second
(HH:MM:SS)
= 4 or S, hour:minute:second.
tenth of second (HH:MM:SS.S)
CALL $TIM

Converted time string at
output address
RO = next available output
address
Rl = address of next input
word
R3-R5 preserved
RO-Rl updated
R2 destroyed

(continued on next page)

9--5

SUMMARY PROCEDURES

Table 9-5 (Cont.)
Output Formatting Routines Summary
Routine Name/
Mnemonic

Input Arguments and Call Statiement

Edit Message
$EDMSG

Define ASCIZ input string with
directives in the form:
%1

%nl
%Vl
where n = optional decimal repeat
count; V specifies an optional value
to be used as a repeat count; and
1 = one of the following:
A = ASCII string ~ransfer
B = Binary byte to octal conversion

... Binary to signed decimal conversion

E = Extended ASCII string transfer
F = Form control insertion
M = Binary to decimal magnitude

conversion, zero suppression
New line insertion
0 = Binary to signed octal conversion
p = Binary to octal magnitude conversion
R = Radix-50 to ASCII conversion
s = Space insertion
T = Double-precision binary to
decimal conversion
u = Binary to double-precisic1n
decimal conversion, no zeiro
suppression
X = File name conversion
Y = Date conversion
z = Time conversion
< = Define fixed length byte field
> = Locate field mark

N =

Set up argument and output block
RO = output address
Rl = input string address
R2 = argument block address
CALL $EDMSG

9-6

outputs
Converted/formatted data in
output block
RO = address of last byte
in output block
Rl = number of bytes in
output block
R2 = address of next argument in argument bl1ock
R3-R5 preserved

SUMMARY PROCEDURES
Table 9-6
Dynamic Memory Management Routines Summary
Routine Name/
Mnemonic

Input Arguments and Call Statement

Outputs

Initialize
Dynamic
MEmlOry
$l:NIDM

Include FREEHD: .BLKW 2 in data
section
RO = free memory listhead address
CALL $INIDM

RO = task's first address
Rl • free pool first address
R2 = size memory pool
R3-R5 not used

REiquest Core
Block
$RQCB

RO = free memory listhead address
Rl = byte size of block

CALL $RQCB

Successful:
RO • block memory address
Rl = actual size of block
C = clear
Unsuccessful:
C = set
R3-RS preserved
R2 destroyed

Reilease Co:re
Block
$FtLCB

RO = free memory listhead address
Rl = byte size .of block
R2 = block memory address

9-7

Released block
R3-R5 preserved
RO unch,anged
Rl-R2 destroyed

SUMMARY PROCJE:DURES

Table 9-7
Virtual Memory Management Routines Summary
Routine Name/
Mnemonic

Input Arguments and Call Statemient

Outputs

Initialize
Virtual
Memory
$INIVM

Define $FRHD block with first
address of free memory
Define 3 global symbols: W$KLUN
(work file LUN); W$KEXT (work
file extension size); N$MPAG
(fast page search page count)
RO • free memory highest addrE~ss
CALL $INIVM

Allocate
Block
$ALBLK

Rl = byte size of requested block
CALL $ALBLK

Successful:
RO = block memory address
Unsuccessful:
User's $ERMSG routine is called
R3-R5 preserved
RO-R2 destroyed

Get Core
$GTCOR

Rl = byte size of requested block
CALL $GTCOR

Successful:
RO = block memory address
c = clear
Unsuccessful:
C = set
R3-R5 preserved

Extend
Task
$EXTSK

Rl = byte size of requested block
CALL $EXTSK

Successful:
Rl = actual extension size
c = clear
Failure:
c = set
R2-R5 preserved

Write
Page
$WRPAG

R2 = memory address of page
CALL $WRPAG

Successful:
C = clear
Unsuccessful:
User's $ERMSG routine is called
RO-R2 preserved

Allocate
Virtual
Memory
$ALVRT

Rl = byte size of requested block
CALL $ALVRT

Successful:
RO = allocated block memory
address
Rl = allocated block disk
address
Unsuccessful:
User's $ERMSG routine is called
R3-R5 preserved
R2 destroyed

Allocate
Small
Virtual
Block
$ALSVB

Define N$DLGH .WORD 512.
Rl = size of requested page block:
= O, for large block allocation
on first call to $ALSVB
= a value less than or equal to
512 (10) bytes for small page
allocation
CALL $ALSVB

RO = block memory address
Rl = block virtual address
R3-R5 preserved
R2 destroyed

Successful:

c = clear and RO = 0
Failure:

c •set and

RO = -2, file not opened
RO = -1, file not marked
R3-R5 preserved
Original content R0-R2
destroyed

(continued on next page)

9-8

SUMMARY PROCEDURES

Table 9-7 (Cont.)
Virtual Memory Mana9ement Routines Summary
Roiutine Name/
Mnemonic

Input Arguments and Call Statement

Outputs

Ccinvert and
Leick Page
$C:VLOK

Rl = virtual address
CAT..L $CVLOK

Successful:
RO = memory address
Rl = virtual address
c = clear
Unsuccessful:
c = set
R2-R5 preserved

Convert Virtual
to Real Address
$C:VRL

Rl = virtual address
CALL $CVRL

RO = memory address
R3-R5 preserved
Rl unchanged
R2 destroyed

REiad Page
$FtDPAG

RO = page disk address
CALL $RDPAG

Successful:
C = clear
Unsuccessful:
User's $ERMSG routine is called
RO-R2 preserved

Find Page
$E"NDPG

Rl = page virtual address
CALL $FNDPG

Page found:
RO = block memory address
C = clear
Page not found:
c = set

WJ:i te-marked
Page
$WRMPG

Rl = virtual address in page
CALL $WRMPG

c = clear, page write-marked
c = set, page not found

Lock Page
$l~CKPG

Rl = virtual address in page
CALL $LCKPG

C = clear, page locked
c = set, page not found
RO-R2 preserved

Unlock Page
$1JNLPG

Rl = virtual address in page
CALL $UNLPG

c = clear, page unlocked
c = set, page not found

RO-R2 preserved

R0-R2 preserved

9-9

APPENDIX A
SYSTEM REFERENCE BIBLIOGRAPHY

This bibliography identifies manuals that contain descriptions of
additional routines available to users of the IAS/RSX-11 system
libraries.
First level entries are manual titles.
Second level entries are
functional headings indicating the types of services described in the
respective manual.
!AS

l~XBCUTIVE

REFERENCE MANUAL (VOLUMES I AND I I)

Task Execution Control Directives
Informational Directives
Event-associated Directives
Trap-associated Directives
I/0 Related Directives
Task Status Control Directives
IAS/RSX-llD DEVICE HANDLERS REFERENCE MANUAL
Laboratory and Industrial I/O Routines
IAS/RSX-11 I/O OPERATIONS REFERENCE MANUAL
I/O Preparation Services
File Processing Services
File Control Routines
File Structuring Services
Command-line Processing Services
Parsing Services
Spooling Services
RSX-llD EXECUTIVE REFERENCE MANUAL
Task Execution Control Directives
Informational Directives
Event-associated Directives
Trap-associated Directives
I/O Related Directives
Task Status Control Directives

A-1

SYSTEM REFERENCE BJCBLIOGRAPBY

RSX-llM EXECUTIVE REFERENCE MANUAL
Task Execution Control
Task Status Control
Event-associated Services
Trap-associated Services
I/O and Intertask Communication
Memory Management Services
RSX-llM I/O DRIVERS REFERENCE MANUAL
Laboratory and Industrial I/O Routines

A-2

APPENDIX B

UNIVERSAL LIBRARY ACCESS

On most RSX-llM systems, the user can create a universal library to
stoI'e files of a similar type. The LBR utility creates the universal
libI"ary file with a file type .ULB. By means of the LBR utility,
the
useI' can subsequently insert files as modules in the library.l
To access a module of a universal library, a program can call the $ULA
routine, which establishes the necessary conditions for access (read
only). The $ULA routine first calls an initializing routine,
$ULAIN,
to validate that the library file is in the correct format and to
obtain the needed information from the library header.
$ULA then
calls a second routine, $ULAFD, to read the module header, to position
libary file pointers to the beginning of the module, and to establish
the necessary FDB locations for the File Control System (FCS) .2 Once
the necessary FDB locations are established, the program can access
the module as if it were a separate file.
That is, the program can
perform GET$ operations in move mode for each record in the module.
To call the $ULA routine, supply the following data.
•

In RO, the address of the universal library FDB.
file must already be open for read access.

The

library

•

In Rl, the address of a 42-word buffer containing the name (in
Radix-50 format)
of the module to be accessed followed by 40
words that will contain a copy of the module header when $ULA
returns control to the user program.

The $ULA routine outputs the following data:
•

RO is unchanged.

•

Rl is unchanged. The $ULA routine fills in the 40-word buffer
with a copy of the header for the module accessed.

•

The first five words of the library file FDB contain the first
five words of the FDB of the module's associated input file
(as if it were a separate input file).

•

The offset F.EFBK+2 of the library file FDB contains the
block number of the module.

last

1 For more information on universal libraries,
refer
to
the
description of the LBR utility in Chapter 14 of the RSX-11 Utilities
Maqual.
2 See the !AS/RSX-11 I/O Operations Reference Manual for
on FCS and use of FDB locations.

B-1

information

May 1979

UNIVERSAL LIBRARY ACCESS
•

The offset F.FFBY of the library file FOB contains the
of the next available byte past the end of the module.

•

The offset F.ERR of the library file FOB has the standard
interpretations except for the following special meanings.

•

The symbol IE.BHD means either FILE
LIBRARY or BAD LIBRARY HEADER.

NOT

The symbol IE.NSF means NO SUCH MODULE.

number

UNIVERSAL

The C bit set indicates an error.

To properly use the $ULA routine, follow the coding sequence below.

OPEN$

:OPEN UNIV LIB FILE

store first seven words of library FOB

CALL

$ULA

GET$

:access module in move mode only

restore first seven words of library FOB

CLOSE$ RO or invoke $ULA again
Note that the program must open the library file for read-only access.
(To change a module in the universal library, use the LBR utility.)
The program must save the first seven words of the library file FOB
before calling the $ULA routine for the first time. The $ULA routine
modifies these words during processing but their original values are
necessary either to access another module or to ensure that the
library file is properly closed. The program must restore the seven
words after accessing a module and before accessing another module or
before closing the library file.

B-2

May 1979

UPDATE NOTICE NO.l
IAS/RSX-11 System Library Routines Reference Manual
AD-5580A-Tl
May 1979
Insert this Update Notice page in the manual as a means of maintaining
an up-to-date record of changes to the manual.
NEW AND CHANGED INFORMATION
This update reflects software changes and additions made in RSX-llM
Version 3.2.
Copyright

@ 1979 Digital. Equipment Corporation

INSTRUCTIONS
Place the following pages in the IAS/RSX-11 System
Library Routines Reference Manual as replacements
for, or additions to, current pages. The changes
made on replacement pages are indicated in the
outside margin by change bars (I ) for additions,
and bullets ( •) for deletions.
Old Page

New Page

Title Page/Copyright Page
iii/iv
v/blank
vii/viii
1-1/1-2
1-3/blank
2-1/2-2 through 2-5/2-6
6-1/6-2
6-3/6-4

Title Page/Copyright Page
iii/iv
v/blank
vii/viii
1-1/1-2
1-3/blank
2-1/2-2 through 2-5/2-6
6-1/6-2
6-3/6-4
6-4. 1/ blank
6-5/6-6 through 6-11/6-12
7-1/7-2
8-5/8-6
9-1/9-2
B-1/B-2
Reader's Comments

6-5/6-6 through 6-11/6-12
7-1/7-2
8-5/8-6
9-1/9-2
Reader's Comments

Additional copies of this update to the IAS/RSX-11 System
Library Routines Reference Manual may be ordered from the
Software Distribution Center, Di~ital Equipment Corporation,
[ Maynard, Massachusetts 01754. Order Code: AD-5580A-Tl. The
order code of the base manual is AA-5580A-TC.

IAS/RSX-11
System Library Routines
Ref ere nee Manual
Order No. AA-5580A-TC

RSX-11M V3.1
IAS V2.0
RSX-11 D V6.2

jTo order additional copies of this document, contact the Software Distributior:-i
L.:.~nter, Digital Equipment Corporation, Maynard, Massachusetts 01754

digib:JI equipnnent corporation · maynard, massachusetts

First Printing, December 1977

The information in this document is subject to change without noti.ce
and should not be construed as a commi.tment by Digital Equipment
Corporation. Digital Equipment Corpoz~ation assumes no responsibility
for any errors that may appear in this1 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 for the use or reliability of software on
equipment that is not supplied by DIGITAL or its affiliated companies.

DIGITAL
DEC
PDP
DEC US
UNIBUS
COMPUTER LABS
COMTEX
DDT
DECCOMM
ASSIST-11

DECsystem·-10
DECtape
DIBOL
EDUSYSTEM
FLIP CHIP
FOCAL
INDAC
LAB-8
DECSYSTEM·-20
RTS-8

MASS BUS
OMNIBUS
OS/8
PHA
RSTS
RSX
TYPESET-8
TYPESET-11
TMS-11
ITPS-10

CONTENTS

Page
vii

PREJ~ACE:

0.1
0.2
0.3

MANUAL OBJECTIVES AND READER ASSUMPTI-ONS
STRUCTURE OF THE DOCUMENT
ASSOCIATED DOCUMENTS

vii
vii
viii

CHAPTER

INTRODUCTION

1-1

CHAPTER

2-1

2.1
2.2
2.3
2.4

SAVE ALL REGISTERS
SAVE REGISTERS 3 SAVE REGISTERS 0 SAVE REGISTERS l -

2-2
2-3
2-4
2-S

ARITHMETIC ROUTINES

3-1

3.1
3.1.1
3.1. 2
3.1. 3
3.2
3.2.1
3.2.2
3.2.3

INTEGER ARITHMETIC ROUTINES
Integer Multiply Routine ($MUL)
Integer Divide Routine ($DIV)
Example
DOUBLE-PRECISION ARITHMETIC ROUTINES
Double-precision Multiply Routine ($DMUL)
Double-precision Divide Routine ($DDIV)
Example

3-1

INPUT DATA CONVERSION ROUTINES

4-1

4.1
4.1.1

4-1

4.3.3

ASCII TO BINARY DOUBLE-WORD CONVERSIONS
Decimal to Binary Double-word Routine
(.DD2CT)
Octal to Binary Double-word Routine
(.OD2CT)
Example
ASCII TO BINARY CONVERSIONS
Decimal to Binary Conversion Routine
($CDTB)
Octal to Binary Conversion Routine ($COTB)
Example
ASCII TO RADIX-SO CONVERSIONS
ASCII to Radix-SO Conversion Routine ( $CAT S)
ASCII with Blanks to Radix-SO Conversion
Routine ($CATSB)
Example

OUTPUT DATA CONVERSION ROUTINES

5-1

5.1
5.1.1
5 .1. 2

BINARY TO DECIMAL CONVERSIONS
Binary Date Conversion Routine ($CBDAT)
Convert Binary to Decimal Magnitude
Routine ($CBDMG)

5-1
S-2

CHAPTER

4.1. 2
4 .1. 3

4.2
4.2.1

4.2.2
4.2.3
4.3
4.3.1
4.3.2

CHA.PTER

ROUTINE ($SAVAL)
S ROUTINE ($SAVRG)
2 ROUTINE ($SAVVR)
S ROUTINE ($SAVR1)

3-~1

3-2
3-2
3-2
3-3
3-3
3-4

iii

4-1
4-2
4-3
4-4
4-4
4-S
4-5
4-6
4-6
4-8
4-9

5-3

CONTENTS (Cont.)

Page

5.4

Convert Binary to Signed Decimal Routine
($CBDSG)
Convert Double-precision Binary to Decimal
Routine ( $CDDMG)
Examples
BINARY TO OCTAL CONVERSION
Convert Binary to Octal Magnitude Routine
($CBOMG)
Convert Binary to Signed Octal Routine
($CBOSG)
Convert Binary Byte to Octal Magnitude
Routine ( $CBTMG)
Example
GENERAL PURPOSE BINARY TO ASCII CONVERSION
ROUTINE ( $CBTA)
RADIX-SO TO ASCII CONVERSION ROUTINE ($C5TA)

OUTPUT FORMATTING JROUTINES

6-1

6.1
6.2
6.2.l
6.2.2
6.2.3
6.3
6.3.l
6.3.2

UPPER CASE TEXT CONVERSION ROUTINE ($CVTUC)
DATE AND TIME FORMAT CONVERSION
Date String ConvE:!rsion Routine ($DAT)
Time Conversion Routine ($TIM)
Example
GENERALI ZED FORMAT~[' ING
Edit Message Routine ($EDMSG)
Examples

6-1
6-2
6-2
6-3
6-4
6-5
6-5
6-14

DYNAMIC MEMORY MANl\GEMENT ROUTINES

7-1

7.1
7.2
7.3
7.4

USAGE CONSIDERATIONS
INITIALIZE DYNAMIC MEMORY ROUTINE ($INIDM)
REQUEST CORE BLOCK ROUTINE ($RQCB)
RELEASE CORE BLOCK ROUTINE ($RLCB)

7-2
7-2
7-3
7-4

VIRTUAL MEMORY MANl\GEMENT ROUTINES

8-1

8.1
8.1.1

GENERAL USAGE CONSIDERATIONS
User Error Handling Requirements
Task Building Requirements
VIRTUAL MEMORY INP['IALIZATION ROUTINE ($INIVM)
CORE ALLOCATION ROUTINES
Allocate Block Routine ($ALBLK)
Get Core Routine ($GTCOR)
Extend Task Routine ($EXTSK)
Write Page Routine ($WRPAG)
VIRTUAL MEMORY ALLOCATION ROUTINES
Allocate Virtual Memory Routine ($ALVRT)
Allocate Small Virtual Block Routine
($ALSVB)
Request Virtual Core Block Routine ($RQVCB)
PAGE MANAGEMENT ROUTINES
Convert and Lock Page Routine ($CVLOK)
Convert Virtual to Real Address Routine
($CVRL)
Read Page RoutinE~ ( $RDPAG)
Find Page Routine~ ( $FNDPG)
Write-marked Page~ Routine ( $WRMPG)

8-2
8-2
8-3
8-5
8-8
8-9
8-11

5.1. 3
5.1. 4

5 .1. 5
5.2
5.2.l

5.2.2
5.2.3
5.2.4
5.3

CHAPTER

8 .1. 2

8.2
8.3
8.3.l
8.3.2
8.3.3
8.3.4
8.4
8.4.1
8.4.2
8.4.3
8.5
8.5.l
8.5.2

8.5.3
8.5.4
8.5.5

5-4

5-5
5-6
5-7
5-7

5-8
5-9
5-10
5-10

s-.11

8-13
8-14
8-16
8-16
8-18
8-20
8-21
8-22
8-24
8-26
8-27
8-29

CONTENTS (Cont. )

Page
8.5.6
8.5.7
CHAP'TER

APPENDIX A

Lock Page Routine ($LCKPG)
Unlock Page Routine ($UNLPG)

8-31
8-32

SUMMARY PROCEDURES

9-1

SYSTEM REFERENCE BIBLIOGRAPHY

A-1

FIGURES
FIGURE

2-1
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

2-2
8-7
8-10
8-12
8-14
8-15
8-17
8-19
8-21
8-24
8-25
8-27
8-29
8-30
8-32
8-33

TABLES
TABLE

6-1
8-1
9-1
9-2
9-3
9-4
9-5
9-6
9-7

$EDMSG Routine Editing Directives
Content of the Virtual Memory Management
Library File
Register Handling Routines Summary
Arithmetic Routines Summary
Input Data Conversion Routines Summary
Output Data Conversion Routines Summary
Output Formatting Routines Summary
Dynamic Memory Management Routines Summary
Virtual Memory Management Routines Summary

6-7
8-4
9-1
9-2
9-3
9-4
9-5
9-7
9-8

PREFACE

0.1

MANUAL OBJECTIVES AND READER ASSUMPTIONS

The IAS/RSX-11 System Library Routines Reference Manual describes the
usage and function of the system library routines that may be called
from MACR0-11 assembly language programs. This manual is intended for
use .by exper :ienced MACR0-11 assembly language programmers.

0.2

STRUCTURE OF THE DOCUMENT

Chapter 1 presents a general description of the services provided
the system library routines and their functional relationships.
Chapter 2 describes the usage and function of
routines.

the

handling

Chapter 3 describes the usage and function of the arithmetic routines.
Chapter 4 describes
conversion routines.

the

usage

and

function

the

input

data

Chapter 5 describes
conversion routines.

the

usage

and

function

the

output

data

Chapter 6 describes the usage and function of
routines.

the

Chapter 7 describes the usage
management routines.

and

function

the

dynamic

memory

Chapter 8 describes the usage
management routines.

and

function

the

virtual

memory

calling

sequences

the

system

library

Chapter 9 summarizes the
rou1tines.

output

formatting

Appendix A presents a cross-reference system bibliography of other
manuals that describe routines available to IAS/RSX-11 systems users.

vii

0.3

ASSOCIATED DOCUMENTS

The following manuals are
readers of this manual:

prerequisite

sources

information

for

IAS/RSX-11 MACR0-11 Reference Manual.

•

The Task Builder Reference Manual for the appropriate _system.

•

The manuals referenced in Appendix A.

The reader should refer to the applicable documentation directory
descriptions of other documents associated with this manual.

viii

for

CHAPTER 1
INTRODUCTION

The routines described in this manual were written to provide commonly
needed capabilities for DIGITAL-supplied utilities. We are happy to
supply documentation for them, because the routines are general enough
to be used regularly by most MACRb-11 programmers. Note, however,
that the basic functionality of the routines described in this manual
cannot be changed, due to the potentially widespread effect it may
have on our system utilities.
The syBtem library routines may be called by MACR0-11
language programs to perform the following services:

assembly

•

Save and restore register content to enable transfers of
control between the calling program and called subroutines.

•

Perform integer
division.

•

Convert ASCII input
format.

•

Convert internal binary and
data.

•

Convert and format output data to produce text for a
printout or display.

•

Manage the dynamic memory space available to the task that
requires a small-to-moderate amount of resident memory for
data.

•

Manage memory and disk file storage to accommodate tasks that
require large amounts of memory for data that must be
transferred between memory and a disk work file.

and

double-precision
data

internal
Radix-50

multiplication
binary
data

and

Radix-50

ASCII

output
readable

This manual describes the procedures for calling the library routines
from within the source program, the outputs that are returned to the
executing task, and the interaction between the library routines and
with the executing task.
The system library routines interface with each other to perform their
various services.
For example, the data conversion routines call the
arithmetic routines to perform the required multiplication
and
division.
All library routines preserve the contents of the calling
task's registers, generally by calling the appropriate register
handling routine to:

1-1

INTRODUC'l'ION

•

Push register contents to the stack.

•

Subsequently pop the contents back into the registers.

•

Return control to the calling task.

The data conversion and format control functions performed by the Edit
Message Routine require calls to the output data conversion routines,
which in turn call other routines.
The virtual memory management routines function as an automatic
control system to allocate and deallocate memory, maintain page
addresses and status, and swap pages between memory and disk storage
to accommodate large amounts of data in a limited amount of physical
(dynamic) memory.
The system library routines communicate with the calling task via
registers in which outputs ·are returned and/or settings of the C bit
in the Condition Code of the Processor Status Word. The calling task
can usually determine whether a requested service was successfully
performed by examining the output register(s) and/or testing the C bit
setting when control is returned from the library routine. Exceptions
to this procedure are described in the detailed discussions of given
routines.
The system library routines are supplied to users as
two files:
•

•

The system
following:

library

file

(SYSLIB.OLB),

object

which

code

contains

the

•

the register handling routines, described in Chapter 2.

•

the arithmetic routines, described in Chapter 3.

•

the input and output data conversion routines,
in Chapter 4 and Chapter 5.

•

the output formatting routines, described in Chapter 6.

•

the dynamic memory allocation
descriibed in Chapter 7.

and

release

described

routines

The memory management routines file
(VMLIB.OLB),
which
contains the dynamic and virtual memory management routines.

At task build time, the Task Builder will automatically search the
system library file for any referenced routines.
However,
the
VMLIB.OLB file must be specified at task build time if a task has
referenced the dynamic memory initialization routine described in
Chapter 7, or any of the virtual memory management routines, described
in Chapter 8 of this manual.
Summarized procedures for using the system library routines a~e
presented,
in tabular format, in Chapter 9. This is quick-reference
material, provided for the MACR0-11 assembly language programmer who
has become familiar with the detailed procedures that are explained in
Chapters 2 through 8 of this manual.
Additional Executive and I/O routines available to IAS/RSX-11 systems
users
are
described
in other manuals.
The System Reference
Bibliography in Appendix A presents a cross-reference listing of these
manual titles, and functional descriptions of types of services
described in the respective manual.

1-2

CHAPTER 2
REGISTER HANDLING ROUTINES

There are four register handling routines in the system library:
•

Save All Registers Routine
($SAVAL), which
saves
and
subsequently
restores registers O - 5, as described in
Section 2 .1.

•

Save Registers 3 - 5 Routine
($SAVRG) ,
subsequently
restores registers 3 - 5,
Section 2.2.

which saves and
as described in

•

Save Registers 0 - 2 Routine
($SAVVR),
subsequently
restores registers 0 - 2,
Section 2.3.

which saves and
as described in

•

Save Registers 1 - 5 Routine
($SAVR1),
subsequently
restores registers 1 - 5,
Section 2.4.

which saves and
as described in

The register handling routines function as co-routines to enable
control swapping between themselves, a subroutine, and the original
caller of the subroutine.
To illustrate the effect of using the register handling routines,
assume the following:
an original caller calls a subroutine. The
subroutine calls a register handling co-routine.
The co-routine
pushes the contents of the specified registers to the stack, and
issues a co-routine call back to the subroutine.
The subroutine
execute!S to completion, when a RETURN instruction is executed to swap
control back to the co-routine.
The co-routine pops the initial
contents of the registers from the stack and returns to the original
caller.
Figure 2-1 illustrates the control swapping function performed by
register handling routines.

the

The regrister handling routines are called by other
system library, as noted throughout this document.

the

2-1

routines

$SAVAL

SAVE ALL REGISTERS

ORIGINAL CALLER
START

CALL (Subroutine) ----(Subroutine)
JSR r,$SAVxx --------1... $SAVxx (save registers)

TL_____{(is ~e

co-routine call
to subroutine)

____r-(restore registers)

RETURN--

END

•

RETURN (to original caller)

I
Figure 2-1

2 .1

Control Swapping of the Register Handling Routines

SAVE ALL REGISTERS ROUTINE

( $SAVJ~L)

following

PC,$SAVAL

The subroutine must return control to the $SAVAL routine with a RETURN
source statement.
On entry to the $SAVAL routine, the program stack contains the return
address to the original caller and the return address of the
subroutine. The $SAVAL routine pushes the contents of registers 4 - 0
to the stack.
The $SAVAL routine moves the subroutine's return address to the
position following Register O's contents, and moves the current
contents of RS to the stack above the contents of R4.
The $SAVAL routine issues a co-routine~ call, in the form CALL @(SP)+,
to swap control back to the subroutine. The co-routine call replaces
the subroutine's return address with the return address to the $SAVAL
routine.
When control returns to the subroutine the stack pointer
points to $SAVAL's return address. The stack contains the following:

2-2

SAVE ALL REGISTERS
SAVE REGISTERS 3-5

$:SAVAl
$:SAVRG

r--·

Return Address to Original Caller
r-·

Return Address to $SAVAL
'--·

The :subroutine executes until a RETURN
('RTS PC')
instruction is
executed, which swaps control back to the $SAVAL routin e. The
contents of RO - RS are restored
(popped from the stack)
and the
$SAVl\.L routine RETURNs, via an 'RTS PC' instruction, to the original
1

calh~r.

2.2

SAVE REGISTERS 3 - 5 ROUTINE ($SAVRG)

The $SAVRG routine saves and subsequently restores registers 3 ·- 5 for
a subroutine.
The $SAVRG routine functions as a co-routi.n1e which
swaps control between itself, a subroutine, and the original caller.
To call the $SAVRG routine, the subroutine must contain the
Jump to Subroutine instruction:

following

JSR R5,$SAVRG
The subrout:im~ must return control to the $SAVRG routine with a RETURN
source statement.
On entry to the $SAVRG routine, the program stack contains the return
address to the original caller and the contents of RS of the original
callE~r.
The $SAVRG routine pushes the contents of registers 4 and 3
to the stack, then pushes the current contents of RS (return address
to the subroutine) to the stack.
The ~iSAVRG routine copies the original contents back into HS and
issues a co-routine call, in the form CALL @(SP)+, to swap control
back to the subroutine. The co-routine call replaces the subroutine's
return address with the return address to the $SAVRG routine.. When
control returns to the subroutine,
the stack pointer points to
$SAVRG's return address. The stack contains the following:

2-3

$SAVRG
$SAVVR

SAVE REGISTERS 3-6
SAVE REGISTERS 0.2

Return Address to Original Caller
Register 5 contents of Original Caller
Register 4
Register 3
Return Address to $SAVRG
The subroutine executes until a RET URN
( 'RTS PC')
instruction is
executed, which swaps control back to the $SAVRG routine. The
contents of registers 3 - 5 are restored (popped from the stack)
and
the $SAVRG routine RETURNS, via an 'RTS PC' instruction, to the
original caller.
1

2.3

SAVE REGISTERS 0 - 2 ROUTINE ($S:AVVR)

The $SAVVR routine saves and subsequently resto:res registers 0 - 2 for
a subroutine.
The $SAVVR routine functions as a co-routine which
swaps control between itself, a subroutine, and the original caller.
To call the $SAVVR routine, the subroutine must contain the
Jump to Subroutine instruction:

following

JSR R2,$SAVVR
The subroutine must return control to the $SAVVR routine with a RETURN
source statement.
On entry to the $SAVVR routine, the program stack contains the return
address to the original caller and the contents of R2 of the original
caller. The $SAVVR routine pushes the contents of registers 1 and 0
to the stack, then pushes the current contents of R2 (the return
address to the subroutine) to the stack.
The $SAVVR routine copies the original contents back into R2 and
issues a co-routine call, in the form CALL @(SP)+, to swap control
back to the subroutine. The co-routine call replaces the subroutine's
return address with the return address to the $SAVVR routine. When
control returns to the subroutine,, the stack pointer points to
$SAVVR's return address. The stack contains the following:
Return Address to Original Caller
Register 2 contents of Original Caller
Register 1
Register 0
R~turn

Address to $SAVVR

SAVE REGISTERS 0-2
SAVE REGISTERS 1-6

$SAVVR
$SAVR1

2.4

SAVE REGISTERS 1 - 5 ROUTINE ($SAVR1)

The $SAVR1 routine saves and subsequently restores registers 1 - S for
a subroutine.
The $SAVR1 routine functions as a co-routine which
swaps control between itself, a subroutine, and the original caller.
To call the $SAVR1 routine, the subroutine must contain the
Jump to Subroutine instruction:

following

JSR RS,$SAVR1
The subroutine must return control to the $SAVR1 routine with a RETURN
source statement.
On entry to the $SAVR1 routine, the program stack contains the return
address to the original caller and the contents of RS of the original
caller. The $SAVR1 routine pushes the contents of registers 4, 3, 2,
and 1, and the current contents of RS (the return address to the
subroutine) to the stack.
The $SAVR1 routine copies the original contents back into RS and
issues a co-routine call, in the form CALL @(SP)+, to swap control
back to the subroutine. The co-routine call replaces the subroutine's
return address with the return address to the $SAVR1 routine. When
control returns to the subroutine,
the stack pointer points to
$SAVRl's return address. The stack contains the following:
Retur n Address to Original Caller
Regis ter

s contents of Original Caller

Regis ter 4
Regis ter 3
Regis ter 2
Regis ter 1
Re tun1 Address to $SAVR1
The subroutine executes until a RETURN
('RTS PC')
instruction is
executed, which swaps control back to the $SAVR1 routine. The
contents of registers 1 - 5 are restored (popped from the stack)
and
the $SAVR1 routine RETURNs, via an
'RTS PC' instruction, to the
original callE~r.

2-5

CHAPTER 6
OUTPUT FORMATTING ROUTINES

The output formatting routines convert internally stored data to
external ASCII characters and format the converted characters to
produce readable output. There are four output formatting routines:
•

ThE~
Upper Case Text Conversion Routine
( $CVTUC) ,
which
converts lower case ASCII text to upper case, as described in
Section 6.1.

Date String Conversion Routine ($DAT), which converts a
• The
three-word binary date to a nine-character ASCII output
string, as described in Section 6.2.1.

6 .1

•

The Time Conversion Routine ($TIM), which converts the binary
time to an ASCII output string, as described in Section 6.2.2.

•

The Edit Message Routine ($EDMSG) , which converts internally
stored
data
to the user-specified type of ASCII data
(alphanumeric, octal, decimal) and formats the converted data
to produce meaningful output for printing or display, as
described in Section 6.3.

UPPER CJ~SE TEXT CONVERSION ROUTINE ($CVTUC)

•

Supply three input arguments in the task's source code:
•

in Register 0, the address
converted.

•

in Register 1, the address of the
upper case string.

•

in Register 2, the number of bytes in the
converted.

Include the statement
CALL $CVTUC
in the source program.

6-1

the

text

string

output

area
string

to
for
to

be
the
be

$CVTUC
$DAT

UPPER CASE TEXT CONVERSION
DATE STRING CONVERSION

The $CVTUC routine does not use registers 3 - 5 of the calling task.
The content of R2 (byte count) is destroyed on return to the calling
task. Registers O and 1 are not altered.
The $CVTUC routine converts all ASCII alphabetic characters in the
input string to upper case. Any other characters are moved from the
input area to the output area in their sequential positions. The user
may specify the input area address as the output area address (RO =
Rl) when the $CVTUC routine is called. In this instance, the lower
case alphabetic characters are converted to upper case in place in the
input area. The original lower case content of the input area is, of
course, destroyed.

DATE AND TIME FORMAT CONVERSION

6.2

These routines convert the binary date and time to formatted ASCII
output strings.
The date is converted and formatted for output as
follows:
day-month-year.
The time is converted and formatted for output in one of the following
forms:
hour
hour:minute
hour:minute:second
hour:minute:second:tick
These routines and the procedures for
detail in the following sections.

6.2.1

using

them

are

described

Date String Conversion Routine ($DAT)

The $DAT routine converts the three-word internal binary date
standard nine-character ASCII output format, as follows:

the

dd-mmm-yy
where:
dd
day (1 - 31)
mmm = month (first 3 letters)
yy = year (last 2 digits)
To call the $DAT routine, the user must:
•

Supply two input arguments in the program's source code:
•

in Register O, the address of the output
the converted date is to be stored.

area

•

in Register 1, the address of the three-word input area
in which the binary date is stored. The input area must
contain the following:
word 1 = last two digits of year
word 2
a number from 1 - 12 (month of year)
word 3 = a numeric value 01 - 31 (day of month)

6-2

which

DATE STRING CONVERSION
TIME CONVERSION

•

$DAT
$TIM

Include the statement
CALL $DAT
in the source program.

NOTE: The $DAT routine does
input.

not

perform

validity

checking

the

The $DA'.r routine calls the $SAVRG routine to save and restore the
content of registers 3 - 5 of the calling task. The $DAT routine uses
Register 2 and possibly destroys its content. Hence, the calling task
should save any critical value in Register 2 before calling the $DAT
routine. Outputs from the $DAT routine are the following:
string~

•

The converted date
area.

stored

the

specified

output

•

RO = the address of the next available location in the

output

an~a;

•

6.2.2

Rl = the next address (input Rl + 6) in the input area.

Time Conversion Routine {$TIM)

The $TIM routine converts the binary time, in a standard format, to an
ASCII output string of the form:
HH:MM:SB.S
The standard format for $TIM input values is shown
table.

the

following

word

Significance

Output
Format

Value Range

WDl

Hour-of-Day

- 23

WD2

Minute-of-Hour

- 59

WD3

Second-of-Minute

- 59

WD4

Tick-of-Second

depends on clock frequency

WD5

Ticks-per-Second

.s
.s

depends on clock frequency

To call the $TIM routine:
•

Supply three input arguments in the task's source code:
•

in Register 0, the address of the output area in which
the converted time is to be stored.

•

in Register 1, the starting address of the input area in
which the time values are stored.

•

in Register 2, the parameter count, where:
R2

= 0 or 1, to specify that the hour (word 1) is to be
converted in the format HH.

6-3

EDIT MESSAGE

$EDMSG

The source statements:

MOV
MOV'
CALL
MOV

#D rBLK ,RO
#BJDBLK,Rl
$DAT
#11, (RO)+

MOV'

#3. ,R2

CALL

$TIM

After execution, the output buffer will contain:
Ol-·NOV-77

6.3

10:15:35

GENERALIZED FORMATTING

Generali.zed output formatting is provided by the Edit Message Routine
($EDMSG).
The $EDMSG routine allows the user to request the
conversion of internally stored data to ASCII decimal, octal, or
alphanumeric characters and to control the layout of the converted
characters to produce formatted output to be printed or displayed as
meaningful,
readable text.
The user may request the conversion of
strings of data and their formatting in columns. Varying ASCII data
types c:an be incorporated in a given formatted line of the output.
Spacing within lines and between lines can be controlled by the user.
The procedures for converting data and producing formatted output with
the $EDMSG routine are described and illustrated in the following
section ..

6.3.1

Edit Message Routine ($EDMSG)

The $EDMSG routine edits internally formatted data,
in an argument
block,
to external format and stores it in the calling task's output
block. The editing performed by the $EDMSG routine is specified by
user directives within an input string.
Input strings may contain
ASCII text as well as editing directives. Any non-editing directive
characters are simply copied into the output block. Any number of
directives may appear in an input string.
Input strings must be in
ASCIZ format.

6-5

$EDMSG

EDIT MESSAGE

Editing directives are of two types:
data
control. The directives must be of the form:

conversion

and

format

editing

directive

%1, %nl or %Vl
where:
%

is a delimiter which identifies an
the $EDMSG routine.

is an optional repeat count
(decimal number)
specifying
the number of times the editing operation is to be
repeated by the $EDMSG routine.
If n = 0 or is not
specified, a repeat count of l is assumed.

specifies that the repeat count is a
word in the task's argument block.

is an alphabetic letter specifying one of 18 editing
operations to b~ performed by the $EDMSG routine, as shown
in Table 6-1.

See Section 6.3.2 for examples
strings.

editing

6-6

value

directive

use

the

input

EDIT MESSAGE

$EDMSG

Table 6-1
$EDMSG Routine Editing Directives
Form

Operation

Move the ASCII character from address
in ARGBLK to OUTBLK.

%nA

Move the next n ASCII characters
address in ARGBLK to OUTBLK.

%VA

Use the value in the next word in
ARGBLK as repeat count and move the
specified number of ASCII characters
from address in ARGBLK to OUTBLK.

(binary
byte to
octal
conversion)

Convert
the next binary byte from
address in ARGBLK to octal number
and store result in OUTBLK.

%nB

Convert the next n binary bytes from
address in ARGBLK to octal numbers,
and store results in OUTBLK;
insert
space between numbers.

%VB

Convert the binary value in the next
word in ARGBLK to signed decimal and
store result in OUTBLK.

%nD

Convert the next n binary values in
ARGBLK to signed decimal and store
results in OUTBLK;
insert tab between
numbers.

%VD

Use the value in the next word in
ARGBLK as repeat count, convert the
specified number of binary values to
signed decimal and store results in
OUTBLK;
insert tab between numbers.

Directive
A

(ASCII*
string)

(binary to
signed
decimal
no
suppression
conversion)

from

* Extended ASCII characters consist of the printable characters in
the 7-bit ASCII code.
If non-printable characters appear in an
ASCII input string, the E directive replaces them with a space,
while the A directive transfers the non-printable characters to the
output bloc:k.
KEY:

ARGBLK = The argument block containing the binary data to be
converted, or the addresses of ASCII and extended
ASCII characters.
OUTBLK = The output block in which $EDMSG is to store output.
(continued on next page)

6-7

$E0MSG .EDITMESSAGE
Table 6-1 (Cont.)
$EDMSG Routine Editing Directives
Directive
E

(extended
ASCII*)

Form

Operation

Move the extended ASCII character from
the address in ARGBLK to the OUTBLK.

~~~~~-1-~~~~~·~~~~~~~~~~~~~~~-~-~

%nE

Move n extended ASCII characters
the address in ARGBLK to OUTBLK.

%VE

Use the value in the next word in
ARGBLK as repeat count and move the
specified number of ASCII characters
to OUTBJC..K.

Insert
OUTBLK.

%nF

Insert n
OUTBLK.

%VF

Use the value in the next word in
ARGBLK as repeat count, and insert
specified
number
of
form
feed
characters in OUTBLK.

(binary to
decimal
magnitude,
0 suppress
conversion)

Convert the binary value in the next
word in ARGBLK to decimal magnitude
with leading zeroes suppressed and
store the result in OUTBLK.

%nM

Convert the next n binary values in
ARGBLK to decimal
magnitude
with
leading zeroes suppressed and store
the results in OUTBLK;
insert tab
between numbers.

%VM

(form
feed)

from

form

feed

character

form

feed

characters

6-8

EDIT MESSAGE

$EDMSG

Table 6-1 (Cont.)
$EDMSG Routine Editing Directives
Directive

Form

Operation

Insert
OUTBI,K.

%nN

Insert n
OUTBLK.

%VN

Use the value in the next word in
ARGBLK as repeat count, and insert the
specified number
of
CR
and
LF
characters in OUTBLK.

(binary to
signed
octal
conversion)

Convert the binary value in the next
word in ARGBLK to signed octal and
store the result in OUTBLK.

%n0

Convert the next n binary values in
ARGBLK to signed octal and store the
results in OUTBLK;
insert tab between
numbers.

%VO

Use the value in the next word in
ARGBLK as repeat count, convert the
specified number of binary values to
signed octal and store the results in
OUTBLK;
insert tab between numbers.

(binary to
octal maqnitude conversion)

Convert the binary value in the next
word in ARGBLK to octal magnitude and
store the result in OUTBLK.

%nP

Convert the next n binary values in
ARGBLK to octal magnitude and store
the results in OUTBLK;
insert tab
between numbers.

%VP

Use the value in the next word in
ARGBLK as repeat count, convert the
specified number of binary values to
octal magnitude, and store the results
in
OUTBLK;
insert
tab
between
numbers.

(new line-carriage return/line
feed)

KEY:

and
CR

and

characters in
LF characters in

6-9

$EDMSG

EDIT MESSAGE

Table 6-1 (Cont.)
$EDMSG Routine Editing Directives
Directive
R

Form

Operation

Convert the Radix-SO value in the next
word in ARGBLK to ASCII and store the
result in OUTBLK.

%nR

Convert the next n Radix-SO values in
ARGBLK to ASCII and store the results
in OUTBI~K.

%VR

Use the value in the next word in
ARGBLK as repeat count, convert the
specified number of Radix-SO values to
ASCII,
and
store the results in
OUTBLK.

Insert a space in OUTBLK.

%nS

Insert n spaces in OUTBLK.

%VS

Use the value in the next word in
ARGBLK as repeat count, and insert the
specified number of spaces in OUTBLK.

Convert the double-precision unsigned
binary value in ARGBLK to decimal
and store result in OUTBLK.

%nT

Convert the next n double-precision
binary values in ARGBLK to decimal and
store results in OUTBLK;
insert tab
between numbers.

%VT

Use the value in the next word in
ARGBLK as repeat count, convert the
specified number of double-precision
binary values to decimal, and store
the results in OUTBLK;
insert tab
between numbers.

(Radix-SO
to ASCII)

(space)

(double precision
binary to
decimal
conversion)

KEY:

ARGBLK = The argument block containing the binary data to be
converted, or the addresses of ASCII and extended
ASCII characters.
OUTBLK = The output block in which $EDMSG is to store

output.

(continued on next page)

6-10

EDIT MESSAGE

$EDMSG

Table 6-1 (Cont.)
$EDMSG Routine Editing Directives
Form

Operation

(binary to
decimal magnitude, no
0 suppress
conversion)

Convert the binary value in ARGBLK to
decimal
magnitude with no leading
zeroes suppressed and store result in
OUTBLK.

%nu

Convert the next n binary values in
ARGBLK to decimal magnitude with no
leading zeroes suppressed and store
results in OUTBLK; insert tab between
numbers.

%VU

Convert Radix-SO file name string in
ARGBLK
to ASCII string in format
NAME.TYP;
convert
octal
version
number, if present, to ASCII and store
results in OUTBLK.

%nX

Convert next n Radix-SO file name
strings in ARGBLK to ASCII string in
format
NAME.TYP;
convert
octal
version numbers, if present, to ASCII
and store results in OUTBLK;
insert
tab between strings.

%VX

Use the value in the next word in
ARGBLK
as
repeat
count, convert
specified number of Radix-SO file name
strings to ASCII strings in format
NAME.TYP;
convert
octal
version
numbers, if present, to ASCII and
store results in OUTBLK;
insert tab
between strings.

Convert the next three binary words
in ARGBLK to ASCII date in format
dd-mmm-yy and store in OUTBLK.
In
this directive a repeat is acceptable,
but will be ignored.

Direct:ive

x
(file! name
string
conve~r sion)

(date conVE~rsion)

KEY~

6-11

$EDMSG

EDIT MESSAGE

Table 6-1 {Cont.)
$EDMSG Routine Editing Directives
Directive

{binary time
to ASCII
conversion)

Form

Operation

%OZ
or

Convert binary hour-of-day in the next
word of ARGBLK to ASCII and store in
OUTBLK in format HH.

%1Z

%2Z

Convert the binary hour-of-day and
minute-of-hour in the next two words
of ARGBLK to ASCII and store in OUTBLK
in format HH:MM.

%3Z

Convert
the
binary
hour-of-day,
minute-of-hour, and second-of-minute
in the next three words of ARGBLK to
ASCII and store in OUTBLK in format
HH:MM:SS.

%4Z
or
%5Z

Convert the binary
hour-of-day,
minute-of-hour, second-of-minute, and
ticks-of-second or ticks-per-second in
the next five words of ARGBLK to ASCII
and store
in
OUTBLK
in
format
HH:MM:SS.S,
where
.s = tenth of
second.

%n<

Insert n ASCII spaces followed by a
field mark (NULL) in OUTBLK to define
a fixed length byte field. The output
pointer will point to the first space.

%n>

Increment the OUTBLK pointer until a
field mark
{NUL)
is located or the n
repeat count is exceeded.

(define
byte
field)
{locate
field
mark)
KEY:

ARGBLK = The argument block containing the binary data to be
converted, or the addresses of ASCII and extended
ASCII characters.
OUTBLK = The output block in which $EDMSG is to store output.

Prior to calling the $EDMSG routine,
appropriate argument block, as follows:

the

user

must

set

the

•

If ASCII or extended ASCII characters are to be moved to the
output block, the argument block must contain the addresses of
the ASCII characters.

•

If binary byte to oct~l conversion is to be performed, the
argument block must contain the addresses of the binary bytes.

•

If binary values are to be converted, the argument block
contain the values.

6-12

must

CHAPTER 7
DYNAMIC MEMORY MANAGEMENT ROUTINES

The dynamic memory management routines allow the user to manually
manage the space in a task's free dynamic memory. The free dynamic
memory consists of all memory extending from the assembled code of the
task to the highest virtual address owned by the task, excluding
resident libraries.
Initially, free dynamic memory is allocated as one large block,
from
the highest available memory address downward. Subsequent memory
block allocations are made within the available memory blocks.
Available memory blocks are maintained as a linked list of blocks in
ascending order, pointed to by a two-word listhead. Each free memory
block contains a two-word control field, where:
•

The first word contains the address of the
block, or zero if there is not another block.

available

•

The second word contains the size of the current block.

Memory allocation is either on a first-fit or best-fit basis.
Allocation is always made from the top of the selected available
dynamic memory block. The second word of the block is adjusted to
reflect the new size of the current block of available dynamic memory.
As memory blocks are allocated completely, they are removed from the
free memory list.
When memory blocks are deallocated (released}, they are returned to
the free memory list. The released memory blocks are relinked to the
free memory list in ascending address order.
If possible,
released
memory blocks are merged with adjacent memory blocks to form a single,
large block of free dynamic memory.
There are three routines that are called
management functions:

perform

dynamic

memory

•

Initialize Dynamic Memory Routine ($INIDM}, which
the task's free dynamic memory.

initializes

•

Request Core Block Routine ($RQCB}, a system library routine
which allocates blocks of memory in the free dynamic memory.

Release Core Block Routine ($RLCB}, a system library routine
• which
releases
(deallocates}
previously allocated memory
blocks in the executing task's free dynamic memory.

7-1

$1Nl0M
7.1

INITIALIZE DYNAMIC MEMORY

USAGE CONSIDERATIONS

To use the dynamic memory management routines, the user
the following in the source program:
•

provide

A two-word free memory listhead:
FREEHD:

•

must

.BLKW 2

The appropriate call argument(s) and statement for the given
routine, as described in Sections 7.2, 7.3, and 7.4 of this
chapter.

At task build time, the user must specify the following
LB: [l,l]VMLIB/LB:INIDM:EXTSK
to include the memory management modules INIDM and EXTSK in the task.

7.2

INITIALIZE DYNAMIC MEMORY ROUTINE ($INIDM)

The $INIDM routine establishes the initial state of the free dynamic
memory available to the executing task.
The free dynamic memory
consists of all memory extending from the end of the task code to the
highest
virtual
address used by the task, excluding resident
libraries.
To call the $INIDM routine:
•

Specify, in
listhead.

•

Include the statement

the

address

the

free

memory

CALL $INIDM
in the source program.
The outputs from the $INIDM routine are:
e

the first address in the task.

the address following the task code (the first
address in the free dynamic memory) .

•

R2 = the size of the free dynamic memory.

available

Rounds the free dynamic
four-byte boundary.

memory

•

Initializes the free dynamic memory as a single large block of
memory.

7-2

base

address

the

VIRTUAL MEMORY INITIALIZATION

$1NIVM

Four modules in the statistical version of the routines set up and/or
maintain statistics of the usage of the work file and memory. These
modules and their associated statistical data fields are:
•

The INIVS modules, which initializes three double-word fields:
the total work file access field ($WRKAC); the work file read
count field {$WRKRD); and the work file write count field
($WRKWR).
Each of these fields is a double word integer
contained in the global data storage module
(VMDAS)
for the
statistical version of the routines.

•

The CVRS module, which maintains the count of total work
accesses in the $WRKAC field.

•

The RDPAS module, which maintains a total of the work file
reads in the $WRKRD field and a total of the work file writes
in the $WRKWR field.

•

The GTCOS module, which maintains a count of the total amount
of free dynamic memory in the $FRSIZ single-word field. This
field must be defined and initialized in the ~ource program.

file

The statistical version of the virtual memory management routines does
not
automatically
report these statistics.
It is the user's
responsibility to provide for the output of the statistical data in
the fields described above if the statistical version of the routines
is used.
To use the statistical routines, the user must specify, at task build
time, the virtual memory management routines library file, the names
of all statistical modules whose routines will be used at task
execution time, and the name of the global data storage module. The
only optional modules are ALSVB and INIDM.
Following
is
a
specification that identifies all modules of the statistical version
of the routines.
LB: [l,l]VMLIB/LB:ALBLK:ALSVB:ALVRT:CVRS:EXTSK:FNDPG:GTCOS
LB: [l,l]VMLIB/LB:INIVS:MRKPG:RDPAS:RQVCB:VMUTL:INIDM:VMDAS
The non-statistical routines use the global data storage module,
VMDAT'. To use the non-statistical routines, the user must specify, at
task build time, the virtual memory management routines library file,
the names of all non-statistical modules whose routines will be used
at task execution time, and the name of the global data storage
module.
The only optional modules are ALSVB and INIDM. Following is
a specification that identifies all modules of the non-statistical
version of the routines.
LB: [l,l]VMLIB/LB:ALBLK:ALSVB:ALVRT:CVRL:EXTSK:FNDPG:GTCOR
LB: [l,l]VMLIB/LB:INIVM:MRKPG:RDPAG:RQVCB:VMUTL:INIDM:VMDAT

8.2

VIRTUAI1 MEMORY INITIALIZATION ROUTINE ($INIVM)

8-5

$1NIVM

VIRTUAL MEMORY INITIALIZATION

To use the $INIVM routine:
•

Define and initialize a two-word field named $FRHD.
the field, include the code

To define

$FRHD:: .BLKW 2.
in the source program. To initialize the field, store
starting address of the free dynamic memory in $FRHD.
•

the

Define three global symbols in the source program:
W$KLUN

Logical unit number (LUN) to be used for the work
file.
The user is also responsible for assigning
this LUN to a disk device.

W$KEXT

N$MPAG

Fast page search page count. If there is sufficient
dynamic memory to allocate at least the number of
pages specified, 512 words of dynamic memory will be
set
aside
to
speed
up
the
searching
of
memory-resident pages.

•

Specify, in Register 1, the highest address of the task's free
dynamic memory.

•

Include the statement
CALL $INIVM
in the source program.

NOTE: Before calling the $INIVM routine, the task may call the $INIDM
routine (see Chapter 7), which returns the starting address of dynamic
memory and the total size of dynamic memory.
The outputs from the $INIVM routine .are:

• Initialization successful:
Condition Code

c bit = clear.

and
RO

= 0.

• Initialization failure:
Condition Code

c bit

set.

and
RO = -2 to indicate work file open failure.
RO
-1 to indicate work file mark-for-deletion failure.
Also, the FCS error code may be examined at offset F.ERR
in the work file FDB. The address of the FDB is stored
in the word $WRKPT.

8-6

CHAPTER 9
SUMMARY PROCEDURES

The procedures fo~ using the system library routines are summarized in
tabular format in this chapter.
These summaries are presented as
quick reference guides for users who are familiar with the detailed
procedures
and
requirements for using individual routines, as
described in preceding chapters of this manual.
Table 9-1
Register Handling Routines :Summary
Routine Name/
Mnemonic

Function

Call Statement

Saves/restores RO - RS

JSR PC,$SAVAL

Saves/resto,res R3 - RS

JSR RS,$SAVRG

Save Registers 0 - 2
$SAVVR

Saves/restores RO - R2

JSR R2,$SAVVR

Saves/restores Rl - RS

JSR RS,$SAVR1

Save All Registers
$SAVAL
Save Registers 3 $SAVRG

Save Registers 1 $SAVR1

9-1

SUMMARY PRCICEDURES

Table 9-2
Arithmetic Routines Summary

Routine Name/
Mnemonic

Input Arguments and
Call Statement

Outputs

Integer Multiply
$MUL

RO = multiplier
Rl = multiplic.and
CALL $MUL

Product:
RO = high order part
Rl = low order part
R2-R5 preserved

Integer Divide
$DIV

RO = dividend
Rl • divisor
CALL $DIV

RO = quotient
Rl .., remainder
R2-R5 preserved

Double-precision Multiply
$DMUL

RO = multiplier
Multiplicandc
R2 = high order part
R3 = low order part
CALL $DMUL

Double-precision Divide
$DDIV

RO = unsigned divisor
Dividend:
Rl = high order part
R2 = low order part

NOTE:

Product:
RO = high order part
Rl = low order part
c = clear
R4-R5 preserved
R2-R3 destroyed
RO = remainder
Quotient:
Rl = high order part
R2 = low order part
R3 preserved

The arithmetic routines accept unsignc~d inputs and produce unsigned results.

Update No.l
IAS/RSX-11 System Library
Routines Reference Manual
AA-5580A-TC, AD-5580A-Tl
READER'S COMMENTS

NOTE::

This form is for document comments only. DIGITAL 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 (SPR) service, submit your comments on an SPR
form ..

Did you find this manual understandable, usable, and well-organized?
Please make suggestions for improvement.

Did you find errors in this manual?
page number.

If so, specify the error and the

Please indicate the type of reader that you most nearly represent.
[] Assembly language programmer
[] Higher-level language programmer
[] Occasional programmer (experienced)
[] User with little programming experience
[] Student programmer
[] Other (please specify>~-~-~-------~~-~--~

Organization
Street
City

, - - - · - - - - - - - - - S t a t e _______ Zip Code _ _ _ _ _ __
or
Country

Do Not Tear - Fold Here and Tape

No Postage
Necessary
if Mai led in the
United States

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

RT/C SOFTWARE PUBLICATIONS TW/A14
DIGITAL EQUIPMENT COHPORATION
1925 ANDOVER STREET
TEWKSBURY, MASSACHUSETTS

Do Not Tear - Fold Here

01876

I
I

(I)

I :§
I]

I~en

I .§
<
l:i
u
I