.AUTOPARAGRAPH
.LEFT MARGIN 10
.RIGHT MARGIN 72
.TAB STOPS 15,20,25,30,35
.INDENT 58
9/81
.SKIP 18
.CENTER 
PRM-11 USER'S GUIDE
.SKIP
.CENTER
OMSI PASCAL INTERFACE TO RMS-11
.SKIP 10
.CENTER
Kenneth G. Tibesar
.CENTER
3M Engineering Systems and Technology Labs
.CENTER
St. Paul, Minnesota 55144
.FILL
.NO HYPHENATION
.JUSTIFY

.page
.TITLE Pascal Record Management User's Manual
.subtitle Table Of Contents
.literal 

1.0 Introduction
  1.1 PRM Design
  1.2 File Operations
  1.3 Record Operations
  1.4 RFA
  1.5 Memory Requirements

2.0 Preparing for PRM
  2.1 Pre-defined Data Structures
  2.2 Control Buffers
    2.2.1 RmsFileDesc - File Description
    2.2.2 RetRecord - Record Retrieval
    2.2.3 StoRecord - Record Storage
    2.2.4 IdxKeyDesc - Indexed Key Description
  2.3 Record Buffers
    2.3.1 Shared Buffers
    2.3.2 Non-Shared Buffers
  2.4 External Calls
  2.5 Rms-11 Initialization
  2.6 Task Build
  2.7 Pit-Falls

3.0 Detailed Description of PRM Buffers
  3.1 RmsFileDesc - File Description
  3.2 RetRecord - Record Retrieval
  3.3 StoRecord - Record Storage
  3.4 IdxKeyDesc - Indexed Key Description
  3.5 User Defined Record Buffers

4.0 Detailed Description of PRM Routines
  4.1 General Use
  4.2 File Access and Creation
  4.3 Record Retrieval and Storage

Appendix A
  PRM program example - Access an existing RMS files

Appendix B
  PRM program example - Dynamic creation of an RMS indexed file

Appendix C
  PRM example command and overlay descriptor files

Appendix D
  PRM error codes

.end literal

.page
.subtitle Preface
.literal 
PREFACE
.end literal

Record Management Services (RMS-11) is a software package written and
supported by DEC.  The package is a data management tool that supports
sequential, relative and indexed (ISAM) files.

Pascal Record Management (PRM-11) is a non-supported interface developed
by 3M Engineering and Systems Technology Labs.  PRM was developed as an
interum until the OMSI Pascal Compiler directly supports RMS-11.  

PRM was developed and tested using V1.2G of OMSI Pascal and DEC RSX-11M+
operating system.  Known problems will occur when using OMSI Pascal V1.2H
due to changes in initialization procedures.  Version 2 of OMSI Pascal
can be used only if the Version 1 switch is used.

Comments and questions concerning PRM should be directed in writting to:
.LITERAL

                  Kenneth Tibesar
                  3M Center, Bldg. 518-1
                  St. Paul, Minnesota 55144

.END LITERAL

.Chapter Introduction to PRM
.LEFT MARGIN 10
.RIGHT MARGIN 72
.TITLE Pascal Record Management User's Manual
.subtitle Introduction to PRM

PRM-11 is a set of routinnes written in OMSI Pascal with in-line MACRO-11
code to interface to RMS-11.  DEC supported high level languages interface
to RMS-11 by using key words supported by the language compiler.  The
present versions of OMSI Pascal for the PDP-11 does not support RMS-11
interface.  PRM provides the interface via a set of external procedures
that are similiar to the key words used by DEC languages.  PRM routines
are called by the user code when RMS-11 operations are required.  The
PRM routines are linked to the user code during the task build.

.hl 1 PRM Design

PRM routines use DEC supported MACRO-11 routines to perform RMS-11 operations.
RMS-11 requires attribute blocks describing the file (FAB) and record (RAB).
PRM defines fields within the attribute blocks.  This allows Pascal to
directly control the contents of the files RABs and FABs.  The contents of
the RABs and FABs are indirectly controlled by the PRM user by loading
pre-defined buffers and using one of the PRM external procedures.

User buffers required by PRM routines are allocated in the user space.
The user defines only the number of buffers required for the application.
The buffers are loaded by the PRM user to indicate file or record access
parameters.  The buffers are also used by PRM as working space.  By using
buffers allocated globally (from the heap), PRM can preserve variables
between PRM calls.

