August 16, 1982
APPLICATION PROGRAMMERS' GUIDE
ROUGH DRAFT
S D O S
APPLICATION PROGRAMMERS' GUIDE
COPYRIGHT (C) 1978 SOFTWARE DYNAMICS
4th Printing
NOTICE
------
This manual describes Software Dynamics Operating System (SDOS)
Version 1.1. Software Dynamics has carefully checked the
information given in this manual, and it is believed to be
entirely reliable. However, no responsibility is assumed for
inaccuracies.
SD reserves the right to change the specifications without
notice.
**********************************************************************
** This manual describes software which is a proprietary product **
** of Software Dynamics (SD). SD software is licensed for use on a **
** single copy per computer basis, and is covered by U.S copyright **
** laws. Unless a written exception is obtained from SD, the soft- **
** ware must be used only on the single computer whose unique, SD- **
** assigned serial number matches that for which the software was **
** purchased. Copying the software for any purpose other than **
** archival storage, or use of the software on other than the as- **
** signed serial numbered CPU is strictly prohibited. SD assumes **
** no liability regarding the use of the software. **
** Certain software programs and datafiles are delivered for use **
** in an encrypted format. The content of such programs and data **
** are considered to be a trade secret of SD. Attempts or suc- **
** cess at breaking the encryption, publication of the results of **
** such attempts or successes, or copying, storage or use of such a **
** file in clear text form will be treated as theft of a trade sec- **
** ret, and prosecuted as such. **
** POSSESSION OR USE OF THIS MANUAL OR THE SOFTWARE IT DESCRIBES **
** CONSTITUTES AGREEMENT BY THE USER TO THESE TERMS. **
**********************************************************************
This manual and the software it describes are the copyrighted
property of Software Dynamics.
1.1
SDOS APPLICATION PROGRAMMERS' GUIDE
INTRODUCTION
This manual gives detailed information needed by programmers
building programs to operate under SDOS 1.1. The reader should be
familiar with SDOS concepts; the SDOS User's Guide provides the
appropriate background.
This document presumes some familiarity on the part of the reader
with assembly language coding for M6800, M6801 and M6809
microprocessors. This knowledge is needed to understand fully the
implications of the SDOS System Call (SYSCALL) interface and the
rules about error propagation. Practical use of SDOS does not
generally require assembly assembly language programming, as most
programming is done in SD BASIC, which provides statements for
performing SDOS System Calls.
This document covers three main areas:
SDOS SYSCALL structure and assembly language interface
Device Independent I/O - Concepts and device specific
descriptions
SDOS File System Structure
1.2
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION I: DEVICE-INDEPENDENT I/O
DEVICE-INDEPENDENT I/O
SDOS allows user programs to view all disk files and I/O devices
as being fundamentally the same, i.e., if one can perform an
operation on a device of type x (say, LPT:), one can generally
perform that same operation on a different device of type y.
Since disk files and devices are treated essentially identical,
we will use file sometimes to mean device.
In this section, a conceptual model of how files/devices should
act is presented (later sections describe in detail the system
calls used to implement this model). SDOS is designed in such a
way that disk files conform to this model very closely;
exceptions will be noted later. Real devices such as line
printers, CRT's, Digital-to-Analog converters, etc., are made to
emulate this model as closely as possible via a device driver
routine in the I/O package; the degree of closeness depends
entirely on this driver. In many cases, it is not practical or
appropriate for a device to match the desired model; this means
that there are device-dependent (actually, driver-dependent)
limitations on this device independence.
SDOS implements files for the purpose of storing and retrieving
data. A file is assumed to consist of a sequential set of 8 bit
data bytes, with the first byte being numbered zero, the second
being number 1, the nth being numbered n-1. Each file has a
size, which is equal to the number of bytes of data stored in the
file. The data in a file can be read or written sequentially in
variable-size blocks. If new data needs to be added to the end of
a file, the file can be automatically extended. Commands exist to
allow a file to be positioned to a specified byte position in
preparation for a later read or write operation, thus providing
random access. Data can be read or written in pure binary, or in
ASCII (text) format.
A device is (usually) a physical piece of hardware capable of
retrieving and storing data, converting data to/from printed
form, etc. (some devices, such as the CLOCK:, are almost purely
software). In many cases a device is treated as a file by SDOS.
Some devices can actually store many separate data files (such as
a disk device).
User programs communicate with files via mechanisms called "I/O
channels". A channel remembers which file is being manipulated,
and where in the file that the next data transfer should take
place. Each user can have several I/O channels; typical SDOS
systems allow eight I/O channels per user. I/O channels for a
user are given numbers 0 to 255 maximum.
Virtually all operations on a file must be performed in
conjunction with an I/O channel. An initial connection is
established between a user-program specified I/O channel and a
particular file by use of a SYSCALL:OPEN (or SYSCALL:CREATE).
COPYRIGHT (C) 1978 1 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION I: DEVICE-INDEPENDENT I/O
All further operations on that file must specify the operation
desired, and the I/O channel number associated with a file. Note
that a particular file may be open on several I/O channels, thus
causing interactions between what appear to be independent
operations. The association between a channel and a file is
broken with a SYSCALL:CLOSE operation; a channel on which this
operation is the most recently executed valid operation is said
to be CLOSED. No operations except OPEN or CREATE are valid on a
closed I/O channel.
The I/O channel has associated with it several pieces of
information: whether that channel is open or closed; the
particular device driver which is responsible for that file;
information selecting which file on that device is to be used;
data selecting a position within that file; and a column count
(next print position on a real or simulated printing device).
When a file is first opened, the position is reset to zero
(beginning of the file). Each read or write operation on an I/O
channel advances the position for that channel by the amount of
data read/written. An End Of File condition is said to have
occurred whenever the file position on a particular channel is
equal or larger than the file size (in bytes). Note that two I/O
channels open to the same file are not necessarily positioned to
the same place within that file.
A column count is maintained for the purpose of "tabbing" (a text
concept). This column count is zeroed whenever binary data
(non-text) is read or written to a file, and adjusted to reflect
the position along an imaginary typewriter line whenever textual
data is copied to or from a file.
Operations prformed on files are done via SDOS System Calls
(SYSCALLs). SYSCALLs specify an operation, a Write Buffer
(containing data going to a file or to SDOS), a Reply Buffer
(where data or status from SDOS is returned), a channel number
and/or operation subcode, and a reply length (RPLEN).
COPYRIGHT (C) 1978 2 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION I: DEVICE-INDEPENDENT I/O
Operations defined on files include, but are not limited to:
OPEN, CREATE, CLOSE, DELETE, RENAME, READA, READB, WRITEA,
WRITEB, CONTROL, STATUS, POSITION, GETEOF, GETCOLCNT
Other operations are device-driver specific.
OPEN is intended to associate an I/O channel with a file (device)
that already exists, for the purpose of reading (or
updating) data in that file. Data-input only devices such as
paper tape readers must be OPENed in order to read data.
All devices can be OPENed so that the device type is easily
read without knowing the kind of device being OPENed.
CREATE is intended to associate a file or device with an I/O
channel which is to be used whenever an entirely new stream
of data is to be written or stored. In particular, when a
new disk file is needed, or data sent to an output-only
device (such as a line printer) a CREATE should be
performed. Some devices, like CRT's, which are both input
and output, can be either OPENed or CREATEd.
CLOSE is used to break the association between a file and an I/O
channel, and to cause the driver for the device on which
that file resides to finish any operations on that file.
DELETE is used to delete (disk) files from devices that store
multiple named files. Devices cannot be deleted. Once a
file is deleted, it cannot be OPENed and its contents are
permanently lost.
RENAME is used to change the name of a disk file, and is illegal
when directed specifically at a device.
READA and WRITEA are used to read and write ASCII (textual) data.
This is used to read data from consoles, print on line
printers, etc. If a file has no more room for new data
written, then the file is automatically expanded. A channel
number must be given to select the desired file.
READB and WRITEB are used to read and write binary data to and
from devices (data stored in a form convenient for the
computer). An I/O channel number is required to select the
desired file. Some devices, like Digital to Analog
converters, can only perform Write Binary.
CONTROL operations are used to cause device-specific operations
that do not fit into the above types of operations. Typical
control operations are GETTYP (get device type), POSITION,
DUMP BUFFERS, etc.
STATUS operations are used to read device or file specific data.
Typical status data is DEVICE TYPE, FILESIZE, EOF flag and
COLCNT.
COPYRIGHT (C) 1978 3 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION I: DEVICE-INDEPENDENT I/O
POSITION is used to change the place in the file that the next
read or write will start transferring data to or from.
POSITION affects an I/O channel, not the file itself, so
several I/O channels may be positioned to different points
in the same file. A file can be positioned anywhere past
the last data byte; this is used to expand a file. Although
POSITION operations can be performed independently of read
or write operations, it is generally more efficient to
perform both in the same step; to allow this, an "implied
position" operation can be added to read and write
operations.
GETEOF is used to determine if the position of a particular file
is at or past the file size (i.e., there is no more data to
read).
GETCOLCNT is used to read back the simulated print head position
of an ASCII text file (or an actual print head position for
a line printer, etc.). This is useful when a tabular
display is desired. Like the file position, this value is
I/O channel dependent.
COPYRIGHT (C) 1978 4 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION II: DEVICE DRIVERS
DEVICE DRIVER CHARACTERISTICS
This section describes the actual characteristics of the device
drivers, and how operations on these drivers differ from an
"ideal" device (as described under DEVICE-INDEPENDENT I/O).
These characteristics are observable directly by the assembly
language programmer via "Syscalls". Many features of the device
drivers may be masked by a high level language such as BASIC; to
use these features, an escape to assembly language may be
required.
COPYRIGHT (C) 1978 5 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION II: DEVICE DRIVERS
DISK File Driver
Disk files under SDOS implement virtually all aspects of general
file handling as described under Device-Independent I/O. This
section details exactly the operations implemented by the SDOS
Disk File Driver.
An SDOS disk file can physically contain as few as zero data
bytes, and as many as the remaining free space after an
SDOSDISKINIT. SDOS keeps track of disk file sizes accurate to
the byte. Apparent file size may be much larger than the
actually allocated disk space; such a file is said to be
"sparse".
Disk files may be allocated "dense"ly or "sparse"ly. A dense
file is one in which data clusters are allocated for each data
byte whose position is less than the file size. A sparse file
may have a position (with a smaller value than the file size) for
which no data cluster is allocated (data read from this area of
the file appears as zeroes).
An OPEN is used to open a disk file (that must already exist) for
reading and/or update. If the file does not exist, an error will
occur. A CREATE will CREATE a new disk file which will supersede
the old version of the file when the new file is closed. The new
file will contain zero data bytes after creation. A new file
cannot be created if the old file is write protected, or a new
file by that name is being created.
Any OPEN or CREATE that specifies a filename that does not
contain an explicit device identifier will be automatically
assumed to be a disk file on the default disk (DISK:). Also, any
filename that is prefixed by a disk device name, and does not
consist solely of the device name is assumed to be the name of a
disk file on the specified disk.
For the form of disk file names, see the section on DEVICE and
DISK FILE NAMES. Disk file names may include a parenthesized
integer; this integer is used by CREATE to allocate enough disk
space at file creation time to contain the number of data bytes
specified by the integer. This has two advantages: first, it
decreases the amount of time needed to allocate the space to the
file (it is cheaper to allocate all at once than to allocate
several little pieces when SDOS discovers it needs them) and it
increases the probability the allocation of the file on the disk
is contiguous, which decreases random access time to the file. No
error is given if there is not enough disk space to satisfy the
request. OPEN will parse but ignore the size.
If CREATE is used to make a new disk file, and there is an old
file by the same name, the old file must not be delete or write
protected or an error will occur and the new file will not be
created (nor will the channel be opened). Also, no file by that
name may be CREATEd simultaneously (i.e., in psuedo-BASIC,
COPYRIGHT (C) 1978 6 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION II: DEVICE DRIVERS
CREATE #1,"X"
CREATE #2,"X"
will result in an error). Otherwise, the new file is created,
and the channel is opened. As long as the newly created file is
still open on the channel on which it was created, that new file
is in the state of "being CREATEd". If an old file with the same
name does exist, an OPEN SYSCALL executed after the CREATE,
looking for the same file, will open the old file. If the system
crashes before the new file is closed, the old file will be
unaffected in any way. Even after the new file is closed,
channels still open to the old file will not notice any
difference. When the last channel OPEN to the old file is closed,
the space for the old file is returned to free disk space.
Example:
TIME OPERATION ACTION
1 OPEN #1, "ABC" Opens old ABC
2 CREATE #2, "ABC" CREATEs a replacement
3 OPEN #3, "ABC" Opens old ABC
4 CLOSE #2, "ABC" Marks old verson of ABC
as deleted
5 OPEN #4, "ABC" Opens file generated at
time 2
6 CLOSE #1,#3 Deletes old ABC
CLOSEing a disk file causes changes to the file size, protection,
and other characteristics to be updated on the disk. IF THE
SYSTEM CRASHES WHILE THE FILE IS OPEN, THESE CHANGES ARE LOST
(NOT RECORDED IN THE DIRECTORY). If the disk file is newly
created, and is not replacing another by the same name, closing
will make its name appear in the directory. If the file is newly
created, and it is a replacement for a file that already exists
(i.e., one by the same name), then the new file will replace the
old in the directory, and the disk space allocated to the old
file will be returned to free space as soon as no other I/O
channels remain open to the old version of the file. Disk space
allocated to a file beyond the file size will be returned to the
free disk space pool when a file is closed.
RENAME is used to change the name of a disk file. RENAMEing a
disk file to its own name is legal, and can speed up later OPENs
of that file since a rename causes the file name to be re-hashed
into the directory. Refer to hash-lookup description of files.
A disk file cannot be renamed if it is write protected, or a file
by that name already exists, or a new file by that name is being
created.
COPYRIGHT (C) 1978 7 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION II: DEVICE DRIVERS
DELETE is used to free the space being used by a disk file and
remove the filename from the directory. A file cannot be deleted
if it is delete or write protected, or if a new version of the
file is being created.
READA performs exactly as specified by SYSCALL:READA. READAing
through a large, sparse portion of a file may take an excessive
amount of time due to the automatic suppression of all the zero
bytes found in the sparse area. WRITEA, WRITEB, and READB match
the SYSCALLs exactly. If an error occurs during a read or write,
the file position may not be advanced properly.
CONTROL operations available on disk files are the following:
CC:POSITION
Used to set file position before a read or write operation.
See also SYSCALL:WRITEx and SYSCALL:READx.
CC:DUMPBUFFERS
Forces all data related to the file back to the disk media,
so it is recorded permanently in case of a later crash.
CC:SETFILEDATE
Sets the creation/update date of the file. The date supplied
must be in the same format as returned by a SYSCALL:READB to
the CLOCK: device. Note that the file date is automatically
updated whenever a WRITE or CC:SETFILESIZE operation is
applied to a file.
CC:SETFILEPROT
Sets the file protection byte to the byte supplied. See
DIRECTORY.SYS for structure of file protection byte. If the
BACKUP protection bit is set, it will be cleared if any
RENAME, CC:SETFILESIZE, or WRITE operation occurs. If the
DELETE protection bit is set, the operations RENAME, DELETE,
WRITE and CC:SETFILESIZE will not be allowed.
CC:SETFILESIZE
Sets the file size to the current file position. This
operation can be used to extend a file (the extension will
be sparse until written) or to truncate a file (data written
beyond the file position given by the file size will become
inaccessible, and data clusters that were allocated beyond
that point will be returned to the pool of free clusters
when the file is closed).
CC:POSITIONTOEND
Sets the file position equal to the file size; has the same
effect as as a CC:POSITION applied to the result of an
SC:GETFILESIZE. Generally used when extending a file is
desired.
COPYRIGHT (C) 1978 8 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION II: DEVICE DRIVERS
STATUSes obtainable from a disk file are:
SC:GETPOS
Read position of file.
SC:GETCOL
Get file column number. This value is zeroed by a
CC:POSITION or READB/WRITEB and adjusted as data bytes are
read or written in ASCII mode. The disk file driver advances
the column count by one for any visible character
read/written; decrements by one if ASCII:BS is encountered;
zeros the column count if ASCII:CR is encountered; advances
the column count to the next multiple of 8 if ASCII:HT is
found; and leaves the column count alone for all other
codes. The value of the column count at a particular point
in a file thus depends on the last operation of a file; it
is intended only for use with sequential ASCII reads and
writes.
SC:GETEOF
Returns EOF hit flag. EOF is set if positioned at or past
file size. EOF also set when last byte of file is read or
overwritten, or file is extended. EOF is reset when file is
positioned with a positioning value less than the file size.
SC:GETTYPE
Returns device type of DVTYP.FILE. See SDOSUSERDEFS.ASM.
All devices (drivers) are able to return a device type.
SC:GETFILESIZE
Returns the position of the last data byte written to the
file, plus 1. If file has no data written in it, returns
zero.
SC:GETPARAMS
Returns data about the file, such as sector size in bytes,
and the cluster size.
SC:GETFILEDATE
Returns the creation/update date of the file in the standard
system date format (same format as a SYSCALL:READB would
return from the CLOCK:). device.
SC:GETFILEPROT
Returns the protection byte currently associated with the
file. See DIRECTORY.SYS description for format of protection
byte.
COPYRIGHT (C) 1978 9 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION II: DEVICE DRIVERS
No other status is obtainable from a disk file.
SDOS will allocate data clusters to a file automatically whenever
a write request to a non-allocated part of a file occurs (it does
not allocate from the current end of file up to the point of the
write; it simply leaves that part of the file sparse). A cluster
allocated in a formerly sparse part of a file is automatically
zeroed to preserve the "zero" property of the part not modified.
SDOS attempts to allocate data clusters contiguously (with
respect to Logical Cluster Numbers) to minimize scattering of the
file over a disk and to minimize sequential processing time. If
absolutely contiguous allocation is not possible, SDOS allocates
the closest free LCN that starts a contiguous block of
BOOT:MIDALLOC free clusters.
The SDOS disk file driver keeps track of OPENed (CREATEd) files
via File Control Blocks. FCBs are in one-to-one correspondence
with open files (not channels), and contain what amounts to a
DIRECTORY.SYS entry. In particular, the FCB holds the amount of
disk space allocated to a file and its apparent size. If a file
is extended on one channel, the extension will be apparent
immediately on a different channel on which that file is also
open because of the shared FCB.
Disk sectors are kept in a pool of sectors to minimize disk reads
of frequently accessed data. Data written into a file will be
immediately available through another I/O channel on which that
file is open because the (modified) disk sector in the pool is
shared. Modified sectors in the pool are written back to the
disk as space is required to bring in another disk sector
according to a Least Recently Used discipline. The oldest sector
on the queue will be written back if its disk is free.
These side effects of the FCBs and the disk sector buffer pool
are subtle but desirable because it is appropriate that different
programs be able to share a file and its contents exactly as it
is in any instant in time. Many disk operating systems do not
provide this exact sharing capability, and consequently make it
hard to build a set of programs that interact through a common
data base.
SDOS optimizes sequential I/O to disk files via "read-ahead".
Whenever data from a particular sector of a disk file is fetched,
SDOS pre-reads the next sector of that disk file into the sector
pool. The read-ahead happens in parallel with processing of data
from the first sector. This scheme decreases sequential file
processing time, and lowers the cost of reading records that span
sector boundaries to an acceptable level.
COPYRIGHT (C) 1978 10 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION II: DEVICE DRIVERS
DISK Device Driver
The SDOS disk device driver allows access to the entire contents
of a disk as though it were a single, large file. This facility
is generally only used by utility programs to initialize, check
out, and repair the file structure on a disk, but it may also be
used to squeeze out the last ounce of available disk space, to
cut down access time to a large file, or to read/write disks
compatible with the drive but intended for other disk operating
systems.
Disk device drivers may also be used to perform operations on the
device itself, such as to dismount a disk.
A disk device driver is OPENed when SDOS is asked to OPEN a file
whose name consists only of a disk name. (Writes to the device
are illegal until a CC:UNLOCKDISK call is made to enable this;
this protects the file structure against damage from casual
programs since they typically don't issue this call.)
A disk device which has been DISMOUNTed recently will have a Map
Algorithm of :0001. If the disk device is already mounted (i.e.,
has been used for disk file operations), then the map algorithm
will be that given by the BOOT.SYS file on the disk.
The disk device driver treats CREATE calls exactly like an OPEN.
CLOSEing a disk device simply disassociates the I/O channel
number, and otherwise does nothing.
RENAME and DELETE operations directed to a disk device will cause
an error.
READA and READB act as described under SYSCALLs; the contents of
the disk are treated as a single, large stream of bytes. WRITEA
and WRITEB act as described (once enabled by CC:UNLOCKDISK),
however, a disk device cannot be "extended" when more space is
needed, so writing off the "end" of the disk device will cause an
End of File error, and the written data will be lost.
Access to sectors may be obtained by positioning a disk device to
a byte position which is a multiple of the sector size for that
disk.
COPYRIGHT (C) 1978 11 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION II: DEVICE DRIVERS
Disk device drivers support the following CONTROL operations:
CC:POSITION
To position for later reads/writes.
CC:DUMPBUFFERS
This control operation will cause all modified sectors
belonging to the disk to be written back to it. It will
also cause information changed in FCBs of files open on that
disk to be written back. Information in FCBs for newly
created but not yet closed files is NOT written back to the
disk. This is not a substitute for a DISMOUNT control
operation. No parameters are needed.
CC:UNLOCKDISK
This enables WRITEA and WRITEB to work properly on a disk
device. If CC:UNLOCKDISK is not issued after OPENing a
disk, and prior to a write, a "disk is software write
protected" error will occur. Requiring this control
operation to write on the disk device prevents accidental
writing to a disk device. CLOSEing the disk device
re-enables the write protection. No parameters are needed.
CC:DISMOUNTDISK
This operation is used to make SDOS let go of a disk
entirely so it may be removed from the drive. An implied
DUMPBUFFERS occurs. If there are any (new or old) disk
files OPEN on that disk, an error will occur and the
dismount operation will not take place (one should
repeatedly issue dismounts until no errors are detected; a
disk I/O fault on a dismount will probably require
SDOSDISKVALIDATE to repair the disk). The disk I/O driver
will be called so that it may physically eject the disk or
perform other needed cleanup. A successful dismount also
turns off the FORMAT mode switch in the disk sector I/O
driver. The map algorithm is set to :0001 if the dismount
succeeds.
CC:SETMAPALGORITHM
This allows the 16 bit Map Algorithm for the disk to be
changed. An implied CC:DUMPBUFFERS occurs first; if there
are any disk files OPEN on that disk, an error will occur.
If any error occurs, the map algorithm will not be changed.
The map algorithm is passed in the WRBUF of the SYSCALL
block.
CC:FORMAT
CC:FORMAT is used to switch into "blind write" mode,
intended for disk formatting purposes. See Disk I/O
drivers. This operation may not be available on all disk
devices.
COPYRIGHT (C) 1978 12 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION II: DEVICE DRIVERS
Any other CONTROL code is simply passed by the SDOS Disk Device
Driver to the Disk Sector I/O driver for its use.
STATUS information obtainable from a disk device is the
following:
SC:GETPOS
As described under SYSCALLs
SC:GETCOL
As described under SYSCALLs
SC:GETEOF
As described under SYSCALLs
SC:GETPARAMS
Returns NBPS (number of bytes per sector), NSPT (number of
sectors per track), NTPC (number of tracks per cylinder),
and NCYL (number of cylinders) each as 2 byte values. See
SDOSUSERDEFS.ASM for details on format of result.
SC:GETFILESIZE
Returns the size of the disk in bytes; equal to
NBPS*NSPT*NTPC*NCYL (the product of the sector size in
bytes, and the number of sectors on the disk).
SC:GETTYPE
Returns DVTYP.DISK
SC:GETLASTBADLSN
Returns the Logical Sector Number of the disk sector which
last caused a Seek, Read or Write error. The LSN is
returned as 3 bytes; an LSN of :FFFFFF means "no bad LSN".
Executing SC:GETLASTBADLSN, CC:DISMOUNT, or
CC:SETMAPALGORITHM causes the value to be reset "to no bad
LSN". This STATUS is intended primarily for use by
SDOSDISKVALIDATE.
SC:GETERRORSTATS
Returns error statistics collected by the disk driver
selected. Such error statistics record counts and disk
controller status after each failed attempt by the driver to
perform a seek, read or write operation, and the the LSN of
the sector involved when the failed attempt last occurred.
Since the disk drivers retry failed attempts, nonzero error
statistics can occur and yet the system will still function
without error; such errors are known as "soft" errors and
are only an indication that some difficulty may be present.
Executing SC:GETERRORSTATS, CC:DISMOUNT or
CC:SETMAPALGORITHM causes the value to be reset "to no bad
LSN". This STATUS is intended primarily meant for display
by the DISMOUNT command.
COPYRIGHT (C) 1978 13 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION II: DEVICE DRIVERS
VIRTUAL TERMINAL DRIVER
(CONSOLE:, LPT: and Other ASCII-Oriented Serial Devices)
This section describes SDVT11C, known as the "Virtual Terminal
Driver". The Virtual Terminal driver is intended to allow an
applications program to operate with the majority of
display-oriented display units (terminals), without knowing
physical terminal characteristics. Inasmuch as printer devices
and terminals have a great deal in common, with respect to
output, the secondary intent of the VT driver is to give the
application the same uniform view of printer devices.
This is accomplished by defining a set of display-oriented
operations for an imaginary (virtual) terminal. The application
controls the terminal with this set of operations, giving no
regard to the type of physical terminal which may be ultimately
used. At time of program execution, the operations commanded by
the application are mapped into equivalent operations which the
physical terminal can perform.
In the event that an applications programmer desires to
explicitly reference a feature peculiar to a particular terminal,
he may use installation-dependent CONTROL or STATUS calls, or the
binary operations READB and WRITEB to bypass the general nature
of the VT driver. In so doing, however, that program becomes tied
to a particular terminal and is no longer portable to all
terminals serviced by the VT driver.
The VT driver provides keyboard entry, line input editing, and
text display functions. For CRTs, the VT driver also provides a
standard method of dealing with cursor positioning, data entry
via fields, and various screen attributes (denoted as "Coloring"
in this document) thus making display-oriented applications
portable over a wide variety of terminals.
For each virtual terminal device, the VT driver presents an
indefinitely long input or output byte stream to the application.
The path of input, from typist to application, travels through
several territories, before reaching its destination. Keystrokes
are first collected in a type-ahead buffer. When a request for
data is made (via a READA or READB, for instance), characters are
removed from the type-ahead buffer, in the order received, and
assembled in the input line buffer. Characters are moved from
the type-ahead buffer to the input line buffer, up to and
including the character which terminates the buffer filling
process. All subsequent data requests are satisfied from this
line buffer, until it has been exhausted; then, the type-ahead
buffer is again referenced. If the type-ahead buffer is empty,
then input is taken from the keyboard, a keystroke at a time. The
type of the last data request (READA, READB, etc.) determines how
the type-ahead buffer is filled. If the binary mode has been
selected (the last request was a READB), then all keystrokes are
faithfully stored in the type-ahead buffer. On the other hand,
if the ASCII mode has been selected (the last request was a READA
COPYRIGHT (C) 1978 14 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION II: DEVICE DRIVERS
or CC:ACTIVATIONCK control call), the parity bit is stripped from
all characters; certain control characters are assigned special
meaning (see Control Characters in this section) and are not
stored in the type-ahead buffer. Editing of the input line is
performed at the time of character transfer from the type-ahead
buffer to the input line buffer: if a READA or a CC:ACTIVATIONCK
control call initiated the transfer, then the input line buffer
is filled in ASCII mode and line editing is performed; otherwise,
the data is transparently copied through the input line buffer to
the RDBUF specified by the request. When ASCII mode keystrokes
are being stored in the type-ahead buffer, switch requests, such
as ^A, ^C, ^S, and ^P (to name a few), are serviced immediately,
and are not retained in the type-ahead buffer.
Associated with each virtual terminal device is a "Device Profile
Block". The DPB customizes the terminal to operate with specific
manufacturers' devices so that standard SDOS operations are
converted to equivalent device-specific operations. This allows
application programs to position cursors, "color" the screen or
screen regions, or update and erase the screen without knowing
the specific device type. A system command, SDOSSET, can be used
to change which device profile is in use; some profiles are
"malleable"; i.e., changeable, so even devices with properties
not handled by standard DPBs in a system can be accommodated.
There are also special control calls to allow an application to
select or modify particular profiles.
A terminal may be OPENed or CREATEd, using the device name
"CONSOLE:", "PORT1:", "PORT2:", etc.; a printer to "LPT:",
"LINEPRINTER:", etc. Doing an OPEN or CREATE sets the ASCII
activation set to <CR> only, sets the tabs to 8, 16, 24 .... up
to 132, performs CC:ECHO and CC:KILLENABLE control calls, and
sets the background color to "black" (see CC:BACKGROUND). CREATEs
to non-ready devices are aborted with a "Device Not Ready" or
"Printer Not Ready", depending on whether the device was a
console or printer, respectively; this prevents applications from
outputting data to un-ready devices in a way which is convenient
to test. A terminal/printer may be open on several channels
provided that all channels belong to the same task; output
display by the terminal is exactly what would be seen if the I/O
requests had been all directed to one channel in the same order.
CLOSE disassociates the I/O channel from the driver. For
printers, if part of a line has been printed, the VT driver will
complete the line by effectively WRITEAing ASCII:CR; if a partial
page has been printed, it will finish the page by effectively
WRITEAing ASCII:FF, thus assuring that each use of a printer
leaves the paper aligned at top of form for the next use. CLOSE
finally does an implied CC:DUMPBUFFERS, and gives an error if the
device times out.
RENAME and DELETE operations are illegal.
COPYRIGHT (C) 1978 15 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION II: DEVICE DRIVERS
READA and WRITEA are the normal I/O modes used with the terminal,
and match the SYSCALL specification. A READA causes the
characters to be taken from an input line buffer maintained by
the driver. When the input line is exhausted, and a READA is
issued, the driver processes characters from the type-ahead
buffer, placing regular keystrokes in the input line buffer,
performing editing as directed by control keys, and performing
echoing for the typist's benefit. A ^Z read from the type-ahead
buffer will cause an End of File condition to occur. Parity is
stripped, leaving only 7-bit ASCII codes. Characters are not
taken from the input line buffer until activation has been
signaled. READA terminates when an activation character is
encountered, or RDBUF has no room for the next character. In
the latter case, an "Activation Not in Buffer" error is returned,
along with as much data as RDBUF can hold. READA must be done in
line mode: a non-line mode request for more than zero bytes will
result in an "Illegal Device Operation" error; READA non-line
mode for zero bytes is accepted for backwards compatibility
reasons to allow change of mode from Binary reads to Ascii reads.
As a general rule, SDOS uses a single <CR> character to represent
<CR><LF> as a pair. Line feeds are not an acceptable alternative.
When a READB is issued, keystrokes are accumulated in the input
line buffer (and the type-ahead buffer, as necessary), with
neither echoing nor pre-processing of any kind. The exact key
codes generated by the terminal hardware are passed directly to
the application, including the parity bit. READB is terminated
when the reply buffer is filled. WARNING: an unsatisfied READB to
a VT device cannot be aborted; we do not recommend using this.
If the last operation upon the terminal was READA, then most
control keys, including ASCII:ESC and ASCII:RUBOUT cause various
actions to be taken by the VT driver; these keystrokes are not
passed to the application. If READB was last issued, no special
interpretation of any keystroke is made; all keystrokes are
placed in the type-ahead buffer for processing by the
application. READA and READB permit a 0-byte read request for the
purpose of changing input modes. See section on Control
Characters for a complete list of the control characters, and
their actions, upon both input and output.
COPYRIGHT (C) 1978 16 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION II: DEVICE DRIVERS
WRITEA causes text to be output to the terminal. All characters
are first stripped of the "parity" bit (bit 7), and then
inspected to determine their interpretation. Printing characters
are sent to the device. Tab characters are expanded according to
the tab table assigned to each terminal. ASCII:CR characters
cause an ASCII:LF and a variable number of idle characters to be
output after them. ASCII:FF (form) characters cause CRT screens
to be cleared, and cause printers to move to top-of-next-page.
Other control characters are generally printed as ^c, where c is
the keystroke used with the control key. See Table of Control
Characters for a complete list of the control characters, and
their actions, upon both input and output.
WRITEB causes the bytes to be sent to the terminal exactly as
specified in the write buffer, including the "parity" bit. No
linefeeds or idles are inserted. The logical column count is
zeroed, and the VT driver assumes it no longer knows the location
of the cursor (the application must issue a CC:POSITION or
perform an implied positioning call before the VT will know where
the cursor is again).
COPYRIGHT (C) 1978 17 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION II: DEVICE DRIVERS
The VT driver supports the following control operations:
CC:POSITION
The positioning information is treated as a cursor position
of the form R*256+C, where R is the desired row (0 is the
top row), and C is the desired column (0 is the leftmost
column). Any value which would cause the cursor to position
off the display, will result in an Illegal Device Operation
error, and the cursor will not be moved. Positioning the
cursor of a hardcopy terminal (display depth is zero) or a
printer is not permitted, and will result in an Illegal
Device Operation error. Note that SYSCALL:READA,
SYSCALL:READB, SYSCALL:WRITEA and SYSCALL:WRITEB all allow
implied positions in SCBLK:EXTENSION, so that a single call
can both position the cursor and do I/O.
CC:DUMPBUFFERS
This is generally a no-op, since the driver dumps characters
to the device as fast as it can; it does check for a device
timeout. No parameters are needed.
CC:ECHO
This enables echo on READA. No parameters are needed.
CC:NOECHO
This shuts off echo on READA. No parameters are needed.
CC:WRAP
This enables line wrapping when a line exceeds the display
width.
CC:NOWRAP
This disables line wrapping when a line exceeds the display
width: the line is truncated, and the cursor is left on the
same line, following the last character displayed.
CC:IDLES
This sets the number of idles to be transmitted after a <CR>
or <LF>. The first byte in WRBUF is the idle count (0 is
legal), the second byte in WRBUF is the character after
which the idles are to follow. If the second byte is not
present, idle trigger defaults to <LF>. A character other
than <CR> or <LF> will cause an "Illegal Device Operation"
error. This information is not changed by OPENs, CREATEs, or
CLOSEs. Note that the current profile must be either
malleable or hardcopy (an option which must be SYSGENed into
the I/O package); otherwise, a Profile Not Malleable error
will be returned.
Caveat: Some terminals will behave differently for <LF><CR>
than for <CR><LF>.
COPYRIGHT (C) 1978 18 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION II: DEVICE DRIVERS
CC:TABS
This sets tab stops for tab simulation. The WRBUF must hold
a string of bytes, each byte specifying the next tab stop.
Each successive byte must contain a column number larger
than the previous one. When the terminal is first opened,
tab columns are set at every eighth column, up to 132
columns (0 is the first column). Up to 16 tab stops may be
set; if too many are supplied, an "Illegal Device Operation"
error will result. If the order of the tab stops is
incorrect (not monotonically increasing), an "Illegal Device
Operation" error will be returned, and the old tab settings
will be undisturbed. Since CONSOLE: devices tend to stay
open for long periods of time, CONSOLE: tab settings have a
tendency to remain in effect long after needed.
CC:SETACTBLOCK
This specifies a non-standard set of activation characters.
The non-standard set is specified with a vector of 128 bits
(arranged in WRBUF as 16 bytes), corresponding to the ASCII
character set. The least significant bit in the first byte
corresponds to character code 00, and the most significant
bit of the 16th byte corresponds to character code :7F.
When a bit is set, the corresponding character is
interpreted as a non-standard activation character; when the
bit is reset, the standard interpretation applies (see the
chart of Control Characters, below). The activation set is
restored to the standard interpretation (all bits reset) by
OPEN and CREATE. When marked as activation characters,
control characters and ASCII:RUBOUT are never echoed, while
printing characters echo only if echo is enabled. Note that
<CR> is always an activation character -- marking it as a
non-standard activation character only changes its echoing
characteristics (as a standard activation character, it
echoes if echo is enabled; as not-standard, it does not
echo).
CC:CLRINPUT
This clears the input line and type-ahead buffers. This is
useful when input, following an abnormal condition, is
required.
CC:CLROUTPUT
This clears the output buffer. It is generally useful only
when the output buffer for a device is very big, or the
device is very slow; otherwise, the buffer will empty
quickly anyway.
COPYRIGHT (C) 1978 19 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION II: DEVICE DRIVERS
CC:SETREADTIMEOUT
This sets a timeout on a subsequent READA or CC:ACTIVATIONCK
control call. The timed period begins when the subsequent
input operation is issued. When the timed period has
expired, the input operation is terminated with a "Timed
Input Expired" error, and the data input thus far is
returned in the RDBUF supplied by the input operation. The
length of the period is expressed in 60ths of a second, as a
16-bit value. Note that the period allowed is only
approximately what is specified, but is guaranteed to be
longer than the value given. The value is found in WRBUF,
and WRLEN must be 2.
CC:SETPROFILE
This selects a new device profile, which includes a function
mapping VT operations to physical terminal operations.
Selection of a profile sets default device width, depth and
output timeouts; it specifies how the device will position
the cursor, clear the screen, erase to end of line, and go
to new lines; it controls how "coloring" is to be displayed,
etc. Such a profile generally represents a particular model
of CRT/printer. The new profile replaces the old profile,
and is retained until changed or the system is re-booted.
Some profiles are malleable and may be somewhat altered to
accomodate devices for which there is no specific profile
(see below). As the malleable profile is a template, any
alterations are retained with the device, rather than with
the profile. Selection of a new profile will cause previous
alterations to be lost. WRBUF contains one number, which is
the profile "name". Specification of a profile not sysgenned
into the I/O package will result in a "No such Profile"
error. WRLEN must be 1. This call is normally only used by
the SDOSSET program. For a list of profile names, see the
documentation for SDOSSET or the file IOVTDPBS.ASM.
Note that adding a new profile requires changes to the I/O
package.
COPYRIGHT (C) 1978 20 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION II: DEVICE DRIVERS
CC:ALTERPROFILE
This alters the currently selected profile (see above), if
it is malleable; if it is not, a "Profile Not Malleable"
error is returned. The alterations are confined to defining
a cursor-positioning sequence, an erase to end of line
(EEOL) sequence, and a home and clear screen (CLEAR)
sequence. An "Illegal Device Operation" will be given if
the parameter supplied are unreasonable. Note that the
cursor positioning sequence contains, in place of the row
and column numbers, the offsets to be added to the row and
column numbers supplied by the application; thus, the cursor
positioning sequence could be used, by itself, to position
to location (0,0). More extensive alteration must be
accomplished by defining a new profile and incorporating it
into a newly-generated system.
WRBUF must contain the following data:
ALTERPROFILE:CPLEN significant length of cursor
positioning sequence following; 1
byte in range 3 to 4. If this
length is < 3, then the VT driver
will output '@@' instead of a
cursor position.
ALTERPROFILE:CPSEQ cursor position sequence, which
includes the row and column
offsets; 4 bytes
ALTERPROFILE:CPIDLES number of idles to follow cursor
positioning sequence; 1 byte
ALTERPROFILE:ROWDISP displacement into cursor
positioning sequence of row number;
1 byte
ALTERPROFILE:COLDISP displacement into cursor
positioning sequence of column
number; 1 byte
ALTERPROFILE:CLLEN significant length of CLEAR
sequence following; 1 byte in range
0 to 4. If 0, a CLEAR sequence
will be simulated by generating
enough ASCII:LFs to move to the top
of a page if a printer device (page
depth can be changed by
CC:SETPARAMS). This is a useful
device if a system has different
size paper forms, and no forms
control tape.
ALTERPROFILE:CLSEQ CLEAR sequence; 4 bytes
COPYRIGHT (C) 1978 21 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION II: DEVICE DRIVERS
ALTERPROFILE:CLIDLES number of idles to follow CLEAR
sequence; 1 byte
ALTERPROFILE:EEOLLEN significant length of EEOL sequence
following; 1 byte in range 0 to 4.
If 0, the sequence will be
simulated.
ALTERPROFILE:EEOLSEQ EEOL sequence; 4 bytes
ALTERPROFILE:EEOLIDLES number of idles to follow EEOL
sequence; 1 byte.
CC:WRITEEDITLINE
This appends the contents of WRBUF to the end of the input
line buffer as if the typist had entered that data. A
subsequent READA or CC:ACTIVATIONCK control call will cause
the data to be displayed, in the usual fashion, and the
typist may edit the data until an activation character is
entered. Note that using the CC:NOECHO control call, prior
to invoking CC:WRITEEDITLINE, will inhibit that data from
being displayed at the time of the READA or CC:ACTIVATIONCK
control call. An activation character may be present in
WRBUF, but will prevent the typist from editing characters
prior to the activation character: activation will occur
immediately. If WRLEN is greater than the space available in
the input line buffer, or data follows an activation
character in WRBUF, an Illegal Device Operation error is
returned and no data is transferred to the input line
buffer.
If present, the syscall block extension contains a cursor
position at which the cursor should be left, after the data
has been echoed by the input operation; otherwise, the
cursor will be left at the end of the data supplied in
WRBUF.
When a field has been explicitly defined (see the
CC:SETFIELDSIZE control call, below), the 1-byte syscall
extension is the column number at which the cursor is to be
placed, at the time of the READA or CC:ACTIVATIONCK control
call; if that column is in the middle of a tab expansion,
the cursor will be positioned following the expanded tab.
COPYRIGHT (C) 1978 22 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION II: DEVICE DRIVERS
CC:SETFIELDSIZE
This defines an input field for a subsequent READA or
CC:ACTIVATIONCK control call. WRBUF contains the field
width. The field width must be at least 1 and no greater
than the width of the display. If the field width is 0, or
exceeds the limits of the display, a "Bad Field Width" error
will be returned, and the field definition will not be made.
Unless any of the cursor control keys for moving left,
right, up, and down have been designated activation
characters, they may be used to position within the defined
field. When an attempt is made to position the cursor
beyond the boundary of the field, that character is treated
as an activation character and the operation is terminated;
the terminating cursor control character is appended as the
activation character, and the cursor is not moved. An
SC:GETACTCOL status call may be issued to determine the
exact column of exit. If any of the cursor control
characters is designated an activation character, then that
character cannot cause a field exit condition, and will
activate immediately upon use.
The field definition terminates upon field exit, or entry of
an activation character. If the field, at the time of the
input operation, is not contained completely within the
display width, that input operation will terminate with an
"Bad Field Width" error and the field input mode will be
cancelled. ^C^C will cancel any outstanding field
definition.
CC:SETPARAMS
Sets the width (1 byte) and the depth (1 byte) of the
display; this overrides the default from the device profile
chosen. Zero depth means that the terminal is not a paging
device and will print ^L when given a form feed character.
COPYRIGHT (C) 1978 23 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION II: DEVICE DRIVERS
CC:ACTIVATIONCK
This is used to enable keyboard input without causing the
program to suspend operation. CC:ACTIVATIONCK returns an
"Activation Received" error if an activation character is in
either the input line buffer or the type-ahead buffer. If no
activation character is present in either buffer, the input
line buffer is filled from the type-ahead buffer, unless
this has already been done by a previous call of
CC:ACTIVATIONCK. A READA issued following an "Activation
Received" error will always return immediately with the data
requested and/or an error appropriate to a READA (If ^C^C
has been seen while the SDOS/MT and KILLPROOF flags are set,
a "Program Killed" error will be returned; otherwise, ^C^C
will result in the program being killed.) *Once the
CC:ACTIVATIONCK control call has been issued, subsequent I/O
requests (with the exception of CC:ACTIVATIONCK, status
requests, and SYSCALL:READA) will result in an "I/O In
Progress" error. This state is exited by issuing a READA
upon receipt of an "Activation Received" error. A
CC:SETREADTIMEOUT control call issued prior to the initial
CC:ACTIVATIONCK can be used to limit the time spent in this
state. When the timed period expires, the next
CC:ACTIVATIONCK will return an "Activation Received" error,
and the subsequent READA will return the expected "Timed
Input Expired" error, along with any data received prior to
the expiration.
* See the section on SDOS/MT support for a caveat that
applies to this note.
CC:SETBAUDRATE
This call is used to change the baud rate of a device.
WRBUF contains a 16 bit unsigned integer representing the
exact baud rate desired (rounded to an integer). An
"Illegal Device Operation" is returned if the baud rate
cannot be changed, or cannot be changed to the specified
value.
COPYRIGHT (C) 1978 24 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION II: DEVICE DRIVERS
CC:COLORING
For the purposes of this control call, a "color" is that
which changes the appearance of text without changing its
meaning or size. This call supports the myriad available
features dealing with display appearance: these include, but
are not limited to: color, intensity, underscoring, and
blinking. It explicitly does NOT handle characters whose
size is non-standard (i.e., double-width or double-height)
for the device. 16 bits of data, found in WRBUF, specify the
desired display mode for subsequent output: all display
characteristics must be specified by the same control call
at one time.
The mode change is made immediately, and the mode is saved
for later use by the position control call. All characters
output via WRITEA are "colored" according to the last color
selected by this call. When a position control call is
made, the "zero" coloring is selected (see CC:BACKGROUND,
below), the positioning is performed, and the coloring
selected by CC:COLORING is re-instated.
CC:COLORING does not cause the cursor to move (some
terminals violate this, due to their design deficiencies).
Two bytes in WRBUF are used to specify the display modes.
The first byte is divided as follows: 2 bits for intensity,
1 bit for blink, 1 bit for underscore, 1 bit for reverse
video, 3 bits for (inverted) color (1 bit each for "not
red", "not green", and "not blue"). The second byte contains
3 bits for selecting alternate Roman character sets; the
remaining bits are undefined and must be zero. The default
color of "zero" (both bytes zero) selects the standard
Roman character set, standard intensity, no reverse video,
no underscore, no blink, and the color white (i.e., the
display mode obtained for virtually all "dumb" CRTs). The
"zero" color is automatically selected by OPEN.
Although this control call is recognized by all systems, its
actual implementation will vary according to the particular
terminals being supported; in the simplest of cases, it will
be implemented as a NOP.
COPYRIGHT (C) 1978 25 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION II: DEVICE DRIVERS
CC:BACKGROUND
A "background" color is the color displayed in all screen
locations which do not contain a character.
CC:BACKGROUND selects the default coloring to be used when
the display is cleared, or when cursor positioning is to be
done (see CC:COLORING, above). The required byte of data is
found in WRBUF and is of the same format as for the first
byte of CC:COLORING, above. A black background (hex :07) is
automatically selected by OPEN.
Although this control call is recognized by all systems, its
actual implementation will vary according to the particular
terminals being supported; in the simplest of cases, it will
be implemented as a NOP.
CC:KILLPROOF
This is used to KILLPROOF a specific VT input device. What
that means is that ^C^C and ^D will be rejected with a beep
when they are entered. ^C while killproof clears the
type-ahead buffer.
CC:KILLENABLE
This is used to cancel the effect of a CC:KILLPROOF control
call directed at the same VT input device. Note that
SYSCALL:KILLPROOF is not overridden by this control call.
CC:SETEXCEPTION
This call is used to specify exceptions to VT driver
processing. At this time, the only exception defined is for
SEDIT; and specifies that fields also activate on
ASCII:RUBOUT at left end of field, and on ^U or ^L at right
end of field.
CC:SETOUTPUTTIMEOUT
This call is used to specify a new value for output timeout
interval, and overrides the default selected by the Device
Profile Block last chosen. It is especially useful with the
VT:MALLPT profile when the printer has a large buffer of its
own, and goes "BUSY" for long periods while it prints. The
interval is specified as a two byte number in WRBUF in 60ths
of a second.
COPYRIGHT (C) 1978 26 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION II: DEVICE DRIVERS
STATUS OBTAINABLE FROM THE VT DRIVER
Many of the statuses available from the VT driver are simply
images of data specified by Control calls to the driver. This is
for convenience of the SDOSSET program, and allows it to show the
operator the "current" settings of things before modification.
SC:GETPOS
Reads the cursor position in the same form as CC:POSITION.
SC:GETCOL
If the input line buffer is empty, this returns the output
column number; otherwise, this returns the column number
corresponding to the first byte to satisfy the next read.
The column number is the same as used in CC:POSITION. A
READB zeroes the column number. Returning the column number
corresponding to the next input character when there is a
partially-read input line makes it possible to distinguish
between "TERSE" command lines and "VERBOSE" command lines;
if the column count is zero when a program gets control,
there must be nothing in the line buffer and so VERBOSE mode
is desired; otherwise, something is in the line buffer and
so TERSE mode is desired (see COMMAND INTERPRETER).
SC:GETEOF
This returns a non-zero byte if ^Z was seen while in READA
mode, and the input line buffer is empty; otherwise, this
returns a zero byte. End of File status is never set while
in READB mode to a VT device. Note that the only way to
reset this status is to CLOSE and reOPEN the channel.
SC:GETTYPE
Returns DVTYP.CONSOLE or DVTYP.PRINTER, as appropriate.
SC:GETPARAMS
Returns the width (1 byte) and the depth (1 byte) of the
display. Zero depth means that the terminal is a hardcopy
device with continuous paper. Printers return paper width
and depth.
SC:GETPROFILE
Returns the current profile "name" (a one byte number);
suitable for use by the CC:SETPROFILE control call.
SC:GETPROFILENAME
Returns a one to 16 character ASCII text string
corresponding to the numeric profile "name" (1 byte)
specified in WRBUF. This call does NOT change the profile
currently selected on the device. Return a "No Such Profile"
error if the profile name specified in WRBUF is not
sysgenned into the I/O package. This call is used to all
SDOSSET produce a human-readable list of DPBs configured
into a system.
COPYRIGHT (C) 1978 27 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION II: DEVICE DRIVERS
SC:GETPROFILEALTERATION
Returns the current profile alterations in exactly the
format given to CC:ALTERPROFILE. Gives a "Profile Not
Malleable" error if the profile currently selected is not
malleable (and therefore has no alterations).
SC:GETFREECOUNT
Returns a 16 bit integer specifying how much room is
currently available in the output buffer for a device
(memory-mapped video displays always return "1").
SC:GETDATACOUNT
Returns a 16 bit integer specifying how much data is
currently available in the input ring buffer for this
device. Can be used to prevent hanging the system when
doing READB.
SC:GETOUTPUTTIMEOUT
Returns the current value of the Output Timeout for this
device, in a form suitable for use with CC:SETOUTPUTTIMEOUT.
SC:GETBAUDRATE
Returns the current baud rate for this device, in exactly
the form required for CC:SETBAUDRATE. Devices which cannot
change baud rates usually return "0".
SC:GETTABS
Returns the current tab settings for this device, in exactly
the form required for CC:TABS.
SC:GETIDLES
Returns the count of idles to follow a Newline sequence, and
the Idle trigger character, in exactly the form required for
CC:IDLES.
SC:GETWRAP
Returns a non-zero byte if Wrapping (see SC:WRAP) is
enabled, else return a zero byte (wrapping is disabled).
SC:GETCOLORING
Returns 2 bytes of Coloring information in exactly the form
required by CC:COLORING.
SC:GETBACKGROUND
Returns 1 byte of Background Coloring information in exactly
the form required by CC:COLORING.
COPYRIGHT (C) 1978 28 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION II: DEVICE DRIVERS
SC:GETACTCOL
Returns both the column position and the line buffer
displacement at which the last activation character was
entered (the activation character, itself, is placed at the
end of the input line and is obtained via READA or READB).
Note that if echoing is disabled, the returned column
position value will be meaningless.
SC:ATTENTIONCK
This checks for "Operator Requested Attention" status. If
found, the status is cleared and an "Operator Requested
Attention" error is returned.
SC:STATUSCK
This returns a "Status Has Changed" error if the VT device
has had an interesting change of status, which include
receipt of an activation character, receipt of ^C^C, a
"Timed Input Expired" error, a "Device Timed Out" error,
etc.
COPYRIGHT (C) 1978 29 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION II: DEVICE DRIVERS
CONTROL CHARACTERS
This table describes how control characters are treated if they
are NOT marked as activation characters (see CC:SETACTIVATION).
:00 NUL input: ignored
output: discarded
:01 ^A input: toggles the CAPS LOCK switch, echoes
immediately at the end of the line
output: prints ^A
:02 ^B input: requests BASIC breakpoint, does not echo
output: prints ^B
:03 ^C input: clears the input and output buffers,
resets the FREEZE OUTPUT and DISCARD
OUTPUT switches (see ^S, ^O), resets the
PAGE MODE switch (see ^P), echoes
immediately at the end of the line,
aborts the program if two ^C's are
received in succession; ^C^C will be
rejected with a beep if KILLPROOF is set.
output: prints ^C
:04 ^D input: invokes the debugger immediately, does not
echo; a beep is echoed if no debugger is
available (CNFG:VTDEBUG=0). Illegal under
SDOS/MT.
output: prints ^D
:05 ^E input: causes all input at, and to the right of,
the cursor to be erased from the display
and deleted from the input buffer.
output: erases the remainder of the display line
(erase to EOL)
:06 ^F input: positions cursor at left side (front) of
current input field. Illegal for hardcopy
terminals.
output: prints ^F
COPYRIGHT (C) 1978 30 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION II: DEVICE DRIVERS
:07 ^G input: causes BASIC to resume execution from the
current breakpoint, does not echo
output: beeps
:08 ^H input: implements the backspace function, does
not echo
output: implements the backspace function.
Backspace across edge of screen is not
allowed.
:09 ^I input: positions the cursor at the next tab
column, when read
output: positions the cursor at the next tab
column
:0A ^J input: rejected with beep; see CC:SETFIELDSIZE
output: discarded
:0B ^K input: rejected with beep; see CC:SETFIELDSIZE
output: prints ^K
:0C ^L input: implements the forespace function, does
not echo
output: causes a PAGE BREAK if the PAGE MODE
switch is set (see ^P), homes the cursor,
selects the background color, and clears
the display if depth is not zero, prints
^L if the the depth is zero; for a printer
device, moves paper to the top of form,
such that the next character will be
printed in the first position of the line.
:0D ^M input: echoes <CR><LF>, causes program activation
output: prints <CR><LF>
:0E ^N input: passed to the application, echoed when
read
output: prints ^N
:0F ^O input: toggles the DISCARD OUTPUT switch (see ^Q,
^C), echoes immediately; not functional
while a READA or CC:ACTIVATIONCK control
call is being satisfied
output: prints ^O
COPYRIGHT (C) 1978 31 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION II: DEVICE DRIVERS
:10 ^P input: toggles the PAGE MODE switch (see ^Q, ^C),
echoes immediately at the end of the line
output: prints ^P
:11 ^Q input: resumes output suspended due to a PAGE
BREAK (see ^P), resets the DISCARD OUTPUT
switch (see ^Q), resets the FREEZE OUTPUT
switch (see ^S), does not echo
output: prints ^Q
:12 ^R input: if CRT, positions cursor to Right end of
current input field; for hardcopy devices
echoes ^R<CR><LF> followed by all data
entered since the last activation
output: prints ^R
:13 ^S input: sets the FREEZE OUTPUT switch (see ^Q,
^C), echoes immediately
output: prints ^S
:14 ^T input: toggles the BASIC line trace switch, does
not echo
output: prints ^T
:15 ^U input: deletes the character at the current
cursor location, deletes the corresponding
character from the input buffer, does not
echo
output: prints ^U
:16 ^V input: toggles the BASIC single step switch, does
not echo
output: prints ^V
:17 ^W input: for CRTs, causes the last input line to be
retrieved as though the typist had entered
it explicitly, if no other keys have been
typed since the last input. Illegal for
hardcopy devices.
output: prints ^W
COPYRIGHT (C) 1978 32 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION II: DEVICE DRIVERS
:18 ^X input: clears the input buffer; for hardcopy,
echoes ^X<CR><LF> and positions to the
column at which input began; for a
terminal, erases, from the display, the
data entered since the last activation
character, and positions the cursor at the
location where input began; for a terminal
with fields defined, erases the displayed
field contents, and positions the cursor
at the first location of the field
output: prints ^X
:19 ^Y input: passed to the application, echoed when
read
output: prints ^Y
:1A ^Z input: causes END OF FILE status to be set,
causes program activation with an END OF
FILE error, echoes immediately at the end
of the line
output: prints ^Z
:1B ESC input: causes cursor to be placed at right end of
current input field, OPERATOR REQUESTED
ATTENTION status to be set, and returns
"Operator Requested Attention" error.
output: prints ^[
:1C ^\ input: passed to the application, echoed when
read
output: prints ^\
:1D ^] input: passed to the application, echoed when
read
output: prints ^]
:1E ^^ input: passed to the application, echoed when
read
output: prints ^^
COPYRIGHT (C) 1978 33 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION II: DEVICE DRIVERS
:1F ^_ input: passed to the application, echoed when
read
output: prints ^_
:7F RUB input: deletes the character preceeding the
current cursor location, deletes the
corresponding character from the input
buffer, does not echo
output: discarded
NOTE: No control character is passed to the application unless
explicitly noted.
COPYRIGHT (C) 1978 34 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION II: DEVICE DRIVERS
SOFTWARE SWITCHES AFFECTED BY CONTROL CHARACTERS
CAPS LOCK
When set, READA will interpret the lowercase letters a-z as
uppercase letters. ^A toggles the switch. If a terminal is
stuck in upper case, and the alpha lock key isn't the
problem, someone probably typed ^A by accident.
FREEZE OUTPUT
When set, further output will be suspended until the switch
is reset. On CRTs, ^S will be displayed to remind the typist
that the switch has been set. ^S sets the switch, ^Q and ^C
reset the switch.
DISCARD OUTPUT
When set, all output will be discarded until either the
switch is reset or a READA/READB is issued. ^O will be
displayed to remind the typist that the switch has been set.
A READA will reset the switch and overwrite the "^O" with "?
". A READB will simply reset the switch. ^O toggles the
switch, ^Q and ^C reset the switch.
PAGE MODE & PAGE BREAK
When set, subsequent WRITEA lines will be counted, and when
<display depth> lines have been output, a Clear screen
request is output, or cursor positioning is attempted, then
a PAGE BREAK will occur, and no more output will occur until
the typist has acknowledged the page break. This gives the
typist a chance to read what is displayed before more output
occurs. On a CRT, a page break will be signalled by ^P being
displayed in the lower right-hand corner of the screen; on
hardcopy devices, output will simply cease. The
acknowledgement can be ^P (which prevents further page
breaks), ^Q (which allows output until the next page break),
or ^C (which prevents further page breaks). On CRTs, a Clear
screen requests causes a page break BEFORE the screen is
cleared, so the text may be read before it disappears; on
hardcopy terminals, the page break occurs AFTER the FORM
character moves the paper to top-of-page, so individual
sheets of paper may be conveniently printed. All lines
output while in page mode will be truncated to fit within
the current display width, thus ensuring that line wrapping
does not occur so that all lines between page breaks will be
captured on the display.
NOTE: All reminders are displayed in the lower, right corner of
the display. Reminders will overwrite any characters
already in those locations.
COPYRIGHT (C) 1978 35 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION II: DEVICE DRIVERS
SDOS/MT SUPPORT
The following control and status functions are included for
complete documentation only. They are subject to change without
notice.
Caveat Emptor!!
MULTIUSER CONTROL FUNCTIONS
CC:SETTIMESHARE
Sets the SDOS/MT flag, which results in different handling
of the line flags and ^C^C abort. If the flag has already
been set, an "SDOS/MT Already Running" error is returned.
RDBUF is filled with system-dependent linkage information
for use by SDOS/MT.
CC:STOPTIMESHARE
Turns off the SDOS/MT flag. SHOULD NOT BE EXECUTED BY USER
PROGRAMS, OR A SYSTEM CRASH WILL RESULT.
CC:WRITEANOWAIT
This defines, for the VT driver, WRBUF as the source of data
for an asynchronous WRITEA of WRLEN bytes. RDBUF contains 3
bytes, the first of which the VT driver will set to zero
when the request is accepted, and set to non-zero when WRLEN
bytes have been written; the remaining two bytes will
contain either an error code, or zero if the operation had
no errors. Note that WRBUF must not be modified until the
request is complete (the first byte of RDBUF becomes
non-zero).
CC:WRITEBNOWAIT
This defines, for the VT driver, WRBUF as the source of data
for an asynchronous WRITEB of WRLEN bytes. RDBUF contains 3
bytes, the first of which the VT driver will set to zero
when the request is accepted, and set to non-zero when WRLEN
bytes have been written; the remaining two bytes will
contain either an error code, or zero if the operation had
no errors. Note that WRBUF must not be modified until the
request is complete (the first byte of RDBUF becomes
non-zero).
COPYRIGHT (C) 1978 36 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION II: DEVICE DRIVERS
MULTIUSER STATUS FUNCTIONS
SC:GETLINEFLAGSHINT
Returns zero if no line flags have been collected since
the last call to SC:GETLINEFLAGS, otherwise returns
non-zero value. The value returned is only intended as
a hint; the program must call SC:GETLINEFLAGS to get
the true line flags and acknowledge their receipt.
Don't ask why.
SC:GETLINEFLAGS
Exchanges a zero with the line flags, and returns that
byte. If ^C^C has been seen while the SDOS/MT and
KILLPROOF flags are set, a "Program Killed" error will
be returned; otherwise, ^C^C will result in the program
being killed.
SC:GETTIMESHARE
This checks to see if SDOS/MT is running. If it is, an
"SDOS/MT Already Running" error will be returned;
otherwise, a normal return will be made.
SC:ALLSTATUS
This checks to see if an SC:STATUSCK status call issued
to any VT device would return a "Status Has Changed"
error as a response; if so, a "Status Has Changed"
error is returned. Note that this status call supplies
only a hint.
COPYRIGHT (C) 1978 37 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION II: DEVICE DRIVERS
The CLOCK: Device Driver
The CLOCK: device is used to set and read the current time and
date. Since its function is limited, so is its conformance to
the SDOS file concept.
The CLOCK: device can only be OPENed. CREATE, RENAME, DELETE,
WRITEA, and CONTROL operations are illegal. CLOSE does nothing
except to disassociate the I/O channel from the driver.
A READA directed to the CLOCK: device returns a string of 17
bytes in the following form:
HH:MM:SS MO/DD/YY
where HH is hours on a 24 hour clock, MM is minutes, SS is
seconds, MO is the month, DD is the day number, and YY is the
year modulo 100. An ASCII:CR is appended if the READA has line
mode enabled and buffer space permits.
A READB returns 6 bytes exactly in the following form:
T T T M D Y
where T T T is a 24 bit binary value equal to the number of 1/60
second clock ticks since midnight; D is the day, M is the month,
and Y is the year modulo 100, all in BCD.
A WRITEB must write exactly 6 bytes in the format read by READB,
and is used to set the time of day.
The only status syscall accepted is SC:GETTYP, which returns
DVTYP.CLOCK.
COPYRIGHT (C) 1978 38 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION III: SYSCALLS
SYSCALLS - CONCEPTS
Programs running under SDOS communicate with it via system calls
(SYSCALLs). A SYSCALL is a subroutine call (from the user program
to SDOS) with a parameter block describing the function to be
performed.
This section describes the general philosophy behind the SYSCALLs
and their general format. It assumes some knowledge of assembly
language.
The most general form of a SYSCALL contains a function code, some
fixed parameters needed by the function, a (pointer to) Write
buffer and a (pointer to) Reply buffer. Essentially, the SYSCALL
causes the specified function to be performed according to the
parameters, using data from the write buffer, and storing a
result in the reply buffer. Many readers will recognize this as
an implementation of
RDBUF:= F(PARAMS, WRBUF)
The purpose of constraining all SYSCALLs to this form is to
simplify the process of transmitting a request from one computer
to another, to facilitate networking of multiple computers.
Conceptually, SYSCALL execution proceeds as follows:
1) The user program issues a SYSCALL.
2) SDOS transmits the function code, the parameters, and the
contents of the WRITE Buffer from the user's computer to some
target computer.
3) The target computer processes the SYSCALL and produces a
reply.
4) The reply, along with any error information, is sent back to
the SDOS which sent out the request.
5) SDOS places the reply in the user program's reply buffer.
In a stand-alone system, the target computer and the user's
computer are one and the same.
The primary advantage of this scheme is that by forcing all
SYSCALLS to have a fixed form for transmitting, performing, and
receiving replys to function requests, the software logic
processing the request can forward it to another computer without
having a lot of function-specific knowledge. In particular, it
means that the forwarding logic need not be changed even when new
functions are added to the list of legal SYSCALLs.
COPYRIGHT (C) 1978 39 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION III: SYSCALLS
Typical SYSCALL functions are: OPEN file, READ byte stream, LOAD
a program, etc. Not all functions require write data (i.e., a
STATUS Syscall needs only the function, some parameter bytes and
a reply buffer); nor do all functions return a result (WASCII
writes a string of ASCII bytes to a file and returns no result).
Some functions have neither write nor reply buffers (i.e., EXIT
to system). Furthermore, many functions have side effects (like
CLOSE I/O channel).
SYSCALL Format:
The following definitions give the formats of a SYSCALL block
(SCBLK).
*
* SYSCALL BLOCK DISPLACEMENTS
*
ORG 0
SCBLK:OPCODE RMB 1 Primary SYSCAL Function (Open,
Read, Etc.)
SCBLK:WLEN RMB 1 Wait Flag Bit (0=Wait) and SYSCALL
Block Length (0..127)
SCBLK:PARAMS RMB 2 Parameter Bytes to Opcode (Secondary
Opcode, Channel #)
SCBLK:WRBUF RMB 2 Pointer to Write Data Buffer
SCBLK:WRLEN RMB 2 Number of Bytes in Write Data Buffer
SCBLK:RPLEN RMB 2 Length of Reply (Result of SYSCALL)
SCBLK:RDBUF RMB 2 Pointer to Read Data Buffer (Where
Result Goes
SCBLK:RDLEN RMB 2 Ceiling on Size of Reply (Read Data
Buffer)
SCBLK:DATA RMB 0 Other Parameters for SYSCALL; up
to 127-14=113 Bytes
SCBLK:END RMB 0 End of SYSCALL Block;
Assert SCBLK:WLEN[1..7]=
SCBLK:END-SCBLK:OPCODE
SCBLK:OPCODE is the desired function, and occupies a single byte.
Legal functions under SDOS 1.0 are shown in table 1.
(Definitions of all values for SYSCALL opcodes and related
information is given in the SDOSIOPKDEFS.ASM listing in the
back of this manual).
COPYRIGHT (C) 1978 40 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION III: SYSCALLS
SCBLK:WLEN is a single byte with two parts: a Wait flag (the most
significant bit) and a LENgth (2 to 127, measured in bytes)
(the SYSCALL block length). The wait flag is intended to
allow overlapped READ and WRITE operations to files, but is
not implemented in SDOS 1.0. When this bit = 0, it means
"wait for operation complete before returning control to
user program". "1" means "don't wait". To retain
compatibility with future releases of SDOS, the user is
advised to leave this bit reset (0). The LEN field
specifies precisely how long the SYSCALL block is. Each
opcode requires that this byte have some minimum value, or
the SYSCALL will be aborted. The LEN field is used to
determine how much data must be sent to another computer.
The LEN field can specify more bytes than actually needed by
the SYSCALL without ill effect, but processing the unused
bytes may increase the execution time of the SYSCALL. All
SYSCALLs have at least the SCBLK:OPCODE and SCBLK:WLEN
bytes.
SCBLK:PARAMS are 2 bytes used for sundry purposes as parameters
to the opcode requested. Three cases are of particular
note: first, one of the two parameter bytes is generally
used to hold an I/O channel number on I/O-oriented SYSCALLS.
Second, a parameter byte may contain an opcode extension
byte, as with the STATUS and CONTROL SYSCALLs; the parameter
byte selects which control function is to be performed or
the particular piece of status information to read back.
The third case is some 16 bit number, such as passing an
error code to SDOS via the SETERROR SYSCALL. In no case may
these two bytes contain a pointer or any other kind of
reference to other data in the memory of the user's
computer; only data values or relative references to data in
the write buffer or the SYSCALL block itself are legal
(because after the SYSCALL has been sent to another
computer, how could we follow a pointer?) SCBLK:PARAMs need
not be included in the LEN count for SYSCALLS such as
SYSCALL:CLOSE, SYSCALL:EXIT, etc.
SCBLK:WRBUF and SCBLK:WRLEN define the starting address of the
write data buffer, and its length in bytes. SCBLK:WRBUF
contains the address of the first byte of the buffer;
SCBLK:WRLEN contains the number of bytes in the buffer (0 to
65535). Note that SCBLK:WRLEN is the actual number of bytes
to be processed by the SYSCALL, not the allocated size of
the buffer. These parameters are used in SYSCALLs involving
filenames to specify the (device and) filename desired, or
as data buffer definitions for SYSCALL:WRITEB (Write
Binary), etc.
COPYRIGHT (C) 1978 41 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION III: SYSCALLS
SCBLK:RDBUF and SCBLK:RDLEN select a buffer address and size in
which a SYSCALL result/reply is returned. The SCBLK:RDLEN
must contain the expected maximum size of the result (in
bytes). SCBLK:RPLEN is set to the actual length of the reply
given, that is, the actual number of reply bytes placed in
the RDBUF. Many SYSCALLs do not return a result. If the
SYSCALL block includes space for SCBLK:RPLEN, it will be
zerod if no reply is given. If RDBUF overlaps any part of
the SYSCALL block or the WRBUF, the SYSCALL operation is not
well defined. When an error is returned by a syscall, RPLEN
and RDBUF contents are undefined (unless explicitly
specified by description of the particular syscall). In
particular, there is no guarantee that the RDBUF contents
are preserved (even in the presence of an error).
Bytes in the SYSCALL block beyond SCBLK:RDLEN are interpreted in
a manner specific to the particular SYSCALL opcode (like the
SCBLK:PARAMs bytes). Most SYSCALLs do not need or use these
bytes.
An error occurring during execution of a SYSCALL is handled in
the manner described under SDOS Error handling. The calling
sequence for SYSCALLS is thus:
.
.
.
LDX #SYSCALLBLOCKADDRESS
JSR SYSCALL$ (Equated TO $FB)
BCS OOPS (Go Process Error Code In X)
.
.
.
COPYRIGHT (C) 1978 42 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION IV: ERROR HANDLING
ERROR HANDLING
Error handling is an important part of any programming system.
It allows application programs to continue or effect recovery in
spite of problems encountered. The error handling strategy
outlined here is used throughout most SD software. Facilities to
handle errors in a similar fashion are provided by the SD BASIC
Compiler, so application programs can also support the same
scheme.
Errors detected by SDOS are passed back to the user program for
inspection or handling. Each error which can occur is assigned a
16 bit error code (0 to 65535). Blocks of codes are assigned to
each possible detector of an error (i.e., errors which SDOS
detects have codes from 1000 to 1999, compiled BASIC programs
detect errors 2 to 99, EDIT errors are 200 to 299, etc.).
Each (assembly or SYSCALL) subroutine has two exits: a success
exit (meaning no unexpected/unrecoverable errors occurred) and an
error exit (meaning some error which the subroutine cannot handle
occurred).
If the success exit is taken, normal processing can continue. If
the error exit is taken, an error code is passed back to the
caller for his inspection. The caller has three options:
1) Process and recover from the error (example: for "No Such
File" error on an OPEN, a standard default file name might be
OPENed).
2) Give up; notify the operator of the error and exit.
3) Decide to pass the error back to his caller with an error
indication. This option is particularly important when the
caller can fail in many ways not understood by the caller
(such as I/O faults).
Processing the error requires explicit checking for each of the
possible error codes of interest (due to the large number of
unexpected errors, an "if it's not this, it must be that" scheme
is not safe; one should ALWAYS check explicitly). Sometimes, data
associated with the error is needed for the processing routine to
continue; in these cases, the original detector of the error must
have saved that data in a place agreed upon by the detector and
the routine attempting recovery. An example is a "recovery"
routine that prints out the Logical Sector Number of a disk
sector on which a read error occurred -- the recovery routine
must know that a GETLASTBADLSN STATUS syscall will retrieve the
LSN desired.
COPYRIGHT (C) 1978 43 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION IV: ERROR HANDLING
"Giving up" is aided by the SDOS SYSCALL:ERROREXIT. The error
code is stored into the SYSCALL block, and the SYSCALL is
executed. SDOS will print a text message corresponding to the
error code, and pass control to the command interpreter
(DEFAULTPROGRAM). The command interpreter can retrieve this
error code, and a DO file can process it via IFERROR statements
(see command interpreter description).
Passing back the error code to the next level of subroutine is
generally done only if the recovery routine does not find an
error code it is willing to handle. This provides an opportunity
for subroutines at successively higher levels to effect recovery.
The subroutine calling convention that implements this error
handling philosophy is as follows:
* (S) = K HERE
JSR Subroutine
BCS ERROROCCURRED
* SUCCESS EXIT (S) = K HERE
.
.
.
CLC FLAG "SUCCESS EXIT"
RTS
ERROROCCURRED EQU * (S) = K HERE
CPX #ERR:--
BEQ HANDLE1STERROR
CPX #ERR:--
BEQ --
.
.
.
SEC (6809 "CMPX" DESTROYS CARRY BIT)
RTS WITH CARRY SET, INDICATING ERROR
HANDLE1STERROR EQU * TO RECOVER FROM 1ST ERROR
.
.
.
CLC (OKRTS IN DEFS)
RTS
COPYRIGHT (C) 1978 44 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION IV: ERROR HANDLING
Carry reset on exit means the subroutine completed successfully.
The carry set on exit from a subroutine means "error occurred"
(only for those subroutines which adhere to this convention!);
the X register contains a 16 bit error code. Note that the
calling subroutine must provide a BCS after the JSR in order to
detect an error. The ERROROCCURRED routine tests the X register
for errors from which it can recover; if the wrong error happens,
no test will match and another RTS (with carry set) will occur,
providing the next higher level subroutine a chance at processing
the error code. In either case, error or not, the contents of
the stack above the return address is untouched. The stack
register itself has the original value of the stack pointer at
the time of the JSR, so that all higher level routines can be
returned to exactly as normal. Last, notice that the HANDLEERROR
and the success paths both exit by clearing the carry (indicating
"success" exit).
SYSCALLs are implemented as subroutine calls and follow the above
convention with one variation. If an error occurs, SDOS unwinds
the stack until a return address on top of the stack points to a
BCC or BCS. This means that a SYSCALL must be followed by a
BCC/BCS or SDOS will unwind the stack too far, with unpredictable
results. The unwinding process consists of repeatedly popping
two bytes, and assuming the top of the stack is a return address,
(with obviously bad consequences if this is not true) until an
appropriate return address is found (This scheme was chosen to
minimize the amount of processing an SDOS routine had to do when
it didn't care about errors, and has the side effect of speeding
things up 5 to 10 percent).
COPYRIGHT (C) 1978 45 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION V: SYSCALLS - IMPLEMENTATION
SYSCALLS - Implementation
This section details the SYSCALLs implemented in this version of
SDOS. See SDOSUSERDEFS.ASM listing for opcode values.
Errors listed are only common errors, i.e., ones for which
application programs attempt recovery. Many other (even hardware
specific errors) are possible, but due to the size and changing
nature of the list, are not recorded here.
Table 1 - Syscalls implemented in SDOS 1.1
* SYSCALL$ OPCODE DEFINITIONS
*
ORG 0
SYSCALL:OPEN RMB 1 Open File
SYSCALL:CREATE RMB 1 Create a New File
SYSCALL:CLOSE RMB 1 Close a File
SYSCALL:RENAME RMB 1 Rename a File
SYSCALL:DELETE RMB 1 Delete a File
SYSCALL:LOAD RMB 1 Load an Overlay
SYSCALL:CHAIN RMB 1 Chain to a File
SYSCALL:CREATELOG RMB 1 Create the Log File
SYSCALL:CLOSELOG RMB 1 Close the Log File
SYSCALL:DISKDEFAULT RMB 1 Select Default Disk Device
SYSCALL:READA RMB 1 Read ASCII Bytes From a File
SYSCALL:READB RMB 1 Read Binary Bytes From a File
SYSCALL:WRITEA RMB 1 Write ASCII Bytes To a File
SYSCALL:WRITEB RMB 1 Write Binary Bytes To a File
SYSCALL:CONTROL RMB 1 Perform a Control Operation
On a File/Device
SYSCALL:STATUS RMB 1 Read File/Device Status
SYSCALL:WAITDONE RMB 1 Wait for I/O on Channel to Complete
SYSCALL:EXIT RMB 1 Give Control Back to Operating System
SYSCALL:ERROREXIT RMB 1 Exit to System With Error Code
SYSCALL:SETERROR RMB 1 Report an Error To The System
SYSCALL:GETERROR RMB 1 Read Back the Last Error Code
SYSCALL:DISPERROR RMB 1 Display Error Message Corresponding
To Last Error Code
SYSCALL:KILLPROOF RMB 1 Prevent User Program Being Killed
SYSCALL:KILLENABLE RMB 1 Allow User Program to be Killed
SYSCALL:DEBUG RMB 1 Call System Debugger
SYSCALL:ATTNCHECK RMB 1 Operator Attention Request Check
SYSCALL:ISCONSOLE RMB 1 Check Channel 0 Input Device = Console:
SYSCALL:INTERLOCK RMB 1 Perform Interlock functions on objects
SYSCALL:DELAY RMB 1 Delay for n 1/60ths of a second
SYSCALL:NOTUSED RMB 1
SYSCALL:GETSERIALNUMBER RMB 1 Get processor serial number
COPYRIGHT (C) 1978 46 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION V: SYSCALLS - IMPLEMENTATION
SYSCALL:OPEN
This SYSCALL is used to establish an association between an
existing file (to be read and/or updated) and an I/O channel.
OPEN SYSCALL Block Format:
SCBLK:OPCODE FCB SYSCALL:OPEN
SCBLK:WLEN FCB SCBLK:END-SCBLK:OPCODE
SCBLK:PARAMS FCB CHANNELNUMBER,IGNORED
SCBLK:WRBUF FDB FILENAMESTRING
POINTS TO FIRST BYTE
SCBLK:WRLEN FDB FILENAMELENGTH
IN BYTES
SCBLK:RPLEN RMB 2 EXPECTED RETURNED VALUE OF 2
SCBLK:RDBUF FDB SCANNEDCOUNT
# FILENAME CHARACTERS
PROCESSED
SCBLK:RDLEN FDB 2 SIZE OF RDBUF
SCBLK:END EQU *
The WAIT flag must be zero. The first parameter byte is the
channel number desired. The second parameter byte is not used.
The Write Buffer (WRBUF) contains the filename (including device
name, etc.) desired, WRLEN contains the number of bytes in the
filename.
The OPEN SYSCALL checks the channel to ensure that it is not open
already. If not open, the filename is scanned to determine the
selected device (default to DISK: if no device) and a filename on
that device. The number of bytes scanned is returned as a 2 byte
value in the buffer selected by RDBUF; the rest of the bytes in
WRBUF are ignored. Leading blanks on the filename are ignored,
but are included in the scanned count. (Note: All SYSCALLs that
deal with file or device names return the number of bytes of the
filename scanned as the result. The entire filename is scanned
even if an error occurs.) The device is searched for the file if
it is a directoried device, and an error issued if not found. If
the device is not a directoried device, the device is simply
opened. The file is positioned so that a subsequent read will
read the zeroth (first) byte of the file.
(Some) possible errors are:
Bad File Name
No Such File
Can't Open, Must Create
No Such Device
Channel Busy
COPYRIGHT (C) 1978 47 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION V: SYSCALLS - IMPLEMENTATION
SYSCALL:CREATE
This SYSCALL is used to CREATE a new file and establish an
association between an I/O channel number and the new file. It is
also used when a program will do output only to a device (such as
a line printer; the philosophy is that such output is a new
file).
CREATE SYSCALL Block Format:
SCBLK:OPCODE FCB SYSCALL:CREATE
SCBLK:WLEN FCB SCBLK:END-SCBLK:OPCODE
SCBLK:PARAMS FCB CHANNELNO,IGNORED
SCBLK:WRBUF FDB FILENAMESTRING
SCBLK:WRLEN FDB FILENAMELENGTH
SCBLK:RPLEN RMB 2 EXPECTED RETURNED VALUE OF 2
SCBLK:RDBUF FDB SCANNEDCOUNT
SCBLK:RDLEN FDB 2 SIZE OF SCANNED COUNT
SCBLK:END EQU *
The WAIT flag must be zero. The first parameter byte is the
desired channel number; the second parameter byte is ignored.
WRBUF points to the filename (device name) of the new file.
Like SYSCALL:OPEN, RDBUF points to a 2 byte area in which the
number of bytes of the filename scanned by SDOS is placed on
completion of the SYSCALL.
If a disk file is specified and there is an old file, the old
file must not write protected or an error will occur and the new
file will not be created (nor will the channel be opened).
Otherwise, the new file is created, and the channel is opened.
If an old file does exist, an OPEN SYSCALL executed after the
CREATE, looking for the same file, will find the old file. If
the system crashes before the new file is closed, the old file
will be unaffected in any way. Even after the new file is closed,
channels still open to the old file will not notice any
difference. When the last channel to the old file is closed, it
is deleted and the space for the old file is returned to free
disk space. Effectively, a CREATE includes an "implied" delete
of the older version of the file.
The file is positioned so that a write will write its first byte
in byte #0 of the file.
Possible errors are:
File is Delete Protected
File is Write Protected
No Such Device
Channel is Busy
Bad Filename
File is Being Created
COPYRIGHT (C) 1978 48 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION V: SYSCALLS - IMPLEMENTATION
SYSCALL:CLOSE
The CLOSE SYSCALL is used to break the association between an I/O
channel number and a file.
CLOSE SYSCALL Format:
SCBLK:OPCODE FCB SYSCALL:CLOSE
SCBLK:WLEN FCB SCBLK:END-SCBLK:OPCODE
SCBLK:PARAMS FCB CHANNELNO,IGNORED
SCBLK:END EQU *
This SYSCALL frees the I/O channel to be opened to another file,
and causes the CLOSE entry point of a device driver to be called.
Action of the driver is driver-dependent.
If the channel was open to a disk file, then changes to the file
size, protection, and other characteristics are updated on the
disk (not before). If the disk file is newly created, and is not
replacing another by the same name, closing will make its name
appear in the directory. If the file is newly created, and it is
a replacement for a file that already exists (i.e., one by the
same name), then the new file will replace the old in the
directory, and the disk space allocated to the old file will be
returned to free space as soon as no other I/O channels remain
open to the old version of the file.
Possible errors are:
Illegal Channel Number
Channel is Already Closed
COPYRIGHT (C) 1978 49 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION V: SYSCALLS - IMPLEMENTATION
SYSCALL:RENAME
The RENAME Syscall is used to change the name of a file. The
file must be open on some channel; it must not be a newly created
file, and no file (new or old) having the new name must exist.
RENAME SYSCALL Format:
SCBLK:OPCODE FCB SYSCALL:RENAME
SCBLK:WLEN FCB SCBLK:END-SCBLK:OPCODE
SCBLK:PARAMS FCB CHANNELNUMBER,IGNORED
SCBLK:WRBUF FDB NEWFILENAME
SCBLK:WRLEN FDB NEWFILENAMELENGTH
SCBLK:RPLEN RMB 2 EXPECTED RETURNED VALUE OF 2
SCBLK:RDBUF FDB SCANNEDCOUNT
SCBLK:RDLEN FDB 2
SCBLK:END EQU *
The SYSCALL format is identical to that of an OPEN syscall;
parameters and results are passed the same way.
This SYSCALL affects nothing except the name of the file.
RENAMEing a disk file to its own name is legal, and can speed up
later OPENs of that file since a rename causes the file name to
be re-hashed into the directory. Refer to hash-lookup
description of files.
Possible errors are:
Channel Not Open
Bad File Name
File is Being Created
Can't Rename to a Different Device
File is Delete Protected
File is Write Protected
New File Already Exists
COPYRIGHT (C) 1978 50 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION V: SYSCALLS - IMPLEMENTATION
SYSCALL:DELETE
The DELETE SYSCALL is used to delete a file from a disk device.
DELETE SYSCALL Format:
SCBLK:OPCODE FCB SYSCALL:DELETE
SCBLK:WLEN FCB SCBLK:END-SCBLK:OPCODE
SCBLK:PARAMS FCB IGNORED,IGNORED
SCBLK:WRLEN FDB FILENAMEBUFFER
SCBLK:WRBUF FDB FILENAMESIZE
SCBLK:RPLEN RMB 2 EXPECTED RETURNED VALUE OF 2
SCBLK:RDBUF FDB REPLYBUFFER
SCBLK:RDLEN FDB REPLYBUFFERSIZE
SCBLK:END EQU *
The file specified on the specified device is deleted (this
syscall is not legal for devices which do not have directories).
No I/O channel is specified or needed. If the deletion is
successful, the directory entry is removed so that the file can
no longer be opened. If the file is open on some I/O channel
when the delete SYSCALL is issued, then the SYSCALL will complete
successfully, but the file will not actually be deleted until the
last channel open to the file is closed (in fact, the file may
actually be allocated more disk space via the other channel!).
The reply buffer is loaded with the actual length of the filename
(see SYSCALL:OPEN).
Possible errors are:
No Such File
File is Delete Protected
COPYRIGHT (C) 1978 51 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION V: SYSCALLS - IMPLEMENTATION
SYSCALL:LOAD
The LOAD Syscall is used to load an overlay program segment into
memory, without transferring control.
LOAD SYSCALL Format:
SCBLK:OPCODE FCB SYSCALL:LOAD
SCBLK:WLEN FCB SCBLK:END-SCBLK:OPCODE
SCBLK:PARAMS FCB IGNORED,IGNORED
SCBLK:WRBUF FDB FILENAMESTRING
SCBLK:WRLEN FDB FILENAMELENGTH
SCBLK:RPLEN RMB 2 EXPECTED RETURNED VALUE OF 4
SCBLK:RDBUF FDB COUNTANDSTART
SCBLK:RDLEN FDB 4 MINIMUM REQUIRED
SCBLK:END EQU *
No channel number need be specified.
The filename specified is opened on a special system channel, and
checked to see if a load format file is given (first byte must be
ASCII "S" or Hex :01). If so, the file contents are loaded into
memory as specified by the load records (see LOADER FORMATs).
Scatter loading (loading into non-contiguous parts of memory) is
possible. Upon completion of the loading process, control is
returned to the user, and the file is closed.
The results returned in the reply buffer are 2 bytes of filename
count (the first 2 bytes; see SYSCALL:OPEN) and 2 bytes of start
address (the second 2) as specified by the load records.
Load records which would load on top or above SDOS cause the load
to be aborted.
A load record whose address conflicts with that of the reply
buffer may be damaged; conversely, the reply may be garbled.
Loading into the area used by the stack may cause SDOS to crash.
SDOS does not check for this.
Errors while loading cause the error exit of the Syscall to be
taken.
In any case, on completion of the load, the file is closed.
Attempting to LOAD a program with a different encryption key is
illegal.
COPYRIGHT (C) 1978 52 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION V: SYSCALLS - IMPLEMENTATION
Possible errors are:
Not a Load File
No Such File
EOF Hit
Checksum Error
Load Record Format Error
Bad Filename
Bad Filename Size
COPYRIGHT (C) 1978 53 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION V: SYSCALLS - IMPLEMENTATION
SYSCALL:CHAIN
The CHAIN Syscall is used to load and transfer control to an
overlay or program segment.
CHAIN SYSCALL Format:
SCBLK:OPCODE FCB SYSCALL:CHAIN
SCBLK:WLEN FCB SYSCALL:END-SYSCALL:OPCODE
SCBLK:PARAMS FCB IGNORED,IGNORED
SCBLK:WRBUF FDB FILENAMESTRING
SCBLK:WRLEN FDB FILENAMELENGTH
SCBLK:RPLEN RMB 2 EXPECTED RETURNED VALUE OF 4
SCBLK:RDBUF FDB COUNTANDSTART
SCBLK:RDLEN FDB 4 MINIMUM REQUIRED
SCBLK:END EQU *
CHAIN first closes all I/O channels except channel 0. It then
causes all modified disk sectors in the LRU queue to get written
back to the disk to ensure validity of disk contents, and then
performs exactly the same function as SYSCALL:LOAD. If an error
occurs, control will return to the caller only if no data has
been loaded into the user space. The most common causes of this
are the following errors:
Bad File Name
Bad File Name Size
File Not Found
Not a Load File
No Start Address
All other errors will cause an implied SYSCALL:ERROREXIT to be
executed (because of the possibility of the program issuing the
CHAIN being overlayed).
On successful completion of the load, control will be transferred
to the start address of the file. The stack pointer is set to
the contents of $FC,$FD, minus 1 (see SDOS Memory Map).
Chaining to a program with a different encryption key will cause
the user space to be zeroed before control is transferred.
COPYRIGHT (C) 1978 54 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION V: SYSCALLS - IMPLEMENTATION
SYSCALL:CREATELOG
There are occasions on which a record of a terminal session would
be very convenient, such as when a purported bug arises, or when
an example is required. This copy can be laboriously constructed
by hand, or it can be made automatically via a CREATELOG syscall.
CREATELOG SYSCALL Format:
SCBLK:OPCODE FCB SYSCALL:CREATELOG
SCBLK:WLEN FCB SCBLK:END-SCBLK:OPCODE
SCBLK:PARAMS FCB CHANNELNO,IGNORED
SCBLK:WRBUF FDB FILENAMESTRING
SCBLK:WRLEN FDB FILENAMELENGTH
SCBLK:RPLEN RMB 2 EXPECTED RETURNED VALUE OF 2
SCBLK:RDBUF FDB SCANNEDCOUNT
SCBLK:RDLEN FDB 2 SIZE OF SCANNED COUNT
SCBLK:END EQU *
CREATELOG creates a new file (just like the CREATE syscall), but
no channel number is given (SDOS reserves a special, unnumbered,
I/O channel specifically for this purpose). It returns file name
size information in the same manner as OPEN.
There is no way for a user program to explicitly read or write
data to the log channel; all I/O through the log channel is done
invisibly by SDOS. Essentially, any data written via a Write
ASCII to channel 0 (the control channel) is also copied to the
log file. Data read via a Read ASCII on channel 0 is also
written to the log file. In this way, a complete copy of console
sessions (carried on through the control channel) is recorded in
the log file for later retrieval. The writes to the log file are
done only when the log file is open (has been created).
STATUS and CONTROL syscalls are re-directed from channel 0 to the
log channel when it is open, so that status information read from
channel 0 may not actually be that of channel 0. All other
channel-oriented syscalls (in particular, Read Binary and Write
Binary) are not affected by the log channel. If the log channel
is not open, it has no effect whatsoever on channel 0 operations.
The log file will not be found in the directory until it is
closed (via CLOSELOG). Like any CREATEd disk file, PROGRAM KILL
(^C^C) automatically closes the log file. This Syscall is used
mainly by SDOSCOMMANDS to implement the LOG and DO commands.
A program can set up a DO file by:
1) Verifying that the DO file exists by OPENing it on some
channel.
2) CLOSEing channel 0
3) OPENing channel 0 to the DO file
4) CREATELOG on the "CONSOLE:" device
COPYRIGHT (C) 1978 55 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION V: SYSCALLS - IMPLEMENTATION
Further input will come from the DO file. If an error occurs
during step 2 or 3, the program must reOPEN channel 0 to the
CONSOLE: or no further console I/O can occur.
Possible errors are:
Channel Already Open
Illegal File Name
No Disk Space
COPYRIGHT (C) 1978 56 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION V: SYSCALLS - IMPLEMENTATION
SYSCALL:CLOSELOG
This Syscall is used to close the special log I/O channel (see
SYSCALL:CREATELOG).
CLOSELOG SYSCALL Format:
SCBLK:OPCODE FCB SYSCALL:CLOSELOG
SCBLK:WLEN FCB SCBLK:END-SCBLK:OPCODE
SCBLK:END EQU *
This Syscall performs the same operation as a CLOSE Syscall on
the Log channel. No channel number or other parameters are
needed.
Possible errors are:
Channel Not Open
COPYRIGHT (C) 1978 57 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION V: SYSCALLS - IMPLEMENTATION
SYSCALL:DISKDEFAULT
This SYSCALL is used to select which disk is default-selected
when a file name with no explicit disk device indentification is
given.
DISKDEFAULT SYSCALL Format:
SCBLK:OPCODE FCB SYSCALL:DISKDEFAULT
SCBLK:WLEN FCB SCBLK:END-SCBLK:OPCODE
SCBLK:PARAMS FCB IGNORED,IGNORED
SCBLK:WRBUF FDB FILENAMESTRING
POINTS TO FIRST BYTE
SCBLK:WRLEN FDB FILENAMELENGTH
IN BYTES
SCBLK:RPLEN RMB 2 EXPECTED RETURNED VALUE OF 2
SCBLK:RDBUF FDB SCANNEDCOUNT
# FILENAME CHARS PROCESSED
SCBLK:RDLEN FDB 2 SIZE OF RDBUF
SCBLK:END EQU *
DISKDEFAULT parses the device name, and ensures that the device
name is a valid disk device name (filenames passed with the
device name are not examined). The specified disk will then be
used whenever a filename with no device specification is
encountered by a filename SYSCALL.
No channel number is needed.
Data is returned in the same form as an OPEN syscall.
After a successful return, the device name DISK: refers to the
default disk.
Possible errors are:
Device is Not a Disk
COPYRIGHT (C) 1978 58 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION V: SYSCALLS - IMPLEMENTATION
SYSCALL:READA
This SYSCALL is used to read (ASCII) textual data from a file.
The file must be open on some I/O channel.
READA SYSCALL Block Format:
SCBLK:OPCODE FCB SYSCALL:READA
SCBLK:WLEN FCB SCBLK:END-SCBLK:OPCODE
SCBLK:PARAMS FCB CHANNELNUMBER,LMFLAG
SCBLK:WRBUF RMB 2
SCBLK:WRLEN FDB 0
(MINIMIZES PROCESSING TIME)
SCBLK:RPLEN RMB 2
ACTUAL NUMBER BYTES READ
SCBLK:RDBUF FDB READBUFFER
WHERE TO PUT DATA
SCBLK:RDLEN FDB READBUFSIZE
MAXIMUM NUMBER BYTES TO READ
SCBLK:END EQU *
READA will read the specified number of bytes into the read
buffer from the file open on the specified channel, and advance
the file position past the number of bytes examined, subject to
the following conditions: the file has enough bytes, and no
errors occur during the read. Nulls (:00), line feeds (:0A), and
rubouts (:7F) are deleted from the stream of characters read from
the file/device.
Bit 7 of all characters read via SYSCALL:READA is zeroed. Other
characters may be removed from the input stream by the particular
device driver in use.
The column count for this channel is updated for each byte placed
in the read-back buffer, according to the following rule: a
printing character (:20-:7E) causes the column count to be
incremented. CR (:0D) causes the column count to be zeroed. All
other codes leave the count alone. The column count can be read
by a SYSCALL:STATUS call.
If LMFLAG is non-zero, the read proceeds in single line mode. If
a CR (:0D) character is encountered, it will be placed in the
read buffer, and the read will be terminated. LMFLAG=0 prevents
CRs from terminating the read, so the buffer will be filled.
SCBLK:RPLEN is set to the actual number of bytes read, even if an
error (such as End of File) occurs.
The WRBUF is ignored if supplied.
COPYRIGHT (C) 1978 59 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION V: SYSCALLS - IMPLEMENTATION
All data read from channel 0 via a READA is copied (via WRITEA)
to the log file if the log channel has been opened. A READA with
LMFLAG=1 directed at channel 0 will be completed from the
CONSOLE: device if a complete line cannot be read because of an
EOF error (this finishes a partial line from a DO file).
The overhead for doing a single-byte SYSCALL:READA is fairly
high; larger buffers will cause this overhead to be divided
between all the bytes transferred. Large buffers can achieve a
40 to 1 speedup over single byte transfers. Such speed ups are
also typical for SYSCALL:WRITEA, SYSCALL:WRITEB, and
SYSCALL:READB.
If the SYSCALL block length is 18 bytes or more, then the first
four bytes of the extension hold a file position, and an implied
positioning operation is performed BEFORE the actual read takes
place. Compared to a CC:POSITION call followed by a
SYSCALL:READA, a combined position/read operation is considerably
more efficient in a network environment, so it is encouraged.
Similar efficiencies accrue for combined position/write
operations.
An EOF hit error will occur: (1) if not in line mode and the
buffer cannot be filled; (2) if in line mode and no CR character
is encountered before EOF.
An end-of-file condition (which can be sensed via a
SYSCALL:STATUS) is set whenever a read of the last data byte of
the file occurs.
Possible errors are:
Channel Not Open
EOF Hit
COPYRIGHT (C) 1978 60 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION V: SYSCALLS - IMPLEMENTATION
SYSCALL:READB
This SYSCALL is used to read binary data from a file. The file
must be open on some I/O channel.
READB Syscall Block format
SCBLK:OPCODE FCB SYSCALL:READB
SCBLK:WLEN FCB SCBLK:END-SCBLK:OPCODE
SCBLK:PARAMS FCB CHANNELNUMBER,IGNORED
SCBLK:WRBUF RMB 2
SCBLK:WRLEN FDB 0
(MINIMIZES PROCESSING TIME)
SCBLK:RPLEN RMB 2
ACTUAL NUMBER BYTES READ
SCBLK:RDBUF FDB READBUFFER
WHERE TO PUT DATA
SCBLK:RDLEN FDB READBUFSIZE
MAXIMUM NUMBER BYTES TO READ
SCBLK:END EQU *
READB will read the specified number of bytes into the read
buffer from the file opened on the specified I/O channel, and
advance the file position by the number of bytes actually read.
In order for the specified buffer to be completely filled, the
distance between the current file position and the end of the
file must be greater or equal to the buffer size, and no errors
may occur during the read. The data bytes read from the file are
not changed in any way.
SCBLK:RPLEN is set to the actual number of data bytes read
(usually equal to the buffer size).
Using a READB SYSCALL causes the column count for the specified
channel to be zeroed.
SCBLK:WRBUF is ignored if supplied; however, its length should be
specified as zero to minimize SYSCALL processing time.
An EOF error will occur if the read request is not completely
satisfied (i.e., the buffer was not filled).
The overhead for doing single-byte reads is high; long buffers
will distribute this overhead so that the average time per byte
is some 40 times faster than single byte reads.
If the SYSCALL block length is 18 bytes or more, then the first
four bytes of the extension hold a file position, and an implied
positioning operation is performed BEFORE the actual read takes
place.
COPYRIGHT (C) 1978 61 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION V: SYSCALLS - IMPLEMENTATION
Possible errors are:
Channel Not Open
EOF Hit
Disk Read Error
Device Not Ready
Device Timed Out
COPYRIGHT (C) 1978 62 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION V: SYSCALLS - IMPLEMENTATION
SYSCALL:WRITEA
WRITEA is used to Write ASCII data to a file. The primary
difference between this and WRITEB is that the column count gets
updated, and certain output editing is done.
WRITEA SYSCALL Format:
SCBLK:OPCODE FCB SYSCALL:WRITEA
SCBLK:WLEN FCB SCBLK:END-SCBLK:OPCODE
SCBLK:PARAMS FCB CHANNELNUMBER,IGNORED
SCBLK:WRBUF FDB WRITEDATABUFFER
SCBLK:WRLEN FDB NUMBEROFBYTESTOWRITE
SCBLK:END EQU *
The data bytes in the WRITEDATABUFFER are copied to the file open
on the specified I/O channel. The file position is advanced by
NUMBEROFBYTESTOWRITE. Disk files are extended automatically, if
necessary, to make more room and the file size is changed. The
column count for this I/O channel is changed according to the
same rules as specified by SYSCALL:READA. The output stream may
be modified by the device driver; a CRT driver will typically add
LF (:0A) and nulls (idle characters) after a CR (:0D) character.
SDOS conventions dictate that LF characters are superflous in the
presence of CR characters. To write a line of text to a file (or
device), terminating it with a CR is sufficient.
An EOF condition will happen if the last data byte of the file is
overwritten, and/or the file was extended in order to accomodate
the write request. An EOF condition on a WRITE to a disk does
not cause an error.
Data written via WRITEAs to channel 0 is also sent (via WRITEAs)
to the log channel if the log channel is open.
Multi-byte writes are more efficient than single-byte writes.
No read-back buffer is required.
If the SYSCALL block length is 18 bytes or more, then the first
four bytes of the extension hold a file position, and an implied
positioning operation is performed BEFORE the actual read takes
place.
Possible errors are:
Channel Not Open
Disk Space Exhausted (for disk files)
Disk Write Error
Device Timed Out
Device Not Ready
COPYRIGHT (C) 1978 63 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION V: SYSCALLS - IMPLEMENTATION
SYSCALL:WRITEB
The WRITEB SYSCALL is used to write binary data to a file. The
stream of data bytes is copied directly to the file or device
without any change to its content.
WRITEB SYSCALL Format:
SCBLK:OPCODE FCB SYSCALL:WRITEB
SCBLK:WLEN FCB SCBLK:END-SCBLK:OPCODE
SCBLK:PARAMS FCB CHANNELNUMBER,IGNORED
SCBLK:WRBUF FDB WRITEDATABUFFER
SCBLK:WRLEN FDB NUMBEROFBYTESTOWRITE
SCBLK:END EQU *
The data bytes in the specified buffer are copied without change
to the file that is open on the specified I/O channel. The file
position is advanced by NUMBEROFBYTESTOWRITE. If necessary, a
disk file is extended automatically to make more room, and the
file size is adjusted accordingly. The column count for this
channel is zeroed.
Multi-byte writes are more efficient than single-byte writes.
An EOF condition will happen if the last data byte of the file is
overwritten, and/or the file was extended in order to accomodate
the write request.
No read-back buffer is required.
If the SYSCALL block length is 18 bytes or more, then the first
four bytes of the extension hold a file position, and an implied
positioning operation is performed BEFORE the actual read takes
place.
Possible errors are:
Channel Not Open
Disk Space Exhausted
Illegal Device Operation
(for line-printer-like devices)
Disk Write Error
Device Not Ready
COPYRIGHT (C) 1978 64 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION V: SYSCALLS - IMPLEMENTATION
SYSCALL:CONTROL
This SYSCALL is used to control or modify the operation of a
device/file. The first parameter byte selects the I/O channel
number; the second parameter byte determines the actual operation
performed (rewind, eject, dismount, etc.) so this SYSCALL
actually represents an entire class of operations. A control
operation may be issued only to an I/O channel that is already
OPEN.
If logging is active, and a CONTROL operation is issued for
channel 0, the control operation is actually applied to the log
channel.
CONTROL SYSCALL Block Format:
SCBLK:OPCODE FCB SYSCALL:CONTROL
SCBLK:WLEN FCB SCBLK:END-SCBLK:OPCODE
SCBLK:PARAMS FCB CHANNELNUMBER
FCB CC:controlcode
SCBLK:WRBUF FDB CONTROLPARAMETERS
SCBLK:WRLEN FDB NUMBEROFCONTROLBYTES
SCBLK:END EQU *
SDOS divides device control operations into two classes: common,
and device specific. Common control operations are those
operations for which all devices generally have a capability.
Currently only the following operations fit in the category of
common:
CC:POSITION and CC:DUMPBUFFERS
All other control operations are device specific and are
documented with the specific device driver. Typical
device-specific operations include: select echo mode, set tabs,
and dismount disk.
The format of the CONTROL SYSCALLs varies because different
device operations require different parameters. In particular,
most CONTROL SYSCALLs do not require a write buffer. For
specific formats, refer to the device driver descriptions.
COPYRIGHT (C) 1978 65 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION V: SYSCALLS - IMPLEMENTATION
CC:POSITION
CC:POSITION is used to select the next byte of a file to be
read/written. A 4 byte, 2's complement integer is used to select
the byte index into a (disk) file (it can also be used as a
record number, a port number, a screen position, or whatever is
appropriate for the device). The number must be positive (i.e.,
the sign bit must be zero) or an error will result. Following a
CC:POSITION command, further read/writes start from the specified
file position and advance sequentially. A "rewind" is obtained
by specifying a zero for the value of the 4 byte integer.
Setting a file position which is equal or greater than the size
of the (disk) file will cause an EOF condition to occur and cause
an error.
No reply is given for this syscall.
Alphanumeric CRTs are an interesting special case. It is
standard for SDOS CRT drivers to interpret the positioning
parameter as cursor positioning data. The parameter is
interpreted as 2 bytes of zero, 1 byte to specify the screen row
number (zero being the top screen row) and 1 byte of column
number (zero being the leftmost column). Given R for row and C
for column, the value of the positioning parameter is then
Row*256+Column. In this way, cursor positioning on screens is
generalized to work for a broad variety of CRT displays.
CC:POSITION SYSCALL Format:
SCBLK:OPCODE FCB SYSCALL:CONTROL
SCBLK:WLEN FCB SCBLK:RPLEN-SCBLK:OPCODE
SCBLK:PARAMS FCB CHANNELNUMBER,CC:POSITION
SCBLK:WRBUF FDB POSITIONDATA
SCBLK:WRLEN FDB 4
.
.
.
POSITIONDATA RMB 4 NEED FILE POSITION
For CRTs, POSITIONDATA has the following form:
POSITIONDATA FCB 0,0
SCREENROW RMB 1
SCREENCOL RMB 1
.
.
.
COPYRIGHT (C) 1978 66 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION V: SYSCALLS - IMPLEMENTATION
CC:DUMPBUFFERS
CC:DUMPBUFFERS is used to force an I/O device to dump any buffers
it may still have filled. CC:DUMPBUFFERS is particularly useful
in transaction oriented programs which need to force all disk
file changes back to the disk. No parameters are required;
operation is device specific.
CC:DUMPBUFFERS Format:
SCBLK:OPCODE FCB SYSCALL:CONTROL
SCBLK:WLEN FCB SCBLK:WRBUF-SCBLK:OPCODE
SCBLK:PARAMS FCB CHANNELNUMBER,CC:DUMPBUFFERS
COPYRIGHT (C) 1978 67 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION V: SYSCALLS - IMPLEMENTATION
SYSCALL:STATUS
The STATUS Syscall is used to read file or device-dependent
descriptive data about that file or device (as opposed to reading
data from the file or device itself). This syscall is really an
entire group of operations; a parameter byte selects the
device-specific data to read. A STATUS Syscall must reference an
open I/O channel. Like READA and READB, the data is read back
into the reply buffer.
If a STATUS syscall is issued for channel 0, and logging is
active, the status read back will be that of the log channel, not
channel 0.
STATUS SYSCALL Block Format:
SCBLK:OPCODE FCB SYSCALL:STATUS
SCBLK:WLEN FCB SYSCALL:END-SYSCALL:OPCODE
SCBLK:PARAMS FCB CHANNELNO,SC:statuscode
SCBLK:WRBUF FDB IGNORED
SCBLK:WRLEN FDB IGNORED
SCBLK:RPLEN FDB CHANGED
SCBLK:RDBUF FDB STATUSBUFFER
SCBLK:RDLEN FDB STATUSCODEDEPENDENTLENGTH
There are two classes of STATUS requests: those standard across
all devices, and those specific to the particular device type.
The following status information is obtainable from most devices:
SC:GETPOS
SC:GETCOL
SC:GETEOF
SC:GETFILESIZE
SC:GETTYP
SC:GETPARAMS
All other status-reading operations are device specific and are
detailed under the specific device drivers.
SC:GETPOS is used to read the current position in a file, i.e.,
if one executes a CC:POSITION command, an SC:GETPOS will
read back the same value as the positioning value given for
the CC:POSITION. SC:GETPOS always reads back four data
bytes (the interpretation of these bytes is up to the device
driver).
SC:GETCOL reads back the print position of a simulated print head
on a particular I/O channel (see READA, WRITEA syscalls). 0
means "no characters printed on this line." Only one data
byte is returned.
COPYRIGHT (C) 1978 68 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION V: SYSCALLS - IMPLEMENTATION
SC:GETEOF returns a single-byte flag indicating whether the I/O
channel has positioned, read or written past the last data
byte in the file. A non-zero returned byte indicates past
or at end of file; zero means more data can be read from the
file before the end of file is encountered.
SC:GETFILESIZE returns the size of the file (in bytes). The size
is returned as a four byte integer, appropriate for use in a
positioning command (this is convenient for appending data
to the end of a file). This is normally only implemented on
disk files.
SC:GETTYP returns a single-byte device type code, which places a
device into one of the following classes: FILE, DISK, TAPE,
DIRECTORIED TAPE, CONSOLE, LINEPRINTER, SERIALOUT, SERIALIN,
PARALELLOUT, PARALELLIN, DUMMY. Other device types may be
added as needed.
SC:GETPARAMS reads device class-specific parameters. To know
what kind of data to expect for a reply, the program must
first determine the device type (using SC:GETTYP).
Currently defined device-specific parameters are:
Disk FILE:
DVDAT:NSPC Number of Sectors Per Cluster
DVDAT:NBPS Sector Size in Bytes
The maximum file size may be computed as:
(NBPS*NSPC/2-1)*NBPS*NSPC
DISK Device:
DVDAT:NBPS Number of Bytes Per Sector
DVDAT:NSPT Number of Sectors Per Track
DVDAT:NTPC Number of Tracks Per Cylinder
DVDAT:NCYL Number of Cylinders
CONSOLE:
DVDAT:WIDTH In Characters
DVDAT:DEPTH Screen or Page Depth in Lines, or
0 If Continuous Form Paper
PRINTER:
DVDAT:WIDTH In Characters
DVDAT:DEPTH Page Depth in Lines
COPYRIGHT (C) 1978 69 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION V: SYSCALLS - IMPLEMENTATION
SYSCALL:WAITDONE
This system call is used to wait for an operation initiated on an
I/O channel to complete.
This SYSCALL and the parallel initiation feature ARE NOT
IMPLEMENTED IN FINAL FORM. It currently is a no-operation, and
is provided to allow programs to be coded as though parallel
SYSCALLS were implemented.
WAITDONE SYSCALL Format:
SCBLK:OPCODE FCB SYSCALL:WAITDONE
SCBLK:WLEN FCB SCBLK:END-SCBLK:OPCODE
SCBLK:PARAMS FCB CHANNELNUMBER
SCBLK:END EQU *
If any parallel SYSCALL (a syscall with the WAIT flag = "don't
wait") was issued on the specified I/O channel, WAITDONE delays
the execution of the user program until that operation is
complete. Error status returned is that of the parallel SYSCALL
returned as though the parallel SYSCALL had the WAIT flag reset
when executed.
A second WAITDONE issued on an I/O channel, without any other
intervening SYSCALLS, returns immediately with no error possible,
so multiple WAITDONEs on a channel may be performed without
conflicts arising.
COPYRIGHT (C) 1978 70 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION V: SYSCALLS - IMPLEMENTATION
SYSCALL:EXIT
This syscall is used by a user program to pass control to the
DEFAULTPROGRAM. It is an indication that the user program
completed execution successfully.
EXIT SYSCALL Format:
SCBLK:OPCODE FCB SYSCALL:EXIT
SCBLK:WLEN FCB SCBLK:END-SCBLK:OPCODE
SCBLK:END EQU *
There are no parameters, and control does not return to the user
program.
All I/O channels except channel 0 are CLOSEd.
SDOS does a quick checksum on itself after an EXIT is completed,
and reports an error if it thinks memory is starting to fail;
otherwise, no errors are possible.
This syscall is functionally identical to SYSCALL:ERROREXIT with
an error code of 0.
COPYRIGHT (C) 1978 71 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION V: SYSCALLS - IMPLEMENTATION
SYSCALL:ERROREXIT
This syscall is used by a user program to cease execution
abnormally, and notify the operator the reason for stopping.
ERROREXIT SYSCALL Format:
SCBLK:OPCODE FCB SYSCALL:ERROREXIT
SCBLK:WLEN FCB SCBLK:END-SCBLK:OPCODE
SCBLK:PARAMS FDB ERRORCODE
SCBLK:END EQU *
The error code is displayed on the console as either
Error <CR>
or
<TEXT MESSAGE> <CR>
depending on whether SDOS can successfully extract the
corresponding text message from the ERRORMSGS.SYS file on drive 0
(see SYSCALL:DISPERROR). If the error code is 0, a message is
not displayed. Control is then passed to the DEFAULTPROGRAM
(usually the SDOS command interpreter, which can interrogate and
conditionally branch on the error code if a DO file is being
processed). No error is possible.
This syscall is intended to be used as very simple error handling
in user programs.
COPYRIGHT (C) 1978 72 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION V: SYSCALLS - IMPLEMENTATION
Example:
LDX #PARAMETERLISTADDRESS
JSR SYSCALL$
BCS OOPS B/ ERROR
.
.
.
OOPS CPX #ERR:...
BEQ ICANHANDLEIT1
CPX #ERR:...
BEQ ICANHANDLEIT2
.
.
.
IGIVEUP STX ERROREXIT+SCBLK:PARAMS
LDX #ERROREXIT
JSR SYSCALL$
BCS * CAN'T GET HERE!
JMP *
ERROREXIT FCB SYSCALL:ERROREXIT
FCB 4 SCBLK:WLEN
FDB 0 SCBLK:PARAMS
COPYRIGHT (C) 1978 73 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION V: SYSCALLS - IMPLEMENTATION
SYSCALL:SETERROR
This syscall, coupled with SYSCALL:DISPERROR, is used by a
program to display the reason a SYSCALL failed.
SETERROR SYSCALL Format:
SCBLK:OPCODE FCB SYSCALL:SETERROR
SCBLK:WLEN FCB SCBLK:END-SCBLK:OPCODE
SCBLK:PARAMS FDB ERRORCODE
SCBLK:END EQU *
The user program first stores an error code into the syscall
block, and then issues the syscall. The error code has now been
stored in SDOS for use by the DISPERROR and GETERROR syscalls.
Normally, a SETERROR is followed by a DISPERROR, so that a text
display of the error cause occurs. Since control returns to the
user program, this is an effective procedure for displaying the
cause of an error without EXITing to the DEFAULTPROGRAM.
A GETERROR syscall can be used to later retrieve the error code.
A subsequent EXIT or ERROREXIT syscall will change the code set
by SETERROR.
COPYRIGHT (C) 1978 74 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION V: SYSCALLS - IMPLEMENTATION
SYSCALL:GETERROR
This syscall is used to retrieve an error code given to SDOS by
EXIT, ERROREXIT, or SETERROR syscalls.
GETERROR SYSCALL Format:
SCBLK:OPCODE FCB SYSCALL:GETERROR
SCBLK:WLEN FCB SYSCALL:END-SCBLK:OPCODE
SCBLK:PARAMS FDB IGNORED
SCBLK:WRBUF FDB IGNORED
SCBLK:WRLEN FDB IGNORED
SCBLK:RPLEN FDB 2 EXPECTED RETURNED VALUE
SCBLK:RDBUF FDB ERRORCODEBUF
WHERE TO PUT ERROR CODE
SCBLK:RDLEN FDB 2 LENGTH OF 16 BIT ERROR
CODE
SCBLK:END EQU *
The 2 byte error code last given to SDOS is returned in the reply
buffer. No parameters other than the reply buffer discriptor are
necessary.
Possible errors are:
Syscall Length Too Short
Read-Back Buffer Too Short
COPYRIGHT (C) 1978 75 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION V: SYSCALLS - IMPLEMENTATION
SYSCALL:DISPERROR
The DISPERROR is used to display a text message corresponding to
the most recent error code given to SDOS by SYSCALL:EXIT,
SYSCALL:ERROREXIT, or SYSCALL:SETERROR.
DISPERROR SYSCALL Block Format:
SCBLK:OPCODE FCB SYSCALL:DISPERROR
SCBLK:WLEN FCB SCBLK:END-SCBLK:OPCODE
SCBLK:END EQU *
No parameters are needed.
Either
ERROR nnnnn <CR>
or
<TEXT FROM ERRORMSGS.SYS> <CR>
is displayed on channel 0. If the error code is 0, and error
message IS displayed (see SYSCALL:ERROREXIT for contrast). If
channel 0 is not open, SDOS automatically opens it to the
CONSOLE: device. SDOS gets the text message from the
ERRORMSGS.SYS file based on the error code. If SDOS cannot
retrieve the error message from the ERRORMSGS.SYS file, it
displays the simpler form, with nnnnn being the decimal
equivalent of the error code. No carriage return is output, so
that the user program may precede or append text to the error
message (such as ... AT LINE 100 for BASIC).
If an error occurs during the process of displaying the message,
SDOS will hang. The operator must re-boot. This can only occur
if SDOS cannot output to the CONSOLE:.
COPYRIGHT (C) 1978 76 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION V: SYSCALLS - IMPLEMENTATION
SYSCALL:KILLPROOF
This SYSCALL is used by an application which needs to perform a
long computation or large amounts of I/O without being killed by
the operator for correct operation. This situation occurs when
several files need to be updated in order to maintain data base
consistency.
KILLPROOF SYSCALL Block Format:
SCBLK:OPCODE FCB SYSCALL:KILLPROOF
SCBLK:WLEN FCB SCBLK:END-SCBLK:OPCODE
SCBLK:END EQU *
Normally, when the operator types ^C^C, SDOS kills the currently
running program and causes a forced ERROREXIT. This in turn
displays an appropriate message and causes the DEFAULTPROGRAM to
be loaded.
A double ^C is deferred if a SYSCALL:KILLPROOF has been executed
more recently than a KILLENABLE. Operation of the program
continues undisturbed until it executes SYSCALL:KILLENABLE, at
which point the program is stopped. The user program can still
sense operator attention requests via the ATTNCHECK syscall.
On EXIT, SDOS switches user programs back to KILLENABLEd mode
automatically, (actually, the DEFAULTPROGRAM is loaded as a
KILLENABLEd user program) so a set of programs invoked by a DO
file is killable. SYSCALL:CHAIN does not affect the KILLENABLE
status of a program, so a large program consisting of several
serially executed segments can operate entirely KILLPROOFed if
needed.
Possible errors are:
Syscall Block Too Short
COPYRIGHT (C) 1978 77 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION V: SYSCALLS - IMPLEMENTATION
SYSCALL:KILLENABLE
This syscall allows a program to be killed by the operator. It is
normally only used after a critical portion of a program, running
KILLDISABLEd, is finished executing.
KILLENABLE SYSCALL Block Format:
SCBLK:OPCODE FCB SYSCALL:KILLENABLE
SCBLK:WLEN FCB SCBLK:END-SCBLK:OPCODE
SCBLK:END EQU *
Executing this syscall will allow a program to be killed when the
operator types ^C^C (when the I/O package calls
SDOS:KILLPROGRAM). If a ^C^C (call to SDOS:KILLPROGRAM) has
occurred while the user program was KILLPROOF, execution of the
SYSCALL:KILLENABLE will cause the program to quit execution
immediately (i.e., control does not return to the user program in
this case).
SDOSCOMMANDS (the command interpreter) runs KILLENABLEd and loads
user programs initially KILLENABLEd. The user program must
execute a SYSCALL:KILLDISABLE syscall before performing any
critical operations (see SYSCALL:KILLDISABLE). CHAIN syscalls do
not affect the KILLENABLE status of the user program.
Possible errors are:
Program Killed
Syscall Block Too Short
COPYRIGHT (C) 1978 78 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION V: SYSCALLS - IMPLEMENTATION
SYSCALL:DEBUG
The DEBUG syscall is used to transfer control from a user program
to the local system debugger.
DEBUG SYSCALL Block Format:
SCBLK:OPCODE FCB SYSCALL:DEBUG
SCBLK:WLEN FCB SCBLK:END-SCBLK:OPCODE
SCBLK:END EQU *
No parameters are needed. Control is passed to the system
debugger's entry point. The actual method of passing control is
I/O package dependent. If there is no debugger, an ERROREXIT is
forced.
For systems with IDB (an SD assembly language debugging tool),
control is passed to the debugger in such a way that a
non-maskable interrupt appears to have occurred. EXIT from IDB
should be made via a "G" command. Using nnnnG to exit IDB and
return to the user program will also work. If a "G" command is
executed, control returns to the user program just beyond the
call, as with any other SYSCALL.
Possible errors are:
Syscall Too Short
No Debugger
COPYRIGHT (C) 1978 79 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION V: SYSCALLS - IMPLEMENTATION
SYSCALL:ATTNCHECK
This SYSCALL is used to determine if the operator would like to
interact with the user program (the operator normally signals
this by striking the ESCape key on his console; the actual
mechanism is determined by the I/O package).
ATTNCHECK SYSCALL Block Format:
SCBLK:OPCODE FCB SYSCALL:ATTNCHECK
SCBLK:WLEN FCB SCBLK:END-SCBLK:OPCODE
SCBLK:END EQU *
The ATTNCHECK syscall will return normally if no attention has
been requested since the last ATTNCHECK syscall. If the operator
has requested attention at least once since the last ATTNCHECK
SYSCALL was issued, then an error exit is taken with error code
ERR:ATTENTION.
There are no parameters and no returned results.
Note that depressing ESCape terminates line input mode from the
CONSOLE:; thus, with suitable program design, ESCape can be used
to get a program out of one interaction mode and into another
mode of interaction.
COPYRIGHT (C) 1978 80 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION V: SYSCALLS - IMPLEMENTATION
SYSCALL:ISCONSOLE
This system call is used to determine if channel zero is open to
the operator's console (this is needed because a STATUS syscall
will read back the status of the log channel if logging is
active).
This SYSCALL is used primarily by the command interpreter (when
an error is encountered) to determine whether or not a DO file
should be aborted.
ISCONSOLE SYSCALL Block Format:
SCBLK:OPCODE FCB SYSCALL:ISCONSOLE
SCBLK:WLEN FCB SCBLK:END-SCBLK:OPCODE
SCBLK:END EQU *
There are no parameters and no returned results. A normal exit
indicates that channel zero truly is open to the console device;
otherwise, an error exit occurs. The only possible errors are:
Channel is Not Open at All
Channel 0 is Open; But Not to the Console
COPYRIGHT (C) 1978 81 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION V: SYSCALLS - IMPLEMENTATION
SYSCALL:INTERLOCK
This SYSCALL enables multiple users to synchronize usage of one
or more resources (under single-user SDOS, these calls are null
operations). Each resource is represented by an INTERLOCK
"object" (note: future SDOS's will provide for many other
abstract object types), and the means of referencing that object
is called a CAPABILITY. The functions which the INTERLOCK
syscall will perform, include creating a capability to an
interlock object; destroying an existing capability to an
interlock object; reserving an object for exclusive use (also
known as "locking" an object), and, if the object has been
already locked, suspending execution of the caller until that
object has been released; releasing the object, allowing the next
suspended requestor to resume execution; conditionally locking an
object, returning an error if that object is already locked; and
releasing and removing all requests for an object. Note that
objects and capabilities do not "belong" to users (e.g., user 1
may create an interlock capability to an object named "MYFILE",
communicate that capability to user 2, and proceed to lock MYFILE
twice, thereby blocking himself; user 2 subsequently releases
MYFILE, which causes user 1 to be unblocked).
The function codes are expressed as 16-bit values in the PARAMS
field of the SYSCALL block; the specific functions and their
requirements are:
IC:CREATE
Create a capability to an interlock object.
ERR:NOSUCHOBJECT will be returned if the named object is
invalid.
WRBUF must contain an object name, and WRLEN must be 16. A
16-byte capability to the object will be returned in RDBUF.
IC:DESTROY
Destroy the usefulness of all capabilities to the named
interlock object. Release the object if it has been locked;
release all requests for the object; release all suspended
requestors of the object, with ERR:OBJECTDESTROYED. If the
capability is invalid, ERR:NOSUCHOBJECT will be returned.
WRBUF must contain a valid capability to the object, and
WRLEN must be 16.
COPYRIGHT (C) 1978 82 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION V: SYSCALLS - IMPLEMENTATION
IC:LOCK
Lock the named interlock object. If the object is already
locked, the caller's execution is suspended until the object
has been released. Under SDOS/MT 1.2, no more than 32
different objects may be locked at any one time
(implementation restriction); attempted violation of the
restriction will result in ERR:IMPLEMENTATIONLIMITREACHED.
If the capability is invalid, ERR:NOSUCHOBJECT will be
returned.
WRBUF must contain a valid capability to the object, and
WRLEN must be 16.
IC:RELEASE
Release the named interlock object. If the object has not
been previously locked, ERR:NOTLOCKED is returned. If the
capability is invalid, ERR:NOSUCHOBJECT will be returned.
WRBUF must contain a valid capability to the object, and
WRLEN must be 16.
IC:TEST
Lock the named interlock object. If the object is already
locked, no further action is taken and ERR:ALREADYLOCKED is
returned. If the capability is invalid, ERR:NOSUCHOBJECT
will be returned.
WRBUF must contain a valid capability to the object, and
WRLEN must be 16.
IC:RESET
Unconditionally release the named interlock object, if
locked; remove all requests for the object. Callers
suspended, awaiting use of the object, will be returned to
execution with ERR:LOCKRESET. If the capability is invalid,
ERR:NOSUCHOBJECT will be returned.
WRBUF must contain a valid capability to the object, and
WRLEN must be 16.
COPYRIGHT (C) 1978 83 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION V: SYSCALLS - IMPLEMENTATION
SYSCALL:DELAY
This system call is used by a program to wait for some fixed
period of time before continuing execution. This is useful on
multi-user systems when a periodic check is required, as no
resources are used while a program is waiting for the delay to
complete.
DELAY SYSCALL Block Format:
SCBLK:OPCODE FCB SYSCALL:DELAY
SCBLK:WLEN FCB SCBLK:END-SCBLK:OPCODE
SCBLK:PARAMS FCB DELAY ; in 1/60th second units
SCBLK:END EQU *
The delay is a 16 bit value given in 1/60th second units (i.e.,
60 = 1 seconds, 3600 = 1 minute, etc.). The actual delay is at
least that requested, and may be longer.
Possible errors:
Syscall Block is Too Short
COPYRIGHT (C) 1978 84 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION V: SYSCALLS - IMPLEMENTATION
SYSCALL:GETSERIALNUMBER
This system call is used to read the 8 byte hardware serial
number of the computer.
GETSERIALNUMBER SYSCALL Block Format:
SCBLK:OPCODE FCB SYSCALL:GETSERIALNUMBER
SCBLK:WLEN FCB SCBLK:END-SCBLK:OPCODE
SCBLK:PARAMS FDB IGNORED
SCBLK:WRBUF FDB IGNORED
SCBLK:WRLEN FDB IGNORED
SCBLK:RPLEN FDB 8 EXPECTED RETURNED VALUE
SCBLK:RDBUF FDB SERIALNUMBERBUFFER
SCBLK:RDLEN FDB 8
Possible errors:
Syscall Block is Too Short
COPYRIGHT (C) 1978 85 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION V: SYSCALLS - IMPLEMENTATION
ASM/6809 1.4A1: 0000
09/17/84 19:43:57; Page 1; Form 1 *** SDOS SYSCALL Example ***
listfile.asm
5: * This is a sample assembly language program to list
6: * a file to the console: device (i.e., it does exactly
7: * the same thing as a list file command does), and
8: * illustrates use of syscalls and error recovery logic.
9: *
0200 10: org $200 nice place for program
11: * set up the equs we need
12: *
0000 13: channel0 equ 0 user terminal channel
0001 14: channel1 equ 1 channel for file i/o
0001 15: linemode equ 1 input in "line mode"
16: *
17: * Print a "hello" message on user channel
18: *
0200 8E024C 19: listfile ldx #himessage
0203 9DFB 20: jsr syscall$
21: * If we get an error when printing the "hi" message
22: * (i.e., the carry is set), this BCS will take us
23: * to the error routine which will do an error exit
0205 2528 24: bcs error
25: *
26: * Now input the name of the file the user wishes
27: * to list to his/her terminal
28: *
0207 8E0277 29: ldx #inputfilename
020A 9DFB 30: jsr syscall$
020C 2521 31: bcs error
32: *
33: * Next, open the file...to do this we set the length
34: * of the file name in the OPEN syscall block equal
35: * the number of characters read in by the last syscall.
36: * We don't have to move the file name anywhere since
37: * we very cleverly made the place that SDOS will look
38: * at for the file name the same place where SDOS
39: * read in the string from the user
40: * (similar to INPUT a$\OPEN #1,a$ in BASIC)
41: *
42: * Get how many chars the user typed in
020E BE027F 43: ldx inputfilename+reada:actualcount
44: * Set the length of file name to number of chars read
0211 BF028D 45: stx openfile+open:length
0214 8E0287 46: ldx #openfile address of syscall block
0217 9DFB 47: jsr syscall$ make SDOS open the file
0219 2514 48: bcs error take branch if "no such
49: * file", "bad name", etc.
COPYRIGHT (C) 1978 86 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION V: SYSCALLS - IMPLEMENTATION
ASM/6809 1.4A1: 0219
09/17/84 19:43:57; Page 2; Form 1 *** SDOS SYSCALL Example ***
listfile.asm
51: * main program loop
52: *
021B 8E0291 53: readloop ldx #readaline read line from...
021E 9DFB 54: jsr syscall$ the input file
55: *
56: * Now check to see if the read got an error.
57: * If it did, see if the error was an end of file.
58: *
0220 2517 59: bcs checkforeof
60: *
61: * If we get to here, we know we didn't get an error.
62: * So set the length of the write buffer equal to the
63: * number of characters read in
64: *
0222 BE0299 65: ldx readaline+reada:actualcount
0225 BF02A7 66: stx writealine+writea:count
67: *
68: * and then send the line out to the user
69: *
0228 8E02A1 70: ldx #writealine
022B 9DFB 71: jsr syscall$
72: * If no error on output, go read another line
022D 24EC 73: bcc readloop
74: *
75: * Error routine: copy error code in X to a syscall
76: * block which will have SDOS print out the
77: * corresponding error message and exit
78: *
022F BF02AB 79: error stx errorexit+errorexit:code
0232 8E02A9 80: ldx #errorexit
0235 9DFB 81: jsr syscall$ SDOS shouldn't return,
0237 25FE 82: bcs * should never get here
83: *
84: * Check for EndOfFile: if so, wrap things up and exit.
85: * Otherwise, do an error exit.
86: *
0239 8C03E9 87: checkforeof cpx #err:eofhit EndOfFile error?
023C 26F1 88: bne error if not, go complain
023E 8E02AD 89: ldx #byemessage print "I'm done" message
0241 9DFB 90: jsr syscall$
0243 25EA 91: bcs error murphy's law strikes again!
0245 8E02BD 92: ldx #exit now exit
0248 9DFB 93: jsr syscall$
024A 25E3 94: bcs error this can't happen
95: *
96: * end of code
COPYRIGHT (C) 1978 87 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION V: SYSCALLS - IMPLEMENTATION
ASM/6809 1.4A1: 024A
09/17/84 19:43:57; Page 3; Form 1 *** SDOS SYSCALL Example ***
listfile.asm
98: * blocks for syscalls
99: *
024C 100: himessage ; syscall block to output "hello" message
024C 0C 101: fcb syscall:writea
024D 08 102: fcb writea:sclen
024E 00 103: fcb channel0
024F 00 104: fcb ignored filler
0250 0254 105: fdb hitext pointer to message
0252 0023 106: fdb hitextlen length of message
107:
0254 48692128 108: hitext fcc 'Hi! What file do you want to list? '
0023 109: hitextlen equ *-hitext length of message
110:
0277 111: inputfilename ; syscall block to accept line from user
0277 0A 112: fcb syscall:reada
0278 0E 113: fcb reada:sclen
0279 00 114: fcb channel0 from the user
027A 01 115: fcb linemode input up to a <cr>
027B 0000 116: fdb ignored dummy write buffer stuff
027D 0000 117: fdb ignored
027F 0000 118: fdb ignored
0281 02BF 119: fdb filenamebuf read buffer
0283 0100 120: fdb filenamebufmax max amount to read
0285 0002 121: rmb 2 amount read (set by SDOS)
122:
0287 123: openfile ; syscall block to open a file
0287 00 124: fcb syscall:open
0288 0E 125: fcb open:sclen
0289 01 126: fcb channel1
028A 00 127: fcb ignored filler
028B 02BF 128: fdb filenamebuf where user's input is
028D 0004 129: rmb 4 buffer length (set by pgm)
130:
0291 131: readaline ; syscall block to read a line from a file
0291 0A 132: fcb syscall:reada
0292 0E 133: fcb reada:sclen
0293 01 134: fcb channel1
0294 01 135: fcb linemode
0295 0000 136: fdb ignored dummy write buffer stuff
0297 0000 137: fdb ignored
0299 0000 138: fdb ignored
029B 02BF 139: fdb readbuffer
029D 0100 140: fdb readbuffermax
029F 0002 141: rmb 2 how much data read
COPYRIGHT (C) 1978 88 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION V: SYSCALLS - IMPLEMENTATION
ASM/6809 1.4A1: 029F
09/17/84 19:43:57; Page 4; Form 1 *** SDOS SYSCALL Example ***
listfile.asm
02A1 143: writealine ; syscall block to write a line on terminal
02A1 0C 144: fcb syscall:writea
02A2 08 145: fcb writea:sclen
02A3 00 146: fcb channel0
02A4 00 147: fcb ignored filler
02A5 02BF 148: fdb writebuffer
02A7 0002 149: rmb 2 length of line
150:
02A9 151: errorexit ; syscall block to effect error exit
02A9 12 152: fcb syscall:errorexit
02AA 04 153: fcb errorexit:sclen
02AB 0002 154: rmb 2 set to error code by pgm
155:
02AD 156: byemessage ; syscall block to print "done..."
02AD 0C 157: fcb syscall:writea
02AE 08 158: fcb writea:sclen
02AF 00 159: fcb channel0
02B0 00 160: fcb ignored
02B1 02B5 161: fdb byetext
02B3 0008 162: fdb byetextlen
163:
02B5 646F6E65 164: byetext fcc "done..."
02BC 0D 165: fcb $0d carriage return
0008 166: byetextlen equ *-byetext
167:
02BD 168: exit ; syscall block to effect normal exit
02BD 11 169: fcb syscall:exit
02BE 02 170: fcb exit:sclen
171:
172: * and here's the i/o buffer
02BF 173: filenamebuf equ *
02BF 174: readbuffer equ *
02BF 175: writebuffer equ *
0100 176: filenamebufmax equ $100
0100 177: readbuffermax equ $100
02BF 0100 178: rmb readbuffermax space for buffer
179: *
180: * that's all folks!
181: *
182: end listfile
COPYRIGHT (C) 1978 89 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION VI: SDOS CONSTRUCTION/FUNCTIONS
WRITING and DEBUGGING User Assembly Programs
Writing a User Assembly-Language program to run under SDOS
requires the following steps:
1) Use EDIT (or some other means) to place the desired assembly
source program on a disk.
2) Use ASM to produce a listing (optional) and a .BIN (Binary)
version of the desired program.
3) a) Execute the program by typing its name
or
3) b) Debug the program by typing
.DEBUG name
This will pass control to the local system debugger (usually
IDB) and debugging may commence.
Note: Breakpoints should not be placed on a BCC/BCS after a
SYSCALL (SDOS will not see the BCx if an error occurs and a
system failure will result). Further, breakpoints should
all be removed before a SYSCALL:EXIT or SYSCALL:ERROREXIT
is executed. Also, SDOS has no "warm start" entry point;
if the program runs away, the operator's only safe choice
is to re-boot.
COPYRIGHT (C) 1978 90 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION VI: SDOS CONSTRUCTION/FUNCTIONS
MEMORY MAP
The memory of the 6800/6809 computer, when executing a user
program under SDOS, has the following layout:
LOCATIONS CONTENTS
$0-$7 (6800 and 6809)
$18-$1F (6801 and 6811)
Scratch temporaries, usable by user program. Note:
These temporaries are also used by SDOS; so any
SYSCALL will destroy their contents.
$20-$EF
User program page zero. Not used by SDOS or the
I/O package.
$FO-$FA
System dependent data used by system hardware
(ROM), I/O package or interrupt routines for any
purpose; see specific I/O packages. User programs
must not disturb this data; references to this
data will make the program hardware or
configuration dependent.
$FB,$FC,$FD
SYSCALL entry point. These three bytes contain a
JMP to the SYSCALL entry point in SDOS. All user
programs should define SYSCALL$ as $FB; this will
make them independent of the actual location of
SDOS. These bytes are initialized by SDOS whenever
a CHAIN or LOAD SYSCALL is executed. Bytes
$FC,$FD form a 16 bit pointer to the first byte of
SDOS (to the first byte above the memory space
available to the user program).
$FE,$FF
Reserved for system dependent data (typically a
pointer to last byte or page of RAM). User
program must not disturb or use.
$100-(SDOS-1)
User program area. Used in any way desired by
user programs. Last byte of this area has an
address equal to contents of ($FC,$FD) minus 1.
On entry (CHAIN) to a user program, the stack
register is set to this value (SDOS-1).
Generally, user programs have a start address of
$100.
SDOS --
Beginning of SDOS (and/or I/O package). User
program may not overlay or store any byte on or
above this boundary.
COPYRIGHT (C) 1978 91 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION VI: SDOS CONSTRUCTION/FUNCTIONS
Typical SDOS Address Space
--------------------
LOW ! !
! PAGE ZERO !
!__________________!
$:0100 ! !
! !
! SD SOFTWARE or !
! CUSTOMER SOFTWARE!
! !
!__________________!
! . !
! . !
! . !
!
! !
! !
:7800 !__________________!
TTY, ! !\
LINEPRINTER, ! MISCELLANEOUS ! \
DRIVERS, !__________________! \
(ETC.) ! DISK READ ! |
! DISK WRITE ! |
! DISK WAITDONE ! | I/O Package
!__________________! |
! DISK ! |
! SECTOR ! |
! BUFFERS ! /
! ! /
!------------------!
! VT DRIVER !
!__________________!
! SDOS ! 48K
! (DISK FILE !
! MANAGEMENT) ! 63K DEPENDING ON
!__________________! CONFIGURATION
!//////////////////!
!//////////////////! NON-EXISTENT MEMORY
!//////////////////!
!------------------!
:F000 ! IDB !
!__________________!
:FC00 ! SDOS BOOT !
!__________________!
:FF00 ! !
! I/O SPACE ! ROM VECTORS TO OTHER ROM
HIGH !__________________!
COPYRIGHT (C) 1978 92 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION VI: SDOS CONSTRUCTION/FUNCTIONS
SDOS LOADER FORMATS
SDOS will load files containing one of two types of records:
1) SDOS Load Records
2) Encrypted Load Records
A file to be loaded must contain only SDOS load records, or
encrypted load records.
SDOS LOAD RECORD FORMATS
SDOS Load Records are designed to let SDOS load large blocks of
contiguous memory efficiently, and still retain scatter-load
capability. A file containing SDOS Load Records appears as a
stream of load records. Each load record has a type and a
format. There are four SDOS load record types; all four contain
binary information for ease of processing by the loader and to
minimize file space occupied. Each load record type is
identified by its first byte. One record immediately follows
another.
SDOS load record type 1 must be the first record (i.e., start on
byte 0) of the file. It is followed by 2 bytes forming a 16 bit
start address, MSB first. The next two bytes are the 16 bit
one's complement of the start address, MSB first (this record
format makes it extremely improbable that a non-load format file
is actually loaded by accident). The first byte of a A Type 1
load record specifies the CPU type:
$01 6800
$03 6801/6803
$02 6809
$07 6303
$11 6811
SDOS load record type 0 is a skip record. The two bytes
following the record type byte form a 16 bit count (MSB first) of
the number of bytes following the skip record to ignore. The
loader processes this record by positioning the file to the file
position after the skip record, plus count bytes. This record
format is used to align following load records on power of two
boundaries which can speed up loading of larger data records.
SDOS load record types 2 and 3 are identical in format. Both
record types are used to load blocks of data into the memory
address specified by the two bytes following the record type byte
(MSB first). The number of bytes to be loaded is given by the 16
bit count specified by the next two bytes (MSB first). The data
bytes to be loaded immediately follow the count bytes.
COPYRIGHT (C) 1978 93 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION VI: SDOS CONSTRUCTION/FUNCTIONS
A type 2 record specifies that another load record follows (i.e.,
that EOF does not immediately follow the records) and that
further load record processing is needed. A type 3 record
indicates that the load process is complete once the data bytes
in the type 3 record are loaded (i.e., there are no more load
records in the file). After processing a type 3 record, a
SYSCALL:CHAIN will transfer control to the start address
specified by the type 1 record.
COPYRIGHT (C) 1978 94 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION VI: SDOS CONSTRUCTION/FUNCTIONS
SDOS LOAD RECORD FORMATS
Command
_____________________________ ____________
! 0 ! COUNT ! !.....! !
!_______!_____!_____!_______! !__________!
2 BYTES !________________!
!
!
COUNT BYTES
Meaning: Skip COUNT bytes to find
next command. Used as a
space filler to pad to the
next physical sector boundary.
_________________________________________
!CPU Type ! ADDRESS ! 16 BIT CHECKSUM ! Set start address.
!_________!_____!_____!________!________! Must be first command
2 BYTES 2 BYTES in file. CHECKSUM is
:FFFF - address.
__________________________________________________
! 2 ! ADDRESS ! COUNT ! DATA BYTES !
!_______!_____!_____!_____!_____!________________!
2 BYTES 2 BYTES !__________!
!
!
COUNT BYTES
Causes data bytes to be loaded
sequentially into memory
starting with the specified
address.
_________________________________________________
! 3 ! ADDRESS ! COUNT ! DATA BYTES !
!_______!_____!_____!_____!_____!_______________!
2 BYTES 2 BYTES
Just like 2, but also causes
JUMP to start address specified.
COPYRIGHT (C) 1978 95 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION VI: SDOS CONSTRUCTION/FUNCTIONS
The load records are used in the following way to optimize the
disk reads (example):
===================
Logical byte #'s ! Type 1 record ! Must be first in file
! !_________________!
! ! !
! ! !
! ! Type 0 record ! Filler record
! ! !
! !_________________!
! ! Type 2 record ! Indicates "Load next
! !=================! two sectors".
NBPS ! 1ST Data Byte !
! !
!=================!
2*NBPS ! !
! !
!=================!
3*NBPS ! Type 3 record ! Indicates "Load next
!_________________! two sectors" and
! ! transfer control to
! ! start address when
! ! done.
!=================!
4*NBPS ! !
! !
!=================!
Encrypted Files
______________________________________________
| 05 |S# COUNT | 48 Random Bits |
|______|_________|___________________________|
| 1st Serial Number |
|____________________________________________|
| 2nd Serial Number |
|____________________________________________|
| S# Serial Number |
|____________________________________________|
COPYRIGHT (C) 1978 96 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION VI: SDOS CONSTRUCTION/FUNCTIONS
ENCRYPTED OBJECT FILES
An encrypted file is one whose content is not in a directly
usable form. Under SDOS, encrypted object files contain
proprietary programs which are designed to run on only a limited
number of CPUs. Some programs are proprietary to Software
Dynamics; other programs are proprietary to other vendors.
Software Dynamics provides a tool to allow vendors to encrypt
their own object programs or suite of programs.
An encrypted program is decrypted by SDOS while loading into
memory by use of an Encryption Key. The Encryption Key is a
function of the serial numbers of the CPUs on which the program
is authorized run, and a 48 bit "application suite" number
embedded in the object file.
SDOS zeros the address space when loading an encrypted file whose
Encryption Key is different than the Encryption Key of the last
file loaded. This prevents "Trojan Horse" software from
obtaining a snapshot of a previously-executed program. Only
programs with the same encryption key may pass control (and
non-zero data) to one another. This is a common requirement of
an "application suite".
Encrypted object files have an un-encrypted 1st object record,
followed by the rest of the file in an encrypted format. The
encrypted portion of the file, once un-encrypted, is in standard
SDOS load record format, with the exception that no skip records
are allowed (decrypting skip records is simply a waste of time).
The first object record starts with a byte containing :05,
signifying this file is an encrypted object file. The
SerialNumberCount (S#) specifies how many serial numbers for
which this object file was encrypted. Following the
SerialNumberCount are 6 bytes of Application Suite number
(typically a random number chosen at time of encryption). Last
are a series of 8 byte Serial Numbers on which this object file
is authorized to run. These serial numbers are in a clear text
form so they can be easily inspected by a utility program.
COPYRIGHT (C) 1978 97 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION VI: SDOS CONSTRUCTION/FUNCTIONS
SDOS DISK FILE STRUCTURE
This section gives detailed information on the structure of the
SDOS disk file system. Two concepts are critical to the
understanding of the file system: Logical Sector Numbers and
Logical Cluster Numbers. These concepts are detailed xbelow.
Definitions:
NBPS Number of bytes/sector (2^n,n=1..15). Must be power of
2!! NBPS is limited to 128*32=4096 by directory search
routine. Minimum size is 128 bytes (see BOOT sector).
NSPT Number of sectors/track
NTPC Number of tracks/cylinder
NCYL Number of cylinders/drive
NLSN Number of (logical) sectors on a disk (= NSPT*NTPC*NCYL)
Note: Number of bytes/cluster < 2^16 for 6800/6809
implementation.
COPYRIGHT (C) 1978 98 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION VI: SDOS CONSTRUCTION/FUNCTIONS
LOGICAL SECTOR NUMBERS (LSNs)
LSN's are imaginary sequence numbering applied to physical disk
sectors on a disk cartridge or floppy diskette. The reason for
using them is that Logical Sector Numbers can be mapped onto any
disk removing any structure that the disk drive might arbitrarily
impose from the knowledge and concern of SDOS; i.e., the
distinction between tracks, cylinders, and sectors ceases to be
of concern to the SDOS file system.
The only requirements placed by SDOS on LSN's is that they begin
with 0 and increase sequentially; further, track 0, sector 0,
cylinder 0 (usually) maps into LSN 0. This is because most
hardware interfaces can read in this physical disk block as a
means for booting the system, so SDOS reserves LSN 0 for this
block.
A useful method for choosing the LSN number for a disk block on
physical cylinder C, track T, and sector S is:
LSN(C,T,S)=S+NSPT*(T+NTPC*C)
where NSPT and NTPC are the number of Sectors per Track and the
number of Tracks per Cylinder, respectively; where 0<=S<NSPT,
0=<T<NTPC, and 0<=C<NCYL (NCYL= number of cylinders). This has
the advantage of allowing SDOS to allocate new blocks to a file
by use of their LSN's, attempting to minimize LSN distance (which
minimizes Cylinder, Track, and Sector distance, in that order.
The name NLSN refers to the number of logical sector numbers for
a disk and is equal to NSPT*NTPC*NCYL. There are physical disk
read and write routines in the I/O package which are required to
convert LSN's into the corresponding values of S, T and C. Each
LSN occupies 3 bytes (maximum of (2^24)-1 LSN's).
COPYRIGHT (C) 1978 99 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION VI: SDOS CONSTRUCTION/FUNCTIONS
CLUSTERS (LCNs)
SDOS allocates disk space in units of "clusters" (not sectors!).
A cluster is simply a set of sectors whose LSN's are contiguous,
and whose lowest LSN is a multiple of the cluster size (an
arbitrary constant for a particular diskette or disk pack). Data
placed in a cluster is generally related in some fashion.
Each cluster is assigned a logical cluster number (LCN). An
(LCN) is the number given to a cluster of sectors. Every LSN is
in a cluster whose LCN is given by:
LCN(LSN)=INT(LSN/NSPC)
where NSPC is the number of disk sectors per cluster (defined for
the disk).
The total number of clusters on a disk is given by:
NSPC=INT(NLSN/NSPC)
The special cluster number :FFFF is reserved, and means "no
cluster allocated" or "no such cluster". This is the value to
which unallocated clusters specified in cluster headers are set.
The advantage of this clustering technique is that it saves space
and time. Space savings are effected on the disk because each
file does not need to explicitly record all the sectors it
contains. This means less disk space used keeping track of disk
space.
Time savings are effected when SDOS is reading sequentially
through a file, because (NSPC-1)/NSPC*100% (for NSPC=4, 75%) of
the time, SDOS knows the next LSN which is required without
having to do any disk reads to collect this information. The
disadvantage is a small loss in efficiency of disk storage (i.e.,
each file wastes NSPC/2 disk sectors on the average, instead of
1/2 disk sector average).
The cluster size is chosen to either minimize average waste of
disk sectors in files, or to minimize the seek time between disk
sectors in a cluster, subject to several constraints.
The first constraint is that all legal LCN's are limited to the
range 0-65534 decimal (65535 is reserved; 2 bytes inside SDOS),
i.e., INT((NLSN-1)/NSPC)<65535.
The second constraint is that one cluster should have enough
space to contain all the LCN's defined for a disk, i.e.,
NSPC*NBPS/2 >= INT(NLSN/NSPC) where NBPS is the number of bytes
per sector. This constraint allows SDOS to use a single cluster
to record all the clusters of a file. This constraint can be
violated, but the result is that a single file might not be able
to use the entire disk. SDOS will complain if the Header Cluster
COPYRIGHT (C) 1978 100 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION VI: SDOS CONSTRUCTION/FUNCTIONS
of a file overflows when allocating space to a file.
The third constraint is that 1<=NSPC<=255. This is purely an
implementation restriction and must be followed.
Assuming a file with 2^31=2.1x10^9 bytes, NBPS=512, NSPC=255, we
have 2.1x10^9/512=4.2x10^6 sectors in file; 4.2x10^6/255=16449
clusters in file. The header cluster has room for 255*512/2=65280
clusters, which covers such a file easily.
To minimize average wasted space in disk files, NSPC should be
chosen to be as small as possible within the constraints
specified. This may leave some disk sectors (with high LSNs)
unused by SDOS if NLSN is not a multiple of NSPC, but the total
wastage here is again only 1/2*NSPC sectors average, and if one
has 100 files on a disk, this is insignificant in comparison with
the total savings. A final note: if the number of sectors per
cylinder is not a multiple of NSPC, some time inefficiency will
occur when reading sequentially through a cluster because some
clusters will cross track or cylinder boundaries. This
inefficiency will be small if the average file size is much
greater than NSPT*NSPC.
If the average file size is smaller than NSPT*NTPC, some time
savings can be gained by making NSPC a divisor of NTPC - this
will generally prevent part of file (cluster) from overlapping
cylinder boundaries, and will therefore save seek time.
A sample calculation of NSPC:
Assume we have 77 cylinders (NCYL=77), 1 track/cylinder
(NTPC=1), 16 sectors/track (NSPT=16), 256 bytes/sector
(NBPS=256) (so NLSN=NSPT*NTPC*NCYL=16*1*76=1232). Let
LSN(C,T,S)=S+16*(T+1*C). Since we have only one track
(track #0), the formula simplifies:
LSN(C,S)=S+16C
For any NSPC>=1 then NLSN/NSPC < 65536, satisfying
constraint 1.
Constraint 2 implies:
NSPC*256/2>=INT(1232/NSPC)
NSPC*128>=INT(1232/NSPC)
which is true for any NSPC>=4
If we choose NSPC=4, constraint 3 is also satisfied.
To minimize average wasted space, we choose NSPC=4. On a disk
with 100 files, an average of 100*4/2=200 disk sectors are
wasted. With NSPC=3, with 100 files wastes an average of
100*3/2=150 sectors, and prevents files from containing more than
1152 sectors (i.e., a particular file can only cover 93% of the
disk).
COPYRIGHT (C) 1978 101 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION VI: SDOS CONSTRUCTION/FUNCTIONS
DISK FILE STRUCTURE
A File under SDOS is a mechanism for storing logically related
information. From the point of view of an application program, a
disk file is a very large array of 8 bit bytes which can be
read/written sequentially, can be positioned for later
read/writes, and can be automatically extended (at the end) to
add more information. These files can be up to 2^31 bytes (2.1
billion bytes) in size, physical disk size being the real
limitation.
This view of files is implemented by device drivers. The
operations that a device driver considers legal and the actual
operation performed are dependent on each device driver (see
Device Drivers). There are two kinds of drivers: non-disk file
and disk file.
The disk file driver is a component of SDOS proper. It handles
files by breaking them down into two layers: clusters and
sectors. Sectors are the physical unit of transfer to/from the
disk drive. Clusters are a logical grouping of sectors used to
minimize the amount of information required to record where all
the sectors of a file are located.
Each file has a special cluster of sectors known as the Header
Cluster. The Header Cluster contains the logical cluster numbers
of all (data) clusters contained in the file. These numbers are
placed in the Header Cluster in such a way as to indicate the
relative (byte) position of the target cluster in the file.
A special cluster number of hex :FFFF means "no data cluster
allocated" to this place in the file. This allows sparse files
to be built with very little wasted space.
COPYRIGHT (C) 1978 102 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION VI: SDOS CONSTRUCTION/FUNCTIONS
__________
! ! First Cluster Pointer
! ! Points to Headercluster
! !
V !
Header - ______________ !
Cluster ! 2B ! ----------!
! 2B ! ------------------
! 2B ! --------------- ! Remaining Cluster Pointers
! ! . ! ! ! Point to Data Clusters
! ! . ! ! !
! !____________! ! !
! ! ---------- ! !
! ! ! ! ! ! Data Cluster #0
NSPC*NBPS ! ! ! ! ! ____________
! !____________! ! ! !-->! !
! ! ! ! ! ! !
! ! ! ! ! !__________!
! ! ! ! !
! ! ! ! !
- !____________! ! ! Data Cluster #1
! ! ____________
! !----->! 0 !
! !__________!
! ! 1 !
! !__________!
! ! . !
! ! . !
! ! . !
! !__________!
! ! NSPC-1 !
! !__________!
!
!
! Data Cluster #N
! ____________
!--------->! !
! !
!__________!
The first two bytes in the header cluster are reserved to contain
the cluster number of the header cluster itself (this simplifies
the space allocation routines). Succeeding pairs of bytes
contain the logical cluster numbers of the 0th data clusters, 1st
data cluster, etc.
When a file is first allocated, all the pointers (except the
first) in the first sector of the header cluster are initialized
as :FFFF (no data cluster allocated). The other sectors in the
header cluster are left as garbage.
A special 1 byte counter (stored in the directory), DIR:HCSIC
(header cluster initialized count) tells SDOS how many of the
sectors in the header cluster are initialized.
COPYRIGHT (C) 1978 103 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION VI: SDOS CONSTRUCTION/FUNCTIONS
If a data byte is in logical byte number "LBN" in a file, then
SDOS can access that byte (in at most two disk reads) by the
following process (definition):
First, compute:
NBPC := NSPC*NBPS (COMPUTE # BYTES/CLUSTER)
RDCN := INT(LBN/NBPC) (COMPUTE THE RELATIVE DATA
CLUSTER NUMBER)
HSLSN := INT[(RDCN+1)*2]/NBPS + HCLCN*NSPC
where HSLSN = header sector logical sector number
and HCLCN = header cluster logical cluster number.
This computes the LSN of desired sector in the Header
Cluster. The "+1" is because the first cluster pointer
is the pointer to the header cluster. The "*2" is
because each cluster number occupies two bytes.
Note: HCSIC may indicate that this sector (HSLSN) has not
been initialized!!
Next:
read HSLSN into memory in HBBUF (header buffer)
DBLCN := @((((RDCN+1)*2)MOD NBPS)+.HBBUF)
this computes the LCN of the data cluster containing the
byte.
"@" means use the value to the right as a memory address
and fetch 16 bits. ".HBBUF" means the address of the
header buffer. Note: DBLCN may be :FFFF (undefined)!!
Finally:
DBLSN := DBLCN*NSPC+INT((LBN MOD NSPC*NBPS)/NBPS)
Read DBLSN into memory; desired byte is found at
displacement RBN := LBN MOD NBPS
COPYRIGHT (C) 1978 104 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION VI: SDOS CONSTRUCTION/FUNCTIONS
SDOS FILE STRUCTURE
! . !
! . !
! . !
!______________!
! DIRECTORY !
! ENTRY !
! !
! LCN -----------
!______________! !
! . ! !
! . ! !
! . ! !
/
/
/
/
--------------/
!
!
____ !
! ! ! Header Cluster - First Cluster of File
! _V____V_ ________ ________ ________
!----- ! ! ! ! ! ! ! )(Some)
!______! ! ! ! ! ! ! )Sections
!------- ! ! ! ! ! ! ! )Initialized
! !______! ! ! ! ! ! ! )To "No
! !----- ! ! ! ! !......! ! )Cluster
! ! !______! ! ! ! ! ! ! )Allocated"
! ! ! 3RD ! ! ! ! ! ! ! )At File
! ! !______! ! ! ! ! ! ! )Creation
! ! ! . ! ! ! ! ! ! ! )Time
! ! ! . ! ! ! ! ! ! !
! ! !______! !______! !______! !______!
! !
! !-------> 2nd Data Cluster _______________________
! ! A Cluster Number Of !
!---------> 1st Data Cluster ! :FFFF !
! Means "No Cluster !
! Allocated" !
!_____________________!
COPYRIGHT (C) 1978 105 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION VI: SDOS CONSTRUCTION/FUNCTIONS
__________
! !
! V Header Cluster
! __________
!-------- !
--------- !
! ! !
! ! ------------> 2nd Data Cluster
! ! ------------> Etc.
! !________!
!
!
! 1st Data Cluster
!
! ------- ------- ------- -------
! ! ! ! ! ! ! ! !
!-----> ! ! ! ! ! ! !
! ! ! ! ! ! ! !
! ! ! ! ! !.....! !
! ! ! ! ! ! ! !
! ! ! ! ! ! ! !
! ! ! ! ! ! ! !
! ! ! ! ! ! ! !
------- ------- ------- -------
Logical sector number of 1st sector in cluster =
cluster number * cluster size in sectors.
Succeeding sector numbers are base sector number + index into
cluster.
COPYRIGHT (C) 1978 106 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION VI: SDOS CONSTRUCTION/FUNCTIONS
DIRECTORY.SYS STRUCTURE
The directory stores the name and location of the header cluster
for all files on the disk (SDOS allows no magic disk files which
are not in the directory; even system files are mentioned in the
directory).
Each Directory entry is 32 bytes and contains the following
information:
DIR:FILENAME
The file name can be any left-justified sequence of letters
(uppercase only), digits 0 through 9, $ or ".". It may not
begin with a "." or a digit. The name is blank filled to 16
bytes. Two file names are considered equivalent if they
match byte for byte. SDOS automatically folds lowercase
characters in disk file names into uppercase. Bit 7 of all
bytes must be zero.
DIR:HLCN
The Header Logical Cluster Number specifies the location of
the Header Cluster for the file if DIR:HCSIC > 0. If
DIR:HCSIC = 0, then DIR:HLCN is actually the cluster number
of the 1st data cluster.
DIR:HCSIC
The Header Cluster Sector Initialized Count tells SDOS how
many sectors of the header cluster have been initialized
properly (see File Structure) and need not concern any but
the systems programmer. DIR:HCSIC is updated whenever a new
header cluster sector is initialized. If DIR:HCSIC is zero,
and DIR:NCLUSTERS > 0, then the file is contiguously
allocated on the disk, with the first data cluster being in
DIR:HLCN, contiguous for DIR:NCLUSTERS.
DIR:NCLUSTERS
DIR:NCLUSTERS is the number of clusters allocated. This
count is needed as a very sparse file may have an enormous
logical file size, and yet have a very small actual disk
allocation. SDOS updates DIR:NCLUSTERS only when a file is
closed. If DIR:NCLUSTERS is zero, this directory entry is
not valid and is available for use by a new file (name).
DIR:FILESIZE
DIR:FILESIZE is the apparent size of the file in bytes, and
is equal to the position of the last data byte written in
the file, +1. The filesize is completely independent of
sector or cluster size.
COPYRIGHT (C) 1978 107 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION VI: SDOS CONSTRUCTION/FUNCTIONS
DIR:PROTECTION
DIR:PROTECTION contains file protection bits. The
protection bits prevent inadvertant or undesired references
to file. The currently defined bits are:
7 <NOT DEFINED>
6 PROTECT:WRITE
5 <NOT DEFINED>
4 <NOT DEFINED>
3 <NOT DEFINED>
2 <NOT DEFINED>
1 <NOT DEFINED>
0 PROTECT:BACKUP
PROTECT:WRITE
The PROTECT:WRITE bit prevents DELETE, RENAME, and
CREATE commands on a file with the corresponding name.
This is used by SDOS to prevent accidental erasures of
critical system files, and may be used by the user to
protect his critical files.
PROTECT:BACKUP
This bit prevents SDOSDISKBACKUP from backing up a file
if the CHANGED option is specified. It is reset
whenever a file is first created, or when a file is
modified in any way (SYSCALL:WRITEA, SYSCALL:WRITEB,
CC:SETFILESIZE, etc.). It is set by SDOSDISKBACKUP
whenever a file has been backed up using the CHANGED
option.
DIR:CREATIONDATE
DIR:CREATIONDATE contains the creation date of the file in
the form DDMMYY. DD is one byte containing the day number in
BCD; MM is one byte of BCD month; and YY is the year number
modulo 100 in one BCD byte.
SDOSDISKINIT generally places the first data cluster of the
directory at INT(NLCN/2) (the middle of the logical disk) in an
attempt to decrease seek-to-directory time. This also causes
SDOS to extend the directory in the middle of the disk if need
be. Note: This LCN must be non-zero! (Otherwise, the directory
and the boot cluster collide.)
SDOS locates the directory initially by reading BOOT:DIRLSN from
the BOOT.SYS file. BOOT:DIRLSN gives the LSN of the directory
sector containing the DIRECTORY.SYS entry. The directory entry
for DIRECTORY.SYS is located in the first 32 bytes of the sector.
This requirement also forces the sector size to be at least 32
bytes (the first entry must be contained entirely in the first
directory sector), and to be a multiple of 32!
COPYRIGHT (C) 1978 108 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION VI: SDOS CONSTRUCTION/FUNCTIONS
All other filenames in the directory are added to it according to
the following procedure:
The directory is searched by initially hashing the desired
name to choose a directory sector, and then searching
circularly through the directory for the desired name. The
hashing scheme tends to make lookups of existing names very
quick, as long as the directory is 80% or less loaded. The
circular search guarantees that even if the directory size
changes, files will still be found.
The directory is automatically expanded by SDOS if it is
full and a new filename needs to be added. This automatic
expansion invalidates all the previous hashes, but since new
(or renamed) files will get hashed to the correct place,
after the system has been used with the expanded directory
awhile, lookups will speed up again. Renaming a file
rehashes it, so renaming all files will rehash them all.
The directory size is kept in the DIR:FILESIZE entry of the
DIRECTORY.SYS entry, and is always a multiple of the cluster size
(NBPC).
As a convenience to the hashing algorithm, a limit of 65536
directory sectors is imposed on the DIRECTORY.SYS file.
COPYRIGHT (C) 1978 109 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION VI: SDOS CONSTRUCTION/FUNCTIONS
Directory Entry
.
.
.
! . !
! . !
! . !
! . !
! . !
!================!
! ! 16 Bytes,
! DIR:NAME ! Legal Names Contain
! ! A-Z, 0-9, $, "."
!----------------!
! DIR:HLCN ! 2B, Header Cluster Number
! !
! !
!----------------!
! DIR:HCSIC ! 1B Header Cluster Sector
! ! Initialized Count
!----------------!
! DIR:NCLUSTERS ! 2B Number of Data
! ! Clusters in File
!----------------!
! DIR:FILESIZE ! 4B, Number of Bytes in
! ! The File
!----------------!
! DIR:PROTECTION ! 1B, Protection Bits
! !
!----------------!
!DIR:CREATIONDATE! 3B
!----------------!
! UNUSED ! 1B
!================!
! . !
! . !
! . !
! !
! !
! !
! !
COPYRIGHT (C) 1978 110 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION VI: SDOS CONSTRUCTION/FUNCTIONS
File System Sketch
DIRECTORY.SYS
file body
_____________
! !<-------|
LCN 0, LSN 0 ! ... ! | DIRECTORY.SYS
____________ !___________! | Header Cluster
! BOOT: ! ! ! ___|___________________
! DIRLSN *-------> ! DIRECTORY ! ! | ! ! ! !
!__________! ! .SYS #-------->! # ! ! ... ! !
^ !___________! !_____!____!_____!____!
| ! ! usually, LCN=@(Directory)-1
| BOOT.SYS ! ... !
| Header !___________!
__|____________ ! !
! # ! ... ! !<-----# BOOT !
!___!_____!___! ! .SYS !
!___________! DISKMAP.SYS file body
! ! "Busy Cluster Map"
! ... ! (1 cluster)
SDOS.SYS !___________! _______________________
Header Cluster ! ! ! ! ! ! !
--------------- ! SDOS.SYS ! ! ! ! ... ! !
! # ! ... ! !<--------# ! !_____!____!_____!____!
!_|_!_____!___! !___________! ^
| ! ! |
| SDOS.SYS ! ... ! | DISKMAP.SYS
| file body !___________! | Header Cluster
__V________ ! ! ___|___________________
! LCN #1 ! ! DISKMAP ! ! | ! ! ! !
! LCN #2 ! ! .SYS #--------->! # ! ! ... ! !
! LCN #3 ! !___________! !_____!____!_____!____!
! ... ! ! !
! LCN #n ! ! ... !
!_________! !___________!
Notes: * represents pointer to (logical) sector
# represents pointer to (logical) cluster
SDOS hashes to 1st directory entry, and does linear circular
search thereafter.
COPYRIGHT (C) 1978 111 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION VI: SDOS CONSTRUCTION/FUNCTIONS
Physical Placement of Files on Disk
LCN ~~ NLCN/2
| Logical Sector 0
| |
_______|____________V_________
/ | ! BOOT.SYS /\
/ | !___________/ \
/ | \ S \ <--- Logical Cluster #1
/ __V____________ \ D \ <--- LCN 2, 3, etc.
/ ! DISKMAP.SYS ! \ O \
/ --------------- \ S \
! ______ ! . !
! / \ ! S !
! ! ! _____ ! Y !
! ! ! ! S ! ! S !
! \______/ ! Y ! !___!
! ! S ! !
\ / . / <--------- LCN ~~ NLCN/2
\ _______________ / Y / /
\ ! D I R E C T O R / /
\ ------------------/ /
\ /
\_____________________________/
COPYRIGHT (C) 1978 112 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION VI: SDOS CONSTRUCTION/FUNCTIONS
THE BOOT.SYS FILE
BOOT.SYS is a file which owns LSN 0 (the boot sector).
The BOOT.SYS file contains three things:
1) a disk identification (32 bytes of text blank padded).
2) the appropriate DISKINFO (tuning parameters) for this disk
3) a "simple" program to read SDOS off the disk and into memory
as a means of booting.
Items 1 and 2 are stored in fixed places in LSN 0 and occupy the
first 64 bytes. This sets a minimum sector size requirement of
64 + 1 --> 128 (sector sizes must be a power of two!). Other
LSN's in the BOOT.SYS file are simply wasted or used to store an
extended bootstrap program if needed.
The form of the boot sector must be as follows:
________________
! !
16 BYTES ! JUMP ----------- These Bytes Are
!______________! ! Used For Any
! ! ! Purpose By Boot
15 BYTES ! DISK ! ! or Boot ROM
! INFO ! ! Routine
!______________! !
1 BYTE !DISKINFOCKSUM ! <------ = :FF - Sum of
!______________! ! Bytes in
! ! ! DISKINFO Part
! ! !
! ! !
32 BYTES ! DISK ! !
! ID ! !
! ! !
! ! !
!______________! !
! ! !
! <---------
! BOOT !
REST OF ! ROUTINE !
SECTOR ! !
! !
!______________!
This ensures that the disk identification string is easily
locatable, and that it does not prevent the boot routine from
executing.
Normally, LSN 0 is read into memory at $100 by a ROM boot
routine, and control is passed to location $100. The boot sector
reads in the rest of BOOT.SYS if necessary.
COPYRIGHT (C) 1978 113 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION VI: SDOS CONSTRUCTION/FUNCTIONS
The boot routine then reads the contents of the SDOS file into
memory at the appropriate place, and transfer control to the
starting point.
BOOT:FILESYSTEMVERSION is a single byte containing a file system
version and revision number in the left and right nibbles,
respectively. This document describes file system version
1.1 (note: SDOS revision numbers do not necessarily match
file system revision numbers!).
BOOT:NSPC is a single byte which specifies the cluster size of
clusters on this disk (0<BOOT:NSPC<=255).
BOOT:MINALLOC is two bytes which specify the minimum number of
data clusters to allocate to a disk file when it is created
on this disk. 0 is not legal.
BOOT:MIDALLOC is two bytes which specify the minimum number of
clusters to be allocated to a file being extended.
BOOT:MIDALLOC must be >= 1.
BOOT:MAPALGORITHM is 16 bits which are used in a disk-sector
driver dependent way to tune rotational and seek latency
times to a minimum.
Commonly, the upper 8 bits are used as "spiralling", or the
number of sectors each cylinder should be offset from the
next (cylinder) to tune seeks for sequential reads; the
lower byte tunes the physical spacing between adjacent
logical sector numbers (also measured in units of sector
times). SDOS can usually only read every other sector, best
case.
When using the "common" mapalgorithm interpretation to map
LSNs into physical CYLINDER, TRACK, and SECTOR (assuming
CYLINDERs and TRACKs increase sequentially from 0, and
physical sector 0 on all TRACKs are aligned) the following
formulas apply:
COPYRIGHT (C) 1978 114 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION VI: SDOS CONSTRUCTION/FUNCTIONS
REM PSUEDO-BASIC TO COMPUTE PHYSICAL CYLINDER, TRACK, SECTOR
CYLINDER= INT(LSN/(NSPT*NTPC))
TRACK= INT((LSN-CYLINDER*NSPT*NTPC)/NSPT)
SECTOR= ((CYLINDER*SPIRAL)+MAP[LSN MOD NSPT]) MOD NSPT
where MAP[i]= (i*SPACING) MOD NSPT if SPACING is relatively
prime to NSPT, and is generally computed as:
MAP[0]:= 0 \ !RULE!
K= SPACING
FOR i= 1 TO NSPT-1
100 FOR J= 0 TO i-1
IF K= MAP[J] THEN K=(K+1) MOD NSPT\ GOTO 100
NEXT J
MAP[i]= K
K= (K+SPACING) MOD NSPT
NEXT i
On hardware systems where formatting a disk is used to effect
this tuning, the Mapalgorithm is by convention always set to "1".
BOOT:CREATIONDATE is the date that this disk was SDOSDISKINITed,
and consists of 3 BCD bytes: day, month, and year MOD 100,
respectively.
BOOT:DIRLSN is the Logical Sector Number of the DIRECTORY.SYS
sector that contains the DIRECTORY.SYS directory entry in
the first 32 bytes.
BOOT:CHECKSUM contains :FF-[sum of the 15 bytes between (and
including) BOOT:FILESYSTEMVERSION] modulo 256, and is used
to check the validity of the disk.
BOOT:DISKID contains 32 ASCII characters blank filled, used
solely as a disk identification. This ID is displayed by
the FILES command. It can be used (read) by an application
for the purpose of verifying the disk before the application
uses it.
The boot routine is used to read the contents of SDOS.SYS into
memory. Ususally, the boot routine does not fit entirely into the
remainder of the BOOT sector; the rest of the boot routine is
stored in memory image format in the remaining sectors of LCN 0.
Listings of sample boot routines can be obtained from the
distributor of SDOS or from Software Dynamics.
COPYRIGHT (C) 1978 115 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION VI: SDOS CONSTRUCTION/FUNCTIONS
SERIALNUMBER.SYS
SERIALNUMBER.SYS is a file required to be on an SDOS boot disk in
order that SDOS may successfully boot. The file is encrypted,
and contains several things:
A first-time-only conversation with the purchaser of SDOS;
The serial number of the computer for which the particular
version of SDOS was sold; and
The name of the end-user, or organization.
SDOS, after initializing operation of the system, goes and hunts
for SERIALNUMBER.SYS. If this file does not exist, SDOS
displays, and hangs up with a "No SERIALNUMBER.SYS file" error.
If the file does exist, it is CHAINed to, causing implicit
decryption. The SDOS decrypting loader will refuse to load
SERIALNUMBER.SYS if the serial number encoded into it does not
match that of the ROM included in the system hardware; this
causes a "Wrong Serial Number" message to be printed, and
operation of SDOS is aborted. If SERIALNUMBER.SYS is not
encrypted, an error message will likewise be generated and SDOS
will not run. Otherwise, the module is loaded and executed. If
this is not the first time SERIALNUMBER.SYS has been loaded, then
SERIALNUMBER.SYS first prints the ROM serial number, and the name
of the end-user; further operation of SDOS is normal.
The name of the end-user is supplied by the end-user when the
copy is first run by him; i.e., if the end-user name is blank.
SERIALNUMBER.SYS asks the name and then waits for the operator to
enter a corresponding code number that he must obtain from
Software Dynamics. This code number is generated by Software
Dynamics from the serial number of the computer and the string
entered by the user (this may be obtained from Software Dynamics
well in advance of system installation, in order to minimize
delays). An invalid response is so indicated, and the end-user
name is NOT updated. A correct response causes SERIALNUMBER.SYS
to change the end-user name to the supplied string. Once set,
the SERIALNUMBER.SYS file can never be changed again. A response
of <CR> is taken as a signal that the user does not wish to set
the name yet (this may be a demo copy, or the user may not have
yet obtained the corresponding code number from Software
Dynamics); in this case, after a 30 minute delay, SDOS will
operate normally.
COPYRIGHT (C) 1978 116 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION VI: SDOS CONSTRUCTION/FUNCTIONS
SDOS.SYS
SDOS.SYS is an SDOS load record format file containing the memory
resident part of the operating system. It is used by the boot
procedure to load a copy of the system from the disk into memory.
To simplify the boot process, certain restrictions are made on
the file structure of SDOS.SYS.
The data LCNs of SDOS must be numbered 1, 2, 3,... etc., i.e., a
contiguously allocated file. This guarantees sequentially
increasing LSNs which makes the boot routine's job (of computing
LSNs) extremely simple. The header LCN of SDOS (if it has one)
may be anywhere on the disk; the boot routine need not look at it
(many boot routines never bother reading the SDOS header
clusters). Normally, the SDOSDISKINIT program assigns a very
high LCN to the header cluster of SDOS.SYS.
The start address of SDOS.SYS is defined to be SYSCALL$ (:FB).
When debugging a (newly SYSGENed) I/O package, a convenient trick
is to modify (using BMP, the Binary Maintenance Program) the
first load record (actually the start record) in the SDOS.SYS
file so the SDOS start address is the entry point to the ROM
debugger instead of :FB. With this change made, "booting" will
cause SDOS to get loaded, and the debugger will then gain
control. Patches may be made and breakpoints established, and
then SDOS can be started by causing a jump to :FB. When
debugging is completed, the first load record should be restored
to its initial state.
COPYRIGHT (C) 1978 117 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION VI: SDOS CONSTRUCTION/FUNCTIONS
DISKMAP.SYS
The DISKMAP.SYS file is used to keep track of clusters allocated
to disk files for that disk. Each disk cartridge or floppy
diskette has its own DISKMAP.SYS.
The file has one bit per cluster on the disk on which the file
resides. An "on" bit indicates the cluster is allocated (or
contains a bad sector). An "off" bit indicates a free cluster,
available for allocation to a file. SDOS assumes that the entire
disk map can be contained in a single cluster, so if constraint 2
of LCNs is violated (see section on CLUSTERS), one needs to make
sure that NBPS*8*NSPC>=INT(NLSN/NSPC) (otherwise the diskmap
doesn't fit into a single cluster). If constraint 2 is satisfied,
so is this condition (the 8 is the number of bits per byte).
Each byte of DISKMAP.SYS represents 8 clusters, such that bit
number n (starting with 0, counting from the right) represents an
LCN such that (LCN mod 8) = n. Bytes at logically higher byte
addresses within DISKMAP.SYS represent groups of LCNs with higher
values, so that if LBN (logical byte number), BITN (bit number)
represent a particular bit in the DISKMAP.SYS, then that bit
corresponds to LCN=LBN*8+BITN (logical cluster number).
Cluster space allocation is done by taking the previously
allocated cluster number (to a file) as the starting point of a
search for a free cluster. Searches toward logical cluster number
0 and NLCN-1 are both made in an attempt to minimize the distance
between the cluster number (allocated to the preceding cluster in
the file) and the new. Furthermore, an old cluster number of
:FFFF causes allocation starting at a random place within the
map.
The allocator prefers a forward search, and will not bother with
a backwards search if it can get a distance of 1 between the old
cluster number and the new.
COPYRIGHT (C) 1978 118 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION VI: SDOS CONSTRUCTION/FUNCTIONS
DISK CLUSTER ALLOCATION MAP
MSB represents Logical Cluster #7
|
| LSB corresponds to Logical Cluster #0
| !
__V__________________V__
BYTE #0 ! !<--Logical Clusters #0-7
#1 ! !<--#8-15
#2 ! !<--#16-23
. ! !<--#24-31
. ! !
. ! !
. ! !
! !
! !
! !
! !
! !
! !
! !
! !
^ ! !
| ! !
| ! !
One Cluster ! /-------------- Bit # (NLCN-1) mod 8
| !___________V__ ! (max legal cluster number)
| !/////////! ! !
v !/////////!___!________!
!//////////////////////!
!//////////////////////!
!//////////////////////!
NOTE: Sector !//////////////////////!
Containing Bit !//////////////////////!
For NLCN-1 is !///////ILLEGAL////////!
Null Filled With !///////CLUSTER////////!
1's to Make it !///////NUMBERS////////!
Appear that the !//////////////////////!
Illegal LCNs !//////////////////////!
are allocated. !//////////////////////!
!//////////////////////!
!----------------------!
A "1" bit --> cluster is busy
A "0" bit --> cluster is free (available).
COPYRIGHT (C) 1978 119 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION VI: SDOS CONSTRUCTION/FUNCTIONS
ERRORMSGS.SYS (ERROR MESSAGE FILE) FORMAT:
The ERRORMSGS.SYS file is used by SDOS to convert 16 bit error
codes into English text messages for the operator.
The file must exist on the default disk, and the default disk
must be mounted, in order for SDOS to use the file (otherwise
SDOS merely prints "Error nnnnn").
The file is organized into two parts, and is sparse.
The first part of the file converts 16 bit error codes into
string pointers into the file. The second part of the file
contains the raw error message text.
The 16 bit error code is multiplied by 3, and used as a byte
index on the file to fetch a 3 byte relative index into the file.
The 3 byte index points to an ASCII error message string, ending
with a CR (:0D) character. The SDOS error routines do not print
the CR explicitly but use it only to decide where the end of the
error message is (see SYSCALL:DISPERROR). A 3 byte index value
of zero means "no message defined".
The first 65536*3=196608 bytes of the file are reserved for this
lookup; since the number of error messages actually defined out
of the 65536 possible is very small, this region of the file is
sparsely allocated. The first text message starts in byte number
65536*3 of the file. This section of the file is dense.
New messages are added to the file by merely appending them to
the end, and adjusting the 3 byte pointer corresponding to the
error code to point to the old end of file.
The program SDOSERRORMAINT is used to maintain the contents of
this file. The file ERRORMSGBUILD.DO is a DO file used to
initially construct this file.
ERROR MESSAGE NUMBER ASSIGNMENTS:
0 No Error
1 Operator Requested Attention
2-99 BASIC Compiler Runtime Errors
100-199 Errors Related to System Processors, Etc.
200-299 EDITor Errors
300-999 Application System Dependent Errors
1000-1999 SDOS / I/O Errors
2000-65535 Reserved
COPYRIGHT (C) 1978 120 Software Dynamics
SDOS APPLICATION PROGRAMMERS' GUIDE
SECTION VI: SDOS CONSTRUCTION/FUNCTIONS
BUILDING A TURN-KEY APPLICATION SYSTEM
In many circumstances, the full generality of an SDOS development
system is not needed; a simple menu-driven application program
selector plus the applications is sufficient. This is useful in
an office environment because it reduces the training required of
the office personnel.
Only two things need be done to build a turn-key application
system:
1) The boot process needs to be made automatic. This procedure
is hardware dependent and is not described further here.
2) The DEFAULTPROGRAM on an otherwise bootable SDOS disk needs to
be replaced by the menu-display program. This program may
contain the entire application, or it may CHAIN to other
segments at the appropriate time. The other segments, on
completion, will EXIT, which causes DEFAULTPROGRAM (the
menu-display program) to be reloaded, and the cycle repeats.
Note that the application program must set the time and date
itself by doing a WRITEB to the CLOCK$ device.
System development can still continue on a turn-key system if the
menu program has a way of chaining to SDOSCOMMANDS, or if a
regular development disk is inserted (just the boot part is
automatic).
If DEFAULTPROGRAM is replaced by a compiled BASIC 1.4 program,
the 1.4 program must be combined with a runtime package.
COPYRIGHT (C) 1978 121 Software Dynamics
TABLE OF CONTENTS
INTRODUCTION . . . . . . . . . . . . . . . . . . . . . 1.2
SECTION I: DEVICE-DEPENDENT I/O . . . . . . . . . . . . 1
DEVICE-INDEPENDENT I/O . . . . . . . . . . . . . . . 1
SECTION II: DEVICE DRIVERS . . . . . . . . . . . . . . 5
DEVICE DRIVER CHARACTERISTICS . . . . . . . . . . . 5
DISK FILE DRIVER . . . . . . . . . . . . . . . . . . 6
DISK DEVICE DRIVER . . . . . . . . . . . . . . . . . 11
VIRTUAL TERMINAL DRIVER . . . . . . . . . . . . . . 14
OPEN & CREATE . . . . . . . . . . . . . . . . . . 15
CLOSE . . . . . . . . . . . . . . . . . . . . . . 15
RENAME & DELETE . . . . . . . . . . . . . . . . . 15
READA & WRITEA . . . . . . . . . . . . . . . . . 16
READB . . . . . . . . . . . . . . . . . . . . . . 16
VTCONTROL . . . . . . . . . . . . . . . . . . . . . 16
CC:POSITION . . . . . . . . . . . . . . . . . . . 18
CC:DUMPBUFFERS . . . . . . . . . . . . . . . . . 18
CC:ECHO . . . . . . . . . . . . . . . . . . . . . 18
CC:NOECHO . . . . . . . . . . . . . . . . . . . . 18
CC:WRAP . . . . . . . . . . . . . . . . . . . . . 18
CC:NOWRAP . . . . . . . . . . . . . . . . . . . . 18
CC:IDLES . . . . . . . . . . . . . . . . . . . . 18
CC:TABS . . . . . . . . . . . . . . . . . . . . . 19
CC:SETACTBLOCK . . . . . . . . . . . . . . . . . 19
CC:CLRINPUT . . . . . . . . . . . . . . . . . . . 19
CC:CLROUTPUT . . . . . . . . . . . . . . . . . . 19
CC:SETREADTIMEOUT . . . . . . . . . . . . . . . . 20
CC:SETPROFILE . . . . . . . . . . . . . . . . . . 20
CC:ALTERPROFILE . . . . . . . . . . . . . . . . . 21
CC:WRITEEDITLINE . . . . . . . . . . . . . . . . 22
CC:SETFIELDSIZE . . . . . . . . . . . . . . . . . 23
CC:SETPARAMS . . . . . . . . . . . . . . . . . . 23
CC:ACTIVATIONCK . . . . . . . . . . . . . . . . . 24
CC:SETBAUDRATE . . . . . . . . . . . . . . . . . 24
CC:COLORING . . . . . . . . . . . . . . . . . . . 25
CC:BACKGROUND . . . . . . . . . . . . . . . . . . 26
CC:KILLPROOF . . . . . . . . . . . . . . . . . . 26
CC:KILLENABLE . . . . . . . . . . . . . . . . . . 26
CC:SETEXCEPTIONS . . . . . . . . . . . . . . . . 26
CC:SETOUTPUTTIMEOUT . . . . . . . . . . . . . . . 26
VTSTATUS . . . . . . . . . . . . . . . . . . . . . . 27
SC:GETPOS . . . . . . . . . . . . . . . . . . . . 27
SC:GETCOL . . . . . . . . . . . . . . . . . . . . 27
SC:GETEOF . . . . . . . . . . . . . . . . . . . . 27
SC:GETTYPE . . . . . . . . . . . . . . . . . . . 27
SC:GETPARAMS . . . . . . . . . . . . . . . . . . 27
SC:GETPROFILE . . . . . . . . . . . . . . . . . . 27
SC:GETPROFILENAME . . . . . . . . . . . . . . . . 27
SC:GETPROFILEALTERATION . . . . . . . . . . . . . 28
COPYRIGHT (C) 1978 Software Dynamics
SC:GETFREECOUNT . . . . . . . . . . . . . . . . . 28
SC:GETDATACOUNT . . . . . . . . . . . . . . . . . 28
SC:GETOUTPUTTIMEOUT . . . . . . . . . . . . . . . 28
SC:GETBAUDRATE . . . . . . . . . . . . . . . . . 28
SC:GETTABS . . . . . . . . . . . . . . . . . . . 28
SC:GETIDLES . . . . . . . . . . . . . . . . . . . 28
SC:GETWRAP . . . . . . . . . . . . . . . . . . . 28
SC:GETCOLORING . . . . . . . . . . . . . . . . . 28
SC:GETBACKGROUND . . . . . . . . . . . . . . . . 28
SC:GETACTCOL . . . . . . . . . . . . . . . . . . 29
SC:ATTENTIONCK . . . . . . . . . . . . . . . . . 29
SC:STATUSCK . . . . . . . . . . . . . . . . . . . 29
CONTROL CHARACTERS . . . . . . . . . . . . . . . . . 30
SWITCHES . . . . . . . . . . . . . . . . . . . . . . 35
SDOS/MT SUPPORT . . . . . . . . . . . . . . . . . . 36
MULTI-USER CONTROL FUNCTIONS . . . . . . . . . . 36
MULTI-USER STATUS FUNCTIONS . . . . . . . . . . . 37
THE CLOCK: DEVICE DRIVER . . . . . . . . . . . . . . 38
SECTION III: SYSCALLS . . . . . . . . . . . . . . . 39
CONCEPTS . . . . . . . . . . . . . . . . . . . . 39
SYSCALL FORMAT . . . . . . . . . . . . . . . . . 40
SECTION IV: ERROR HANDLING . . . . . . . . . . . . . 43
SECTION V: SYSCALLS - IMPLEMENTATION . . . . . . . . 46
IMPLEMENTATION . . . . . . . . . . . . . . . . . 46
SYSCALL:OPEN . . . . . . . . . . . . . . . . . 47
SYSCALL:CREATE . . . . . . . . . . . . . . . . 48
SYSCALL:CLOSE . . . . . . . . . . . . . . . . 49
SYSCALL:RENAME . . . . . . . . . . . . . . . . 50
SYSCALL:DELETE . . . . . . . . . . . . . . . . 51
SYSCALL:LOAD . . . . . . . . . . . . . . . . . 52
SYSCALL:CHAIN . . . . . . . . . . . . . . . . 54
SYSCALL:CREATELOG . . . . . . . . . . . . . . 55
SYSCALL:CLOSELOG . . . . . . . . . . . . . . . 57
SYSCALL:DISKDEFAULT . . . . . . . . . . . . . 58
SYSCALL:READA . . . . . . . . . . . . . . . . 59
SYSCALL:READB . . . . . . . . . . . . . . . . 61
SYSCALL:WRITEA . . . . . . . . . . . . . . . . 63
SYSCALL:WRITEB . . . . . . . . . . . . . . . . 64
SYSCALL:CONTROL . . . . . . . . . . . . . . . 65
CC:POSITION . . . . . . . . . . . . . . . . 66
CC:DUMPBUFFERS . . . . . . . . . . . . . . 67
SYSCALL:STATUS . . . . . . . . . . . . . . . . 68
SYSCALL:WAITDONE . . . . . . . . . . . . . . . 70
SYSCALL:EXIT . . . . . . . . . . . . . . . . . 71
SYSCALL:ERROREXIT . . . . . . . . . . . . . . 72
SYSCALL:SETERROR . . . . . . . . . . . . . . . 74
SYSCALL:GETERROR . . . . . . . . . . . . . . . 75
SYSCALL:DISPERROR . . . . . . . . . . . . . . 76
SYSCALL:KILLPROOF . . . . . . . . . . . . . . 77
SYSCALL:KILLENABLE . . . . . . . . . . . . . . 78
SYSCALL:DEBUG . . . . . . . . . . . . . . . . 79
COPYRIGHT (C) 1978 Software Dynamics
SYSCALL:ATTNCHECK . . . . . . . . . . . . . . 80
SYSCALL:ISCONSOLE . . . . . . . . . . . . . . 81
SYSCALL:INTERLOCK . . . . . . . . . . . . . . 82
SYSCALL:DELAY . . . . . . . . . . . . . . . . 84
SYSCALL:GETSERIALNUMBER . . . . . . . . . . . 85
SECTION VI: SDOS CONSTRUCTION/FUNCTIONS . . . . . . 90
WRITING AND DEBUGGING USER ASSEMBLY PROGRAMS . . 90
MEMORY MAP . . . . . . . . . . . . . . . . . . . 91
SDOS LOADER FORMATS . . . . . . . . . . . . . . . 93
SDOS LOAD RECORD FORMATS . . . . . . . . . . . . 93
ENCRYPTED OBJECT FILES . . . . . . . . . . . . . 97
SDOS DISK FILE STRUCTURE . . . . . . . . . . . . 98
LOGICAL SECTOR NUMBERS (LSN) . . . . . . . . . . 99
CLUSTERS (LCN) . . . . . . . . . . . . . . . . . 100
DISK FILE STRUCTURE . . . . . . . . . . . . . . . 102
SDOS FILE STRUCTURE . . . . . . . . . . . . . . . 105
DIRECTORY.SYS STRUCTURE . . . . . . . . . . . . . 107
THE BOOT.SYS FILE . . . . . . . . . . . . . . . . 113
SERIALNUMBER.SYS . . . . . . . . . . . . . . . . 116
SDOS.SYS . . . . . . . . . . . . . . . . . . . . 117
DISKMAP.SYS . . . . . . . . . . . . . . . . . . . 118
ERRORMSGS.SYS FORMAT . . . . . . . . . . . . . . 120
BUILDING A TURN-KEY APPLICATION SYSTEM . . . . . 121
COPYRIGHT (C) 1978 Software Dynamics