Digital PDFs

AA-5580A-TC

December 1977

115 pages

Original

4.1MB

Document:	IAS/RSX-11 System Library Routines Reference Manual
Order Number:	AA-5580A-TC
Revision:	0
Pages:	115
Original Filename:	http://bitsavers.org/pdf/dec/pdp11/rsx11m_s/RSX11M_V3.1_Dec77/1A_System_Reference_Information/AA-5580A-TC_RSX-11M_3.1_System_Library_Routines_Reference_Manual_Dec77.pdf

OCR Text

IAS/,RSX-11
System Library Routines
Reference Manual
Order No. AA-5580A-TC

IAS/·RSX-11
System Library Routines
Reference Manual
Order No. AA-5580A-TC

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

To order additional copies of this document, contact the Software Distribution
Center, Digital Equipment Corporation, Maynard, Massachusetts 01754

digital equipment corporation · maynard, massachusetts

First Printing, December 1977

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

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
DECUS
UNIBUS
COMPUTER LABS
COMTEX
DDT
DECCOMM
ASSIST-II

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

MASSBUS
OMNIBUS
OS/8
PHA
RSTS
RSX
TYPESET-8
TYPESET-II
TMS-ll
ITPS-IO

CONTENTS

Page
vii

PREFACE
0.1
0.2
0.3

MANUAL OBJECTIVES AND READER ASSUMPTLONS
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 ROUTINE ($SAVAL)
SAVE REGISTERS 3 - 5 ROUTINE ($SAVRG)
SAVE REGISTERS 0 - 2 ROUTINE ($SAVVR)
SAVE REGISTERS 1 - 5 ROUTINE ($SAVRl)

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

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
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-50 CONVERSIONS
ASCII to Radix-50 Conversion Routine (-$CAT5)
ASCII with Blanks to Radix-50 Conversion
Routine ($CAT5B)
Example

OUTPUT DATA CONV~RSION ROUTINES

5-1

5.1
5.1.1
5.1.2

BINARY TO DECIMAL CONVERSIONS
Binary Date Conversio:n 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

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

5-3

CONTENTS (Cont.)

Page
5.1.3

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-50 TO ASCII CONVERSION ROUTINE ($C5TA)

OUTPUT FORMATTING ROUTINES

6-1

6.1
6.2
6.2.1
6.2.2
6.2.3
6.3
6.3.1
6.3.2

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

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

DYNAMIC MEMORY MANAGEMENT ROUTINES

7-1

7.1
7.2
7.3
7.4

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

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

VIRTUAL MEMORY MANAGEMENT ROUTINES

8-1

8.1
8'.1.1
8.1.2
8.2
8.3
8.3.1
8.3.2
8.3.3
8.3.4
8.4
8.4.1'
8.4.2

GENERAL USAGE CONSIDERATIONS
User Error Handling Requirements
Task Building Requirements
VIRTUAL MEMORY INITIALIZATION 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

5.1.4
5.1.5
5.2
5.2.1
5.2.2
5.2.3
5.2.4
5.3

CHAPTER

8.4.3
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

8-9

8-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

CHAPTER

APPENDIX A

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

8-31
8-32

SUMMARY PROCEDURES

9-1

SYSTEM REFERENCE BIBLIOGRAPHY

A-I

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
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-ll System Library Routines Reference Manual describes the
usage and functiQn of the system library routines that may be called
from MACRO-II assembly. language programs. This manual is intended .for
use by experienced MACRO-II 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
routines.

output

formatting

Appendix A presents a cross-reference syste~ bibliography of other
manuals that describe routines available to IAS/RSX-ll systems users.

vii

0.3

ASSOCIATED DOCUMENTS

The following manuals are
readers of this manual:

prerequisite

sources

information

for

•

IAS/RSX-Il MACRO-II Reference Manual.

•

The Task Builder Reference Manual for the appropriate system.

•

The manuals referenced in App~ndix A.

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

viii

for

CHAPTER I
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 MACRO-II 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 system library routines may be called by MACRO-II
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
prjntout 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 serV1ces. 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

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 be.tween memory and disk storage
to accommodate large amounts of data in a limited amount of physical
(dynamic) memory.
The ~ystem 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 are
presented, 1n tabular format, in Chapter 9. This is quick-reference
material, provided for the MACRO-II 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-ll systems
users
are
described
1n 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

There are four register handling routines in the system library:
•

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

•

($SAVVR),
Save Registers 0 - 2 Routine
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, 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 register 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 - - - - - - I.... $SAVxx (save registers)

'--_ _ _ _ _ _ { (issue co-routine call
to subroutine)

(restore registers)

RETURN - - - - - - '

RETURN (to original caller)

END

Figure 2-1

2.1

Control Swapping of the Register Handling Routines

SAVE ALL REGISTERS ROUTINE ($SAVAL)

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 retu~n 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 R5 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

Return Address to Original Caller
Register 5
Register 4
Register

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 - R5 are restored (popped from the stack) and the
$SAVAL routine RETURNs, via an 'RTS PC' instruction, to the original
caller.

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-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 R5 of the original
caller. The $SAVRG routine pushes the contents of registers 4 and 3
to the stack, then pushes the current contents of R5 (return address
to the subroutine) to the stack.
The $SAVRG routine copies the original contents back into R5 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 SAVEREGISTERS3-6
$SAVVR SAVE REG'STERS 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 RETURN ('RTS PC I )
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 I instruction, _to the
original caller.