Normally, RMS-11 requires the user to reserve POOL space.  The POOL space
is used by RMS internal code as control structures known as BDB's (Buffer
Descriptor Blocks).  The POOL space has to be allocated based on the
number of simultaneously opened files.  This design would wastes user
space that cannot be reclaimed even though the file is closed.  To avoid
this loss of valuable user space, PRM dynamically allocates and deallocates
the space when required by RMS-11.  RMS-11 allows the MACRO-11 programmer
to specify a GSA (Get Space) routine. The PRM GSA routine simply calls
the Pascal Run-Time-System NEW and DISPOSE routines to manage HEAP space.
RMS-11 uses the declared GSA routine when it requires or releases space.
Space is not used until a file is opened and returned to the Pascal heap
when the file is closed.

PRM was modled after syntax used by existing DEC supported languages that
interface to RMS-11.  The following is a list of PRM and high level
language comparisons:
.list
.le; DEC - Compilers support commands that perform RMS-11 file and record
operations.  

PRM - External procedures linked to the Pascal program perform RMS-11 file
and record operations.
.le; DEC- Descriptive key words are used with RMS-11 commands to specify 
attributes of the file and record operations.

PRM - Descriptive field names are used to load records passed to the external
procedures.  The record fields specify attributes of the file or record 
operation.
.le; DEC - A completion code indicating the success of failure of each RMS
operation is made available to the user.  The completion code is available
thru the use of a reserved word.
.le; PRM - A completion code in returned with each PRM call.  The code is
the standard RMS-11 completion code.  In addition, PRM provides debugging
completion codes for the PRM user.
.end list

.hl 1 User Interface

The PRM interface to OMSI Pascal uses the Pascal internal record structure
to pass data.  Pre-defined records are included in the TYPE declaration of
the User Pascal program.  The Pascal programmer determines the operation to
be performed (open, close, get record, etc.) and loads the appropriate
record buffer.  Once loaded, the reocrd address is passed to the specific
PRM routine that performs the file or record operation.  The PRM routines 
load the RMS attribute blocks (RAB and/or FAB) with the control codes
necessary to satisfy the user request.  If data is to be stored or
retrieved, the User Pascal program is also required to pass the address
of a data buffer.  

