\documentstyle[a4,12pt]{article}
\begin{document}
\author{APM Manual pages}
\title{REGION library}
\maketitle
\parskip .1 in
\setcounter{secnumdepth}{10}
\parindent 0in
\section{Preamble}
Procedures for accessing files and parts (regions) of files and
appending data to files

\section{OPEN INPUT/OUTPUT - Open a file for stream I/O}

These routines are declared automatically for all IMP programs.

\%externalroutine OPEN INPUT (\%integer stream,\%string(255)file)
\\\%externalroutine OPEN OUTPUT(\%integer stream,\%string(255)file)

FILE is opened for IMP stream input or output respectively on stream STREAM.
It may then be read to using READSYMBOL etc. or written to using PRINTSYMBOL
etc.

The file should eventually be closed with CLOSE INPUT or CLOSE OUTPUT though
a program terminating via \%endofprogram will usually tidy up open streams.

\section{CONNECT FILE - Read a whole file into memory}

\%externalroutine CONNECT FILE \%c
(\%string(255) fname, \%integer mode, \%integername start,limit)


This routine is declared in INC:UTIL.IMP and the object is loaded at bootstrap.

The file FNAME is read into the area of memory starting at START.
The file length is returned via LIMIT. \hspace{ 0.2 in} Mode=0 for read.

\section{REGION - Accessing parts of files}

These live in UTILS:REGION, object UTILS:REGION.MOB (which must be INSTALLed)

\subsection{ACCESS FILE}
\%externalroutine access file(\%string(255)filename,\%integer mode,
\\ \hspace*{ 1.9 in} \%integername ref,size)

Opens the file and returns in SIZE the number of bytes in the file,
and in REF a token which must be passed to DEACCESS FILE, READ REGION,
and WRITE REGION. The token is in fact the address of a record (NEWed
by ACCESS FILE and DISPOSEd by DEACCESS FILE) which contains the
transaction number and the file size.
MODE=0: Read-only, MODE=1: Read-modify.

\subsection{DEACCESS FILE}

\%externalroutine deaccess file(\%integer ref)

Closes the file and throws away the token

\subsection{READ REGION}

\%externalroutine read region(\%integer ref,byte,bytes,\%bytename buffer)

Reads BYTES bytes from the file specified by REF into store at BUFFER,
starting with byte BYTE of the file (BYTE=0 means beginning of file).

\subsection{WRITE REGION}

\%externalroutine write region(\%integer ref,byte,bytes,\%bytename buffer)

Presumably writes BYTES to the file specified by REF from store at BUFFER,
starting with byte BYTE of the file.


\section{Open/Close Append - Appending to existing files}

\%specs in INC:UTIL.IMP: Object is loaded at bootstrap.

\%externalroutine OPENAPPEND(\%integer stream,\%string(255)file)
\\\%externalroutine CLOSEAPPEND

These should be used in exactly the same way as OPEN OUTPUT and CLOSE OUTPUT
but data is appended to the file rather than written from the start of the
file.

Warning: The file will grow incrementally so in the worst case will generate
one additional extent for each 512 bytes appended. This will eventually clog
the directory it lives in (which contains table entries per file and per
extent)

\vspace{.75in} view:Files.Etc printed on 09/02/89 at 17.15

\newpage
\tableofcontents
\end{document}