2.3

SAVE REGISTERS 0 - 2 ROUTINE ($SAVVR)

The $SAVV~ 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 I 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 I
Register 0
R~turn

Address to $SAVVR

2-4

SAVE REGISTERS ()'2
SAVE REGISTERS 1·5

$SAVVR
$SAVR1

The subroutine executes until a RETURN
('RTS PC I )
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.

2.4

SAVE REGISTERS 1 - 5 ROUTINE ($SAVRl)

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

following

JSR R5,$SAVRI
The subroutine must return control to the $SAVRI routine with a RETURN
source statement.
On entry to the $SAVRI routine, the program stack contains the return
adaress to the original caller and the contents of R5 of the original
caller. The $SAVRI routine pushes the contents of registers 4, 3,
2,
and 1, and the current contents of R5 (the return address to the
subroutine) to the stack.
The $SAVRI routine copies the original contents back into R5 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 $SAVRI routine. When
control returns to the subroutine,
the stack pointer points to
$SAVRl's return address. The stack contains the following:
Return Address to Original Caller
Register 5 contents of Original Caller
Register 4
Register 3
Register 2
Register 1
Return Address to $SAVRI
The subroutine executes until a RETURN
('RTS PC I )
instruction is
executed, which swaps control back to the $SAVRI routine. The
contents of registers 1 - 5 are restored (popped from the stack)
and
the $SAVRI routine RETURNs, via an
'RTS PC I instruction, to the
original caller.

2-5

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

INTEGER ARITHMETIC ROUTINES

The system library contains two routines which
operations on l6-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.1

($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:
•

in Register 0, 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.

•

Rl = 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 dividend.
• in Register 1, the divisor.
•

Include the statement
CALL $DIV
in the source program.

Registers 2 - 5 of the calling easkare preserved.
The output from the $DIV routine is:
•

RO = quotient.

•

the remainder.

The $DIV routine does not return any error 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
RI,WORK+2

the

$MUL

routine

perform

:PUTS MULTIPLIER IN RO.
:PUTS THE MULTIPLICAND AT NDV IN Rl.
: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:

integer

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

$ DDIV

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·PRECISIONMULTIPLY

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 magnitude 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:
•

RO = high order part.

•

Rl = 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 divisor 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:
•

•

$DDIV

DOUBLE·PRECISION DIVIDE

•

Include the statement
CALL $DDIV
in the source program.

The content of Register 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:
•

high order part of quotient.

•

R2 = 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

#150,RO
DVD,Rl

MOV

DVD+2,R2

CALL
MOV
MOV
MOV

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

the

$DDIV

routine

perform

;PUTS DIVISOR IN RO.
iPUTS THE HIGH ORDER PART OF THE DIVIDiEND, STORED IN DVD, IN RI.
iPUTS LOW ORDER PART OF DIVIDEND, STORED
iIN DVD+2, IN R2.
;CALLS $DDIV ROUTINE.
;PUTS HIGH ORDER PART OF QUOTIENT IN QUOT.
iPUTS LOW ORDER PART OF QUOTIENT IN QUOT+2.
iPUTS REMAINDER 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
this 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.

ASCII TO 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 numbe~s as input and converts them to
double-word binary format, d~scribed 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 a - 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 -2 31 to +2 31 -1.

4-1

•DD2 C T DECIMAL TO BINARY DOUBLE WORD
.OD2CT 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 .DD2C~ routine are:

the

calling

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

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 legaliri 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
+2 31 -1.

octal

number:'

4 .... 2

converted

cause

the

_2 31

OCTAL TO BINARY DOUBLE WORD

.OD2CT

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

calling

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 bit = 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

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

iBOUT,R3

MOV

i7,R4

MOV

#ICHR,R5

CALL
BCS

• OD2CT
100$

(continue)

100$:

CALL ERR

:PUTS THE ADDRESS OF THE 2-WORD OUTPUT
:FIELD (BOUT) IN R3.
iPUTS THE NUMBER 7 (NUMBER OF INPUT
: CHARACTERS) IN R4.
:PUTS THE ADDRESS OF THE INPUT CHARACTER
:STRING {ICHR} IN R5 •
: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

$COTS
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 numbers 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.

4.2.1

Decimal to Binary Conversion Routine ($CDTB)

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
$COTB routine is 65,535.
Numbers of greater value will cause
indeterminate results, since the $COTB 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 $COTB
in the source program.
The $COTB routine calls the $SAVRG
registers 3 - 5 of the calling task.

routine

The outputs returned from the $COTB routine are:

•

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

DECIMAL TO BINARY CONVERSION:
OCTAL TO BINARY CONVERSIQN

SCOTS
SCOTS

Since the $CDTB routine returns the address of the next byte in the
input buffer to the calling task, successive input string cQnversion
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.

Valid

binary.

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 ~ymbol. Leading blanks and tab characters
are ignored.
The maximum value of an octal number that
$COTB 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 $COTB routine calls the $SAVRG
registers 3 - 5 of the calling task.

routine

The outputs returned from the $COTB routine are:

•

the address of the next byte in the input butfer.
the converted number.

the terminating character.
• R2
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.
..
.
Successive input string conversion may be effected by setting up a
processing loop as shown in the example for the $CDTB routine in
Section 4.2.3.

4.2.3

Example

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) ~re in the format
xxx (TAB) xxxx (TAB) xx (TAB) xxxxx(SPACE)

4-5

$ CAT 5

ASCII TO RADIX·5O 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 OUTPUT 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 CONVERTED NUMBER IN BNUM
CMP '11,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)

LOO~:

10$:

4.3

'BNUM,R4
'IBUF,RO

ASCII TO RADIX-50 CONVERSIONS

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

alphanumeric

•

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

•

The ASCII with Blanks to Radix-50 Conversion Routine ($CATSB),
which accepts input characters from the ASCII subset and blank
characters and converts them to Radix-50 format, described in
Section 4.3.2.

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

4.3.1

called

perform

the

ASCII to Radix-50 Conversion Routine ($CATS)

The SCATS routine converts from one to three
l6-bit Radix-50 value.

ASCII

characters

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

Alphabetic characters A - Z.

•

Numeric characters 0 - 9.

•

The characters:

dollar sign ($) and period (.).

For complete conversion the string must
three
valid
contain
characters.
Invalid characters will cause the SCATS 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-50 CONVERSION

SCATS

NOTE
A blank character (space) in the ASCII
character string will cause the $CAT5
routine to terminate. If blanks are to
be included as valid characters in the
string, the $CAT5B routine should be
called to perform the conversion (see
Section 4.3.2).
To call the $CAT5 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-50.

Include the statement
CALL $CAT5
in the source program.

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

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

•
•

the converted Radix-50 value (1 - 3 characters).
Rl
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:
C bit = set if fewer than three characters were converted.
C bit

clear if conversion was complete.

The user can determine, in the task, whether conversion was complete
by testing the C bit in th~ 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 $CAT5 statement.

4-7

$C.AT5BASCII WITH BLANKS TQ RADIX·50CONVERSION

4.3.2

ASCII with Blanks to Radix-50 Conversion Routine ($CAT5B)

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

Alphabetic characters A - Z.

•

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:
Rl

first

character

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

•

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 $CAT5B routine calls the $SAVRG
registers 3 - 5 of the calling task.
are:

routine to save and restore
Outputs from the $CAT5B routine

the address of the next character in the input buffer.

•

Rl = the converted Radix-50 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 = set if conversion was incomplete.
C bit

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 res~t'til')g Rl and sett.ing up a proc.essing ,1oGp:backto the
CALL $CAT5B statement.

4-8

INPUT DATA CONVERSION ROUTINES

4.3.3

Example

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

2$:

R2,$SAVVR
'ASDAT,RO

CLR

CALL

$CAT5

BCC

JMP

INER

MOV
Rl,RAD5
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 $CAT5 ROUTINE TO CONVERT ASCII
;TO RADIX-50.
;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 RAD5.
;RETURNS TO MAIN PROGRAM, VIA $SAVVR,
;WHEN CONVERSION COMPLETE.

4-9

the

CHAPTER 5
OOTPUT 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:
•

•

Binary 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 parameters, 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 Radix-50 to ASCII conversion routine, to convert a Radix-50
value to a 3-character ASCII st~ing, 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 TO DECIMAL CONVERSIONS

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

5-1

internally

$CBDAT 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 decimal number, as described in Section 5.1.3.

•

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

These routines use predefined parameters 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

following

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 0, 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

= 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

$C BDAT
$CBDMG

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.

5.1.2

Convert Binary to Decimal Magnitude Routine ($CBDMG)

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
leading 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 =
0, 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

$CBDMG
$CBDS.G

CONVERT BINARY TO DECIMAL MAGNITUDE
CONVERT BINARY TO SIGNED DECIMAL

•

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 $CBDMG routine does not return error conditions to the caller.

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

predefined

number

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 supp~ession indicator, where:
R2 = 0 to specify suppression of leading zeros 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 $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

$CB'DSG
$CDDMG

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 followihg '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 $CODMG 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 $CODMG routine:
•

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

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

•

in Register 1, the address of the two-word
containing the doubie-pr~cision 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, regardle~s of the suppression
indicator setting.
•

Include the statement
CALL $CDDMG
in the source program.

The $COOMG routine calls the$SAVRG routine to save and restore
registers 3 - 5 of the calling task. R~gisters 1 and 2 ~re destroyed.
The $OOIV toutineis called to perform the double-precision division,
and the General Purpose Biriary to ASCII Conversion Routine ($CBTA) is
called to perform the actual ASCII conversion.

5-5

$CD,Q,MG CONVERT DQUBLE-PREC,SIONBINARY TO DECIMAL
Outputs from the $CDDMG routine are:

5. 1. 5

•

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

•

The converted ASCII number, siored iri the output area, or a
string of ASCII asterisks if more than 9 digits resulted in
the conversion attempt.
If the number was succes~~ully
'converted, the output area will contain from four to nine
digits.

the

output

Examples,

Examples of the use of output conversion
this section.
EXAMPLE 1.

presented

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

the

MOV
MOV
CLR

iASDAT,RO
BDAT,Rl
R2

CALL

$CBDAT

routines

ar,e

;PUTS THE ADDRESS OF OUTPUT AREA IN RO.
;PUTS THE BINARY DATE, AT BDAT, 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 statemen,ts to call the $CDDMG
routine to convert a double-precision number to an ASCII
decimal number and check the result.

MOV
MOV

iASDN,RO
iDPWRD,Rl

MOV

#4. ,R2

CALL
CMPB

$CDDMG
i'*,ASDN

BNE

10$

JMP

ERR

:PUTS ADDRESS OF OUTPUT AREA IN RO.
;PUTS STARTING ADDRESS OF DOUBLEiPRECISION INPUT WORD IN Rl.
iPUTS NONZERO IN R2 (SETS THE ZERO
iINDICATOR FLAG TO 1) TO SPECIFY
;THAT LEADING ZEROES ARE NOT TO
iBE SUPPRESSED.
iCALLS THE $CDDMG ROUTINE.
iCOMPARES AN ASCII ASTERISK SYMBOL WITH
iA BYTE OF THE CONVERTED NUMBER.
iIF NOT EQUAL CONVERSION WAS SUCCESSFUL
iAND PROGRAM CONTINUES.
iIF EQUAL, JUMP TO ERROR ROUTINE ERR (MORE
iTHAN NINE DIGITS WERE CONVERTED AND THE
iOUTPUT DATA IS INVALID).

(continue)

5-6

CONVERT BINARY TO OCTAL MAGNITUDE

$CBOMG

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

internally

5.2

BINARY TO OCTAL CONVERSION

•

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

•

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 inte~nally 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 $CBOMG routine converts an internally stored. binary
6-digit unsigned ASCII octal magnitude number.
The $CBOMG
parameters:

routine

uses

the

following

predefined

number

•

conversion

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

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

in Register 0, the starting address o~ 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 $CBOMG
in the source program.

5-7

$CBOMG
$CBOSG

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 th~ user specifies, via R2 =
0, 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 A~CII '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 ate~.

length,

•

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

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

conversion

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

Supply thr~e 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 ntimber.
The odtput 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 =
0, 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 bin.ary number.
5-8

CONVERT BINARY TO SIGNED OCTAL
CONVERT BINARY BYTE TO OCTAL MAGNITUDE

$CBOSG
$CBTMG

The $CBTA routine calls the $SAVRG 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 converted number, a maximum of six digits
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 $CBOSG routine does not return error conditions to the caller.

5.2.3

Convert Binary Byte to Octal Magnitode Rootine ($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.

•

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 $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

$CBTMG
SCBTA

CONVERT BINARY BYTE TO OCTAL MAGNlTUDE
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
pointer to the location following the last digit stored).

(the

•

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

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

tOCOUT,RO

MOV

BNUM,Rl

MOV

t7,R2

CALL

$CBOMG

calling

sequence

:PUTS THE STARTING ADDRESS OF THE OUTPUT
: AREA IN RO.
:PUTS THE BINARY NUMBER TO BE CONVERTED
iIN Rl.
iPUTS THE VALUE 7 IN R2 (SETS THE ZERO
iINDICATOR FLAG TO 1) TO SPECIFY THAT
iLEADING ZEROES ARE NOT TO BE SUPPRESSED.
iCALLS THE $CBOMG ROUTINE.

(continue)

5.3

GE.NERAL 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

$ C B TA

RADIX-50 TO ASCII CONVERSION

$C5TA

Bits 0 - 7:

(low byte) must contain
radix (2.-10.).

the

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
0 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 $CBTA 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
pointer to the location following the last digit stored).

(the

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

5.4

RADIX-50 TO ASCII CONVERSION ROUTINE ($C5TA)

The $C5TA routine converts an internally stored l6-bit Radix-50
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-50

5-11

value

which

$C5TA
•

RADIX-50 TO ASCII 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 registers 3 - 5.
destroyed.

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 lo~er 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

for

the

$CVTUC
$0 AT

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 0 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.

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 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
mmm
yy

day (1 - 31)
month (first 3 letters)
year (last 2 digits)

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

area

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

6-2

which

DATE STRING CONVERSION
TIME CONVERSION

•

SOAT
STIM

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,
area.

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.

6.2.2

stored

the

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

Value Range

WDI

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

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
converted in the format HH.

6-3

(word 1) is to be

$TI M

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, minute, and second
(words 1, 2, and 3) are to be converted in the
format HH:MM:SS.
R2

•

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).

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

output

area.
•

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

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

iYEAR
illTH MONTH (NOV)

iDAY
iHOUR
iMINUTES

iSECONDS

The output area:
DTBLK:

• BLKB

20 •

6-4

EDIT MESSAGE

$EDMSG

The source statements:

MOV
MOV
CALL
MOV

#DTBLK,RO
#BDBLK,Rl
$DAT
#11, (RO)+

MOV

#3. ,R2

CALL

$TIM

iPUTS ADDRESS OF OUTPUT AREA IN RO.
iPUTS ADDRESS OF INPUT BINARY DATE AREA IN Rl.
iCALLS THE $DAT ROUTINE.
iPUTS TAB AFTER DATE IN OUTPUT BUFFER.
iRO NOW CONTAINS NEXT ADDRESS IN DTBLK FROM
i$DAT.
iRl NOW CONTAINS ADDRESS OF NEXT WORD (THE
iHOUR 10) IN BDBLK FROM $DAT.
iSPECIFIES THE HH:MM:SS FORMAT FOR
iCONVERTED TIME.
iCALLS THE $TIM ROUTINE.

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

6.3

10:15:35

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
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 1 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 be 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-"·siore resul t in OUTBLK.

%nB

Convert the next n binary bytes from
address in ARGBLK to octal numbers,
and store results in OUTBLKi
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 OUTBLKi
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 OUTBLKi
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
OUTBLKi
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 block.
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

$EDMSG .EDITMESSAGE
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
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.

(binary to
decimal
magnitude,
o 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

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
ASCII*)

(form
feed)

from

form

feed

character

form

feed

characters

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-8

EDIT MESSAGE

$EDMSG

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

Form

Operation

Insert
OUTBLK.

%nN

Insert n
OUTBLK.

%VN

Use the value in the next word in
ARGBLKas 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.

%nO

Convert the next n binary values in
ARGBLK to signed octal and store the
results in OUTBLKi
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
OUTBLKi
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 OUTBLKi
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
OUTBLKi
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-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 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 OUTBLKi
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 OUTBLKi
insert tab
between numbers.

(Radix-50
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
a 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 OUTBLKi 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
OUTBLKi
insert tab between numbers.

Convert Radix-50 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-50 file name
strings in ARGBLK to ASCII string in
format
NAME.TYP;
convert
octal
version numbers, if present, to ASCII
and store results in OUTBLKi
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.

Directive

(file name
string
conversion)

(date conversion)

KEY:

6-11

$EDMSG

EDIT MESSAGE

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

Operation

%OZ
or
%lZ

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

%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
%SZ

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.

Directive
Z

(binary time
to ASCII
conversion)

(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 octal conversion is to be performed, the
argument block must contain the addresses of the binary bytes.

•

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

6-12

must

EDIT MESSAGE

•

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

•

1
2
3

SEDMSG

specified,

the

Radix-50 file name

= Radix-50 file name

Radix-50 file name
Radix-50 file type
5 = binary version number
4

If the binary date is to be converted, the argument block must
contain the following:
Word 1
year (last 2 digits)
Word 2
number (I - 12) of month
Word 3 = day of month (I - 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 (a - 23)
2 = minute-of-hour (a - 59)
3
second-of-minute (a - 59)
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 - 5 of the calling task.
The $EDMSG routine calls the
output data conversion routines described in Chapter 5 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
• WORD
• WORD
• WORD

3•
99 •
-37 •
137.

The output block (OUTBLK)
OUTBLK:

.BLKB 100.

The source statements
START:

MOV #OUTBLK,RO
MOV jISTRNG,Rl
MOV #ARGBLK,R2
CALL $EDMSG

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

-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 spaees 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
decimali 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

/%F5S***B.

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

The argument block (IBLK)
IBLK:

• WORD 77 •

iYEAR

. WORD 8.

i8TH MONTH (AUG)

• WORD 22 .

iDAY

• WORD 77 •

iYEAR

• WORD 9.

i9TH MONTH (SEP)

. WORD 16 .

iDAY

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 l6-SEP-77***

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

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

%5S

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 l6-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 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

$INIDM INITIALIZE DYNAMIC MEMORY
7.1

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:
in Register
• Specify,
listhead.

the

address

the

free

memory

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

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

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

INITIALIZE DYNAMIC MEMORY
REQUEST CORE BLOCK

•

Computes the total size of the free dynamic memory.

•

Sets the outputs in Register
task.

SINIOM
SROCS

° - 1 and returns to the 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 0, the address of the free memory listhead.

•

in Register 1, the size (number of bytes) of
block to be allocated, where:
Rl = a value greater than or equal
best fit allocation.
Rl

•

once

the

memory

specify

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

Include the statement
CALL $RQCB
in the source program.

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.
RO
Rl
the actual size of the allocated block (requested
size rounded to next two-word boundary.

•

Condition Code C bit = clear.

Unsuccessful allocation:
•

Condition Code C bit

set.

7-3

$RLCB
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 addresses 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 merged 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
deal location 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
their 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 MANAGEMENT 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 routines, 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 MANAGEMENT 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

$EXTSK

(none)

FNDPG

$FNDPG

(none)

GTCOS

GTCOR

$GTCOR

$EXTSK, $WRPAG

INIDM*

$INIDM

$EXTSK

INIVS

INIVM

$INIVM

$ALBLR, $GTCOR, $EXTSR,
$WRPAG

MRKPG

MRRPG

$LCKPG
$UNLPG
$WRMPG

$FNDPG
$FNDPG
$FNDPG

RDPAS

RDPAG

$RDPAG
$WRPAG

(none)

RQVCB

$RQVCB

(none)

VMUTL

$CVLOR

$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

$INIVM

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)1
the work file read
count field ($WRKRD)1
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 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: [I ,I] VMLIB/LB:ALBLK:ALSVB:ALVRT:CVRS:EXTSK:FNDPG:GTCOS
LB: [1,I]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 filet
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 ,1]VMLIB/LB:ALBLK:ALSVB:ALVRT:CVRL: EXTSK:FNDPG:GTCOR
LB: [1,I]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

$INIVM 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 exten~ion 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 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

•

= o.

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

VIRTUAL MEMORY INITIALIZATION

$INIVM

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.

Task

$INIVM

Call $SAV RG to
save task's
R3- RS

$SAVRG

I
Set new high
dynamic memory
address

$SAVRG.

Clear memory
control fields and
lists; force old
pages out of
memory

Clear RO; clear C
bit; transfer to
$SAV RG to restore
R3 - R S and return
I

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

yes
Set up new
address control
list; call $ALBLK
to allocate
I-----I~

File
marked?

$ALBLK

control list
page block

Set RO =-1

Call $ALBLK
to allocate block
for first memory
page

Mark file for
deletion after
close

$ALBLK

yes

Link memory
page to page
control list

Figure 8-1

Open disk
work file

~no

r----.~

open?

~-----~~

Set RO =-2

General Block Diagram of the $INIVM Routine

8-7

$INIVM

VIRTUAL MEMORY INITIALIZATION

The $INIVM routine calls the $SAVRG routine to save
restore registers 3 - 5 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: CLOSES $WRKPT. If the routine is successful, the C bit in
the Condition Code is cleared, and control is transferred to the
$SAVRGroutine to restore registers R3 - R5 and return to the calling
task.
If the work file is not opened successfully, the $INIVM routine sets
th& C bit in the Condition Code, sets RO = -2, and transfers to the
$SAVRG routine.
If the work file is not succ~ssfully marked for deletion, the $INIVM
routine sets the C bit 1n the Condition Code, sets RO = -1, and
transfers to the $SAVRG routine.
The $SAVRG routine restores registers R3
R5 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 deal location 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$ALBLK

•

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
request.

•

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 so, 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
$INIVM routine
$CVRL routine
$ALVRT routine

$ROCB

$EXTSK
Call $GTCOR to
request memory
block

$GTCOR
$WRPAG

Cl,ear block;
yes
set block address 14----<
in RD; return

$RLCB

Call user's
$ERMSG routine

$ERMSG

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)

ALLOCATE BLOCK
GET CORE

•

Request 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.

$ALBLK
$GTCOR

task

region

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

Get Core 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 ~llocated 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

block,

C bit = clear if the allocation was successful.
C bit = set if the allocation failed.
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
($ALBLK).
The $GTCOR routine calls the $SAVRG routine to save and
subsequently restore registers 3 - 5 of the caller.

8-11

$GTCOR GET CORE

Call $RCiCB
to request
memory block

Task
}
$ALBLK

Clear C bit;
set memory
address in RO;
return

yes

See if task can
be extended

Inhibit further
extensions

yes

Check for
unlocked pages

Call $EXTSK
to extend task

no
Set C bit; return

Call $WRPAG
to write pages
out to disk

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

yes

Delete pages
from list; link
remaining pages; I-------------t~
call $RLCB to
release page
blocks

Figure 8-3

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
b19Ck to the ~aller.
If the requested block cannot be allocated from the current free
dynamic memory, the $GTCOR routine calls the Extend Task Routine
($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

$GTCOR
EXTEND TASK $EXTSK
GET CORE

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

Extend 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

$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

8.3.4

General Block Diagram of the $EXTSK Routine

Write Page Routine ($WRPAG)

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:
work

file

address

the

subsequently

•

Sets up the
transferred.

•

Initiates the page writing operation.

•

Checks the status of the write 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.

Task
}
$GTCO R

disk

$WRPAG

page

Caller

$SAVVR

Set up disk
address for
page to be
transferred

Initiate page
writing
operation

Check status
of write
operation

yes

Call user's
$ERMSG
routine

Figure 8-5

Clear C bit;
return

$SAVVR

$ERMSG

General Block Diagram of the $WRPAG Routine

8-15

SALVRT
8.4

ALLOCATE VIRTUAL MEMORY

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

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:

•

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 userls 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 userls $ERMSG routine.

Task
}
$ALSVB