In addition to control and data buffer addresses, an address of a 
status buffer is required with all PRM calls.  The status buffer is
loaded with a completion code.  The code is a standard MACRO-11 RMS
success/error code (refer to RMS-11 User's Manual, Appendix B).  In
additionn PRM will return debugging error codes for the PRM user.  PRM
error codes are only generated due to PRM user procedural error.  Refer
to Appendix D of this document.

The user should check
the completion code following each PRM call.  If the file is not opened
properly, no record operations should be performed.  If the user 
continues after an error in a file open or creation, PRM will catch
the error.  All record operations on an improperly opened  or created
file are prohibited.

.hl 1 File Operations

There are four file operation primitives provided.  A buffer of TYPE
RmsFileDesc must be allocated by the user for each simultaneously open file.  
Once the file is open,
the contents of this buffer provides the file attributes blocks
(FAB and RAB) used to access the file.
All file operations performed require the user to pass the address
of the RmsFileDesc buffer to the PRM routine.

The file opeation primitives are:
.LIST 
.LE; PRMClo - Closes an Open RMS file
.le; PrmCre - Creates an Rms File.  If the file to be created is
an indexed (ISAM) file, the PRMKey routine must
be called a minimum of one time prior to this call.
.le; PRMKey - Defines the keys of a indexed file prior to file creation.
.LE; PRMOpe - Opens an existing RMS file
.END LIST

PRM ensures that the user knows the file record size of the file specified
for during PRMOpe.  The open requires the user to specify the record size
of the file.  If the actual file record size and the user specified record
size to not match, any activity on the file is prohibited.

.hl 1 Record Operations

There are four record operation primitives provided by the PRM interface.
A buffer of TYPE RetRecord is provided for retrieving records from a file
and a buffer of TYPE StoRecord is provided for storing records.  The buffers
contain the necessary parameters for access to the file. 

Before the record operations are performed, PRM will check to see if the
file to be accessed is properly opened.  Record operations performed on
an improperly opened file will produce unpredictable results.  
Any record operation request performed on an RMS file that has not been
successfully opened by PRMOpe will be rejected by PRMRet and PRMSto.

The record operation primitives are:
.LIST 1
.le; PRMDel - delete a record, preceded by a successful PRMRet
.le; PRMFre - unlock the bucket locked by the previous PRMRet operation.  
.le; PRMRet - retrieve a record from an open file (GET and FIND)
.le; PRMSto - store a record in an open file (PUT and UPDATE)
.END LIST

.HL 1 RFA (Record File's Address)

The PRM interface provides access to file records via RFA's.  An RFA is a
unique number assigned to each record of RMS type files.  The use of RFA
provides direct access to a record by-passing the record processing
software.  Use of an RFA will also provide random access to RMS Sequential
files that are stored on random access devices (disks).

An example of RFA access
usage would be an application that searches the
file for records with specific conditions.  The entire file is searched and
records with the specified conditions are "remembered" for future reference.  

When the entire file has been searched, the processing begins 
randomly accessing the file
for the specified records.  If during the initial search, the RFA is stored,
the RFA can be used to randomly access the record.  The storing of the RFA
may be an alternative to storing the entire record (or key) in memory for
rapid access to the data after the initial search.  Storing the entire record
(or key) may not be possible.

The previous senario describes the use of DataTrieve when 
forming a "collection".

.note
The RFA used to define a record is unique and can be stored in a file for
access to records for subsequent executions of an application.  However,
the RFA is only valid for the life of the file.  Once the file has been
reorganized with a utility such as CNV or IFL (or an application program),
the RFA for a given record is no longer valid.
.end note

RFA can be used to retrieve records only.  When you store a new record,
PRM returns the RFA generated by RMS via
the StoRecord buffer.  When you retrieve a record
will normal access, the record RFA is returned by PRMRet in the RetRecord.
When you retrieve a record by RFA,
you specify search := RFA in RetRecord buffer and load the 
RFA in KeyNum in RetRecord buffer.  The example in the appendix shows use
of RFA's to randomly retrieve records from a sequential file.

.hl 1 Memory Requirements

PRM code requires approximately 1KW if all routines are used.  The space
used would be required by any interface to RMS-11 including MACRO-11 or
any high level language.  PRM is designed so only the required calls are
included.

Dynamic memory space is managed by the Pascal run-time system.  PRM defines
a GSA routine (refer to paragraph 1.1) to efficiently control allocation
and deallocation of Pascal heap space.

RMS-11 code requires approximately 24KW is all file organizations with all
RMS-11 file and record operations supported.  At present, PRM requests the
task builder to link ALL RMS-11 code to a PRM task.  If the RMS-11
Resident Library is not used, the user space remaining is serverly limited.
If not using RMS-11 Resident Library support, modify the PRMIni routine
and/or use DEC supplied ODL (overlay descriptor language) files.  Refer to
paragraphs 2.5 and/or 2.6 for detail.

.chapter Preparing for PRM
.LEFT MARGIN 10
.RIGHT MARGIN 72
.TITLE Pascal Record Management User's Manual
.subtitle Preparing for PRM
.HL 1 Pre-defined Data Structures
.hl 1 Control buffers
.hl 1 Record buffers
.hl 2 Non-shared record buffers
.hl 2 Shared record buffers
.hl 1 Prm External Calls
.hl 1 User Space Optimization
.hl 1 PRM Pit-Falls
.chapter Detailed Description of PRM Buffers
.LEFT MARGIN 10
.RIGHT MARGIN 72
.TITLE Pascal Record Management User's Manual
.subtitle Detailed Description of PRM Buffers
.hl 1 RmsFileDesc - File Description
.hl 1 RetRecord - Record Retrieval
.hl 1 StoRecord - Record Storage
.hl 1 IdxKeyDesc - Indexed Key Description
.hl 1 User defined 
.chapter Detailed Description of PRM Routines
.LEFT MARGIN 10
.RIGHT MARGIN 72
.TITLE Pascal Record Management User's Manual
.subtitle Detailed Description of PRM Routines
.hl 1 General Use
.hl 1 File Access and Creation
.hl 1 Record Access and Storage