Call $SAVRG
to save
R3 - R5

Call $RQVCB
to request disk
storage block

Set memory
address of page
in RO; set disk
address of page
in R 1; transfer to
$SAVRG to
restore R3 - R5

Call user's
$ERMSG
routine

Call $ALBLK
to allocate
core page block

Save disk page
address; see if
core page block
available

yes
Update
paging/address
tables

Call $WRMPG
to flag page as
written into

Figure 8-6

Call $CVRL to
convert virtual
address to real
address

General Block Diagram of the $ALVRT Routine

8-17

$ALVRT
$ALSVB

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

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.

•

Registers 3 -

the virtual address of the allocated block.
~

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

$ALSVB

Task

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

Call $ALVRT to
allocate large
disk page block

Get virtual
address of
available small
block

Call $CVRL to
convert virtual
address to memory I---..---I~
address and read
into page

$ALVRT

Return memory
address in RO;
virtual address
in R1

Call $WRMPG
to mark page as
written into

$WRMPG

$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

$ALSVB
$RQVCB

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 address to a memory page address.

•

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

memory

The $ALSVB routine calls the Write-marked 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.

8.4.3

large

block,

necessary,

from

disk

Request Virtual Core Block Routine ($RQVCB)

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 routine with the $ALVRT
diagrammed in Figure 8-8 and described briefly below.

routine

The $RQVCB routine rounds the requested number of bytes up to the
nearest word. If the rounded value crosses 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 disk 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

$RQVCB

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 R1;
clear C bit;
return

All ocate 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

$CVLOK 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), 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 dynamic memory when called by:
•

the $CVRL routine.

•

the Lock Page Routine ($LCKPG).

•

the Unloc~ 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), 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.

8.5.1

Convert and Lock Page Routine ($CVLOK)

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

$CVLOK

To call 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:

•
•

converted memory address.
RO
Rl = virtual address.

•

Condition Code:
C bit = clear if
locked.

the

address

was

converted

and

the

page

C bit = 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

$CVLOK CONVERT AND LOCK PAGE
$CVRL CONVERT VIRTUAL TO REAL ADDRESS

Task

Call $CVRL to
convert virtual
to memory
address

$CVRL

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 Address 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
briefly 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 •

•

Convert 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

$SAVRG

Task
$ALVRT
{
$CVLOK

$CVRL

$SAVAG

Call $FNDPG
to find page

$FNDPG

Call $ALBLK
to allocate
memory page
block

$ALBLK

Call $RDPAG
to read disk
page into
memory page

Convert address;
set RO = memory
address; return

SRDPAG

Figure 8-10

General Block Diagram of the $CVRL Routine

8-25

$RDPAG
8.5.3

READ PAGE

Read Page Routine ($RDPAG)

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 Convert 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.

•

8-26

READ PAGE
FIND PAGE

Caller

$RDPAG
$FNDPG

Task
{ $CVRL

$RDPAG

$SAVVR

Initiate read
operation

Check status
of read

Set C bit;
call user's
$ERMSG
routine

$ERMSG

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

$SAVVR

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 of the $FNDPG routine with the user's task and the
page management routines is shown in Figure 8-12 and described below.
The $FNDPG routine
management routines:

called

the

following

virtual

memory

•

Convert Virtual to Real Address 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 locked 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

I~f~~~G

Caller

$UNLPG
$WRMPG

$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

8.5.5

General Block Diagram of the $FNDPG Routine

Write-marked Page Routine ($WRMPG)

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 allocated 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

$WRMPG

$SAVVR

Call $FNDPG
to find page

$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

$LCKPG

Lock Page Routine ($LCKPG)

8.5.6

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

cleared if the page was locked in memory.

C bit

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
Code is set and control is returned, via the $SAVVR routine, to the
caller.

8-31

$LCKPG LOCK PAGE
$UNLPG UNLOCK PAGE

Caller

Task
{ $CVLOK

$LCKPG

Call $FNDPG
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

8.5.7

General Block Diagram of the $LCKPG Routine

Unlock Page Routine ($UNLPG)

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

$UNLPG

The 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 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 and the C bit in
the Condition Code are 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
Code is set and control is returned, via the $SAVVR routine, to the
caller.

Task

$UNLPG

$SAVVR

Call $FNDPG
to find page

$SAVVR

$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 are summarized in
tabular format 1n this chapter.
These summaries are presented as
quick reference guides for users who are familiar with the detailed
procedures
and
requirements for using individu.al routines, as
described in preceding chapters of this manual.
Table 9-1
Register Handling Routines Summary
Routine Name/
Mnemonic

Function

Call Statement

Save All Registers
$SAVAL

Saves/restores RO - R5

JSR PC,$SAVAL

Save Registers 3 - 5
$SAVRG

Saves/restores R3 - R5

JSR R5, $SAVRG

Save Registers 0-2
$SAWR

Saves/restores RO - R2

JSR R2,$SAWR

Save Registers I - 5
$SAVRI

Saves/restores RI - R5

JSR R5,$SAVRI

9-1

SUMMARY PROCEDURES

Table 9-2
Arithmetic Routines 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 = 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 unsigned inputs and produce unsigned results.

9-2

SUMMARY PROCEDURES

Table 9-3
Input Data Conversion Routines Summary
Routine Name/
Mnemonic

Input Arguments and Call Statement

Decimal to
Binary Double
Word
.DD2CT

R3 = output address
R4 = number input characters
RS = input string address
CALL .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
CALL .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
CALL $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
CALL $COTB

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

ASCII to
Radix-50
SCATS

RO = address first input character
Rl = 0 (period is terminating
character)
Rl = 1 (period is valid character)
CALL SCATS

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

ASCII with
Blanks to
Radix-50
$CATSB

RO = address first input character
Rl = 0 (period is terminating
character)
Rl = 1 (period is valid character)
CALL $CATSB

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

Outputs

--~------------------------------------------------------~------------------------------~

9-3

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
RI = binary date
R2 = 0 (zero suppress)
R2 = nonzero (no zero suppress)
CALL $CBDAT

Converted date at output
address
RO = next available output
address
R3-RS preserved
RI-R2 destroyed

Convert Binary
To Decimal
Magnitude
$CBDMG

RO = output address
RI = 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
RI- R2 destroyed

Convert Binary
to Signed
Decimal
$CBDSG

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

Converted number at output
address
RO = next available output
address
R3-RS preserved
RI-R2 destroyed

Convert DoublePrecision
Binary to
Decimal
$CDDMG

RO = output address
= input address
= 0 (zero suppress)
= nonzero (no zero suppress)
CALL $CDDMG

Successful:
Converted number at output
address.
Unsuccessful:
String of ASCII asterisks at
output address
RO = next available output
address
R3-RS preserved
RI-R2 destroyed

Convert Binary
to Octal
Magnitude
$CBOMG

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

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

RO = output address

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

Convert Binary
to Signed
Octal
$CBOSG

Convert Binary
Byte to Octal
Magnitude
$CBTMG

Rl
R2
R2

Rl = binary number

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

Converted byte at output
address
RO = next available output
address
R3-RS preserved
RI-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 Purpose
Binary to
ASCII
$CBTA

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

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

= 0 = unsigned value

= 1 = signed value

= 0 = zero suppress
= 1 = no zero suppress
= 1, replace leading

zeroes with blanks.
= 0, do not replace

leading zeroes with
blanks.
bits 11-15: field width (value
1-32)
CALL $CBTA
Radix-50 to
ASCII
$C5TA

RO = output address
Rl = Radix-50 word
CALL $C5TA

Converted number at output
address
RO = next available output
address
R3-R5 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
$DAT

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 Conversion
$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 5, 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 Statement

Edit Message
$EDMSG

Define ASCIZ input string with
directives in the form:
tl
tnl
tVl
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
D = Binary to signed decimal conversion
E = Extended ASCII string transfer
F = Form control insertion
M = Binary to decimal magnitude
conversion, zero suppression
N = New line insertion
o = 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-precision
decimal conversion, no zero
suppression
X = File name conversion
Y = Date conversion
Z = Time conversion
< = Define fixed length byte field
> = Locate field mark
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 block
R3-RS preserved

SUMMARY PROCEDURES

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

Input Arguments and Call Statement

Outputs

Initialize
Dynamic
Memory
$INIDM

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-RS not used

Request 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

Release Core
Block
$RLCB

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

Released block
R3-RS preserved
RO unchanged
Rl-R2 destroyed

9-7

SUMMARY PROCEDURES
Table 9-7
Virtual Memory Management Routines Summary

Routine Name/
Mnemonic

Input Arguments and Call Statement

Outputs

Initialize
Virtual
Memory
$INIVM

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

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 RO-R2
destroyed

Allocate
Block
$ALBLK

R1 = 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

R1 = 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:
= 0, 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

(continued on next page)

9-8

SUMMARY PROCEDURES

Table 9-7 (Cont.)
Virtual Memory Management Routines Summary
Routine Name/
Mnemonic

Input Arguments and Call statement

Outputs

Convert and
Lock Page
$CVLOK

RI = virtual address
CALL $CVLOK

Successful:
RO = memory address
RI = virtual address
C = clear
Unsuccessful:
C = set
R2-R5 preserved

Convert Virtual
to Real Address
$CVRL

RI = virtual address
CALL $CVRL

RO = memory address
R3-RS preserved
RI unchanged
R2 destroyed

Read Page
$RDPAG

RO = page disk address
CALL $RDPAG

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

Find Page
$FNDPG

RI = page virtual address
CALL $FNDPG

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

Write-marked
Page
$WRMPG

RI = virtual address in page
CALL $WRMPG

C = clear, page write-marked
C = set, page not found
RO-R2 preserved

Lock Page
$LCKPG

RI = virtual address in page
CALL $LCKPG

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

Unlock Page
$UNLPG

Rl= virtual address in page
CALL $UNLPG

C = clear, page unlocked
C = set, page not found
RO-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-ll system
libraries.
First level entries are manual titles.
Second level entries are
functional headings indicating the types of services described in the
respective manual.
lAS EXECUTIVE REFERENCE MANUAL (VOLUMES I AND II)
Task Execution Control Directives
Informational Directives
Event-associated Directives
Trap-associated Directives
I/O Related Directives
Task Status Control Directives
IAS/RSX-llD DEVICE HANDLERS REFERENCE MANUAL
Laboratory and Industrial I/O Routines
IAS/RSX-ll 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-I

SYSTEM REFERENCE BIBLIOGRAPHY

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 "

IAS/RSX-ll
System Library Routines
Reference Manual
AA-5580A-TC

READER'S COMMENTS

NOTE:

This form is for document comments only. DIGITAL will
use comments submitted on this form at the companyts
discretion. Problems with software should be reported
on a Software Performance Report (SPR) form.
If you
require a written reply and are eligible to receive
one under SPR service, submit your comments on an SPR
form.

Did you find errors in this manual?

If so, specify by page.

Did you find this manual understandable, usable, and well-organized?
Please make suggestions for improvement.

Is there sufficient documentation on associated system programs
required for use of the software described in this manual? If not,
what material is missing and where should it be placed?

Please indicate the type of user/reader that you most nearly represent.

o Assembly language programmer

o
o
o
o

Name

Higher-level language programmer
Occasional programmer (experienced)
User with little programming experience
Student programmer
Non-programmer interested in computer concepts and capabilities
Date _________________________

Organization _______________________________________________________________
Street ______________________________________________________________________

ci ty ____________________ Sta te __________ Zip Code ________
or
Country

-------------------------------------------------------------Fold lIere------------------------------------------------------------

.----------------------------------------------- Do Not Tear - Fold lIere and Staple -----------------------------------------------

FIRST CLASS
PERMIT NO. 33
MAYNARD, MASS.
BUSINESS REPLY MAIL
NO POSTAGE STAMP NECESSARY IF MAILED IN THE UNITED STATES

Postage will be paid by:

Software Documentation
146 Main Street ML5-5/E39
Maynard, Massachusetts 01754

digital equipment corporation

Printed in U.S.A.