Gimix_6809_Flex_V4 Gimix 6809 Flex V4

Gimix_6809_Flex_V4 Gimix_6809_Flex_V4

User Manual: Gimix_6809_Flex_V4

Open the PDF directly: View PDF .
Page Count: 227

Download
Open PDF In Browser	View PDF

6809 PlEH™
OpfZfating
SY/tfZm

technical fYftemf
confultantf, inc.

The FLEX™ Disk Operating System

Technical Systems Consultants, Inc.

This entire manual is provided for the personal use and enj oyment of the purchaser. Its
contents are copyrighted by Technical Systems Consultants, Inc., and reproduction, in
whole or in part, by any means is prohibited. Use of this program, or any part thereof,
for any purpose other than single end use by the purchaser is prohibited.

DISa..AIMER

The supplied software is intended for use only as described in this manual. Use of
undocumented features or parameters may cause unpredictable results for which Technical
Sys tems Consultants, Inc. cannot assume responsibility. Although every effort has been
made to make the supplied software and its documentation as accurate and functional as
possible, Technical Systems Consultants, Inc. will not assume responsibility for any
damages incurred or generated by such material. Technical Systems Consultants, Inc.
reserves the right to make changes in such material at any time without notice.

(

FLEX User's Manual

COPYRIGHT Cl 1979 by
Technical Systems Consultants, Inc.
P.O. Box 2570
West Lafayette, Indiana 47906
All Righ ts Reserved

R.EX is a trademark of Technical Systems Consultants, Inc.

COPYR IGHT INFORMATION

fhis entire manual is provided for the personal use and enjoyment of the purchaser. Its
contents are copyrighted by Technical Systems Consultants, Inc., and reproduction, in
whole or in part, by any means is prohibited. Use of this program, or any part thereof,
for any purpose other than single end use by the purchaser is prohibited.

D ISCLA IMER

The supplied software is intended for use only as described in this manual. Use of
undocumented features or parameters may cause unpredictable results for which Technical
Systems Consultants, Inc. cannot assume responsibility. Although every effort has been
made to make the supplied software and its documentation as accurate and functional as
possible, Technical Systems Consultants, Inc. will not assume responsibility for any
damages incurred or generated by such material. Technical Systems Consultants, Inc.
reserves the right to make changes in such material at any time without notice.

PREFACE
The purpose of this User1s Guide is to provide the user of the FLEX
Operating System with the information required to make effective use of
the available system commands and utilities. This manual applies to
FLEX 9.0 for full size and mini floppy disks. The user should keep this
manual close at hand while becoming familiar with the system. It is
organized to make it convenient as a quick reference guide, as well as a
thorough reference manual.

-iii-

-iv-

GIMIX FLEX USER NOTES 1
The following programs in the TSC 6809 DISK DIAGNOSTICS package
will not work with GIMIX FLEX 4.0.
PROGRAM NAME

NOTES

TEST.CMD

Will give errors for track 00 on a
double density 5" disk.

VALIDATE.CMD

Will abort with the message 'INV~LID
SYSTEM INFO SECTOR'. This only applies
to 5" disks formatted for more than 40
tracks or formatted double density, or 8"
disks formatted for more than 77 tracks.

COPYR.CMD

Same as 'TEST.CMD' above.

EXAMINE.CMD

Same as 'TEST.CMD' above.

FLAW.CMD

Same as 'TEST.CMD' above.

REBUILD.CMD

Same as 'TEST.CMD' above.

NOTE:
This is because these programs do not support double
density or more than 40 tracks on 5" disks, or more than 77
tracks on 8" disks.
FLEX UTILITIES
All FLEX utilities from TSC run correctly withGIMIX FLEX except
DIR. This program can cause the system to hang or crash if it is
used while the print spooler is active. This is due to the way
the spooler uses the stack. OIR will function perfectly when the
print spooler is not active.

FLEX is a trademark of
Hill,North Carolina.
GIMIX is
Illinois.

registered

Technical
trademark

Systems
of

Consultants,

GIMIX,

Inc.,

Chapel
Chicago,

GIMIX FLEX 4.0 ADDENDUM SHEET
Page 1. 2
Paragraph II (SYSTEM REQUIREMENTS)
GIMIX FLEX requires
location $3FFF as well as
location $DFFF.

memory
memory

from
from

location
location

$0000
$COOO

through
through

Paragraph III (GETTING THE SYSTEM STARTED)
When using GMXBUG-09 with the Disk Boot Prom installed type
lUI followed by a carriage return in response to the GMXBUG-09
prompt.
If you have a video system and have a Disk Boot Prom then
the lUI command will bootstrap the system.
Page 1. 3
Paragraph IV (DISK FILES AND THEIR NAMES)
The actual number of sectors available to the user may vary
according the density, number of tracks, and size of the disk, and
whether one or ~oth sides were formatted.
See the 'FORMAT'
command for more information.
Page 2.1
Paragraph 7 (GENERAL SYSTEM FEATURES)
In addition to the features already mentioned GIMIX FLEX also
gives ~he user the following additional· features: selection of
stepping speed, write protec~, and "double stepping" from the
console, and automatic density selection.
See the SYSGEN and
SETUP commands for more information.
Paragraph I (DISK CAPACITY)
See addendum for Paragraph IV, Page 1.3
Paragraph V (ACCESSING DRIVES NOT CONTAINING A DISKETTE)
If a 5" drive which doesn't have a disk in it i$ accessed,
the system will hang Up until the user puts a disk in the drive.
This applies to all older 5" drive models. Some new 5" drives
have a READY/NOT READY output.
If one of ~fiese drives is accessed
when it is empty, FLEX will return
'DRIVES NOT READY'.
Page 3.4
Paragraph VIII
GIMIX

(FLEX OPERATING SYSTEM INPUT/OUTPUT SUBROUTINES)

FLEX

uses

the

GMXBUG-09

-a. i-

(SBUG-E

compatible)

input/output routines for total system compatibility.
Page 3.6
Paragraph IX (BOOTING THE FLEX DISK OPERATING SYSTEM)
If neither the VIDEO prom or the Disk Boot Prom is installed
in the system the user must hand enter the bootstrap. The GIMIX
FLEX bootstrap is listed on the sheet entitled
'GIMIX 6809
RELOCATABLE DISK BOOT'.
For instructions on how to enter this
bootstrap see the GMXBUG-09 manual.
Page 3.7
Paragraph X (REQUIREMENTS FOR THE 'PRINT.SYS' DRIVER)
Object code and source code for two printer drivers is
supplied on the GIMIX FLEX system disk, one each for parallel and
serial interfaces. List the file 'READ-ME' on the system disk for
more information.
NOTE:
GIMIX FLEX does not have a 'NEWDISK' command.
has been replaced with the "FORMAT.' command.

This

*********************************
*********************************
*****
WARNING!
*****
*********************************
*********************************
The disk driver routines in GIMIX FLEX 4.0 have been
completely rewritten.
The USEMPT,
USEDC4,
USEDMF, and UNUSE
commands are not usable with this FLEX. ANY ATTEMPT TO USE THEM
WITH GIMIX FLEX 4.0 WILL CRASH THE SYSTEM!!!
Users who still need
to access DC4 and DMF format disks must use GIMIX FLEX 3.6. Also,
the SETUP, REPORT, and BACKUP commands have been rewritten for
GIMIX FLEX 4.0. The 3.X versions of these commands will not work,
and may crash the system!

-a.1i-

TABLE OF CONTENTS
Page

CHAPTER I
I.

II.
I II.
IV.
V.
VI.
CHAPTER 2
I.

Introduction
System Requirements
Getting the System Started
Disk Files and Their Names
Entering Commands
Command Descriptions

1.1
a.i , 1.2
a.i , 1.2
a.i , 1.3
1.5
1.7
2.1

Utility Command Set

A.1

APPEND
ASN
BUILD
t*BACKUP
CAT
*COPY (-GMX,-TSC)
*CLEAN
*CHECKSUM
*CMPBIN
DATE
DELETE
*DCOPY
EXEC
*EXTEND
*FORMAT
*FIXDAY
*FREEMAP
t*HARD
t*HARDFORM

A.2
B.1

B.2
C.1
C.2
C.3
C.4
C.5
D.1

D.2
D.3
E.I
E.2
F.1
F.2
F.3

H.1
H.2
1.1
J.1

JUMP
LINK
LIST
*NAME
*N

L.I
L.2
N .1

N.2
0.1
P.I
P.2
P.3
Q.1

o
P

PRINT
PROT
QCHECK
RENAME
*REPORT
SAVE
STARTUP
*SETTIME
*SETUP
t*SYSGEN
TTYSET
*TIME
* UPDATE
*UNSNARL
VERIFY
VERSION
XOUT
*YEAR
*Y

R.I
R.2
S.l

5.2
S.3
S.4
S.4
T .1
T.2

U.1
U.2
V.1

V.2
X.l
Y.1

Y.2

-v-

CHAPTER 3
I.

II.
I II.
IV.

V.
VI.
VII.
VIII.
IX.
X.
XI.
XII.
CHAPTER 4
I.

Disk Capacity
Write Protect
The 'RESET' Button
Notes on the P Command
Accessing Drives Not Containing a Disk
System Error Numbers
System Memory Map
Flex Input/Output Subroutines
Booting the Flex Disk Operating System
Requirements for 'PRINT.SYS' driver
Hardware Configuration
Patching FLEX to use the Time-of-Day clock

3.1
3.1
3.1
3.1
3.1
3.2

a.i
a.ii
a.ii
a.i
(see

3.3
, 3.4
, 3.6
, 3.7
, 3.10
SYSGEN)
4.1

Command Summary

These programs are not interchangeable with earlier versions of
similar programs or other versions ofGIMIX/FLEX

Programs supplied by GIMIX

-vi-

FLEX USER'S MANUAL

INTRODUCTION

The FLEX m Operating System is a very versatile and flexible operating
system. It provides the user with a powerful set of system commands to
control all disk operations directly from the user's terminal. The
systems programmer will be delighted with the wide variety of disk
access and file management routines available for personal use.
Overall, FLEX is one of the most powerful operating systems available
today.
The FLEX Operating System is comprised of three parts, the File
Management System (FMS), the Disk Operating System (DOS), and the
Utility Command Set (UCS). Part of the power of the overall system lies
in the fact that the system can be greatly expanded by simply adding
additional utility commands. The user should expect to see many more
utilities available for FLEX in the future. Some of the other important
features include: fully dynamic file space allocation, the automatic
"removal"
of defective sectors from the disk, automatic space
compression and expansion on all text files, complete user environment
control using the TTYSET utility command, and uniform disk wear due to
the high performance dynamic space allocator.
The UCS currently contains many very useful commands. These programs
reside on the system disk and are only loaded into memory when needed.
This means that the set of commands can be easily extended at any time,
without the necessity of replacing the entire operating system.
The
utilities provided with FLEX perform such tasks as the saving, loading,
copying, renaming, deleting, appending, and listing of disk files.
There is an extensive CATalog command for examining the disk's file
directory. Several environment control commands are also provided.
Overall, FLEX provides all of the necessary tools for the user's
interaction with the disk.

* FLEX is a registered

trademark

Consultants, Inc.

-1.1-

Technical

Systems

FLEX User's Manual
II.

SYSTEM REQUIREMENTS

FLEX requires random access memory from location 0000 through location
2FFF hex (12K). Memory is also required from COOO (48K) through DFFF
hex (56K), where the actual operating system resides. The system also
assumes at least 2 disk drives are connected to the controller and that
they are configured as drives #0 and #1. You should consult the disk
drive instructions for this information. FLEX interfaces with the disk
controller through a section of driver routines and with the operator
console or terminal through a section of terminal I/O routines.
III.

GETTING THE SYSTEM STARTED

Each FLEX system diskette contains a binary loader for loading the
operating system into RAM. There needs to be some way of getting the
loader off of the disk so it can do its work.
This can be done by
either hand entering the bootstrap loader provided with the disk system,
or by using the boot provided in ROM if appropriate to FLEX.
As a specific example, suppose the system we are using has SWTPc's S-8UG
installed and we wish to run FLEX. The first step is to power on all
equipment and make sure the S-8UG prompt is present (». Next insert
the system diskette into drive a (the boot must be performed with the
disk in drive a) and close the door on the drive. Type "0" on the
terminal if using a full size floppy system or "u" if a minifloppy
system. The disk motors should start, and after about 2 seconds, the
following should be displayed on the terminal:
FLEX X.X
DATE (MM,DD,YY)?
+++

The name FLEX identifies the operating system and the X.X will be the
version number of the operating system. At this time the current date
should be entered, such as 7,3,79. The FLEX prompt is the three plus
signs (+++), and will always be present when the system is ready to
accept an operator command. The '+++' should become a familiar sight
and signifies that FLEX is ready to work for you!

-1.2-

FLEX User's Manual
IV.

DISK FILES AND THEIR NAMES

All disk files are stored in the form of 'sectors' on the disk and in
this version, each sector contains 256 'bytes' of information. Each
byte can contain one character of text or one byte of binary machine
information. A maximum of 340 user-accessible sectors will fit on a
single-sided mini disk or 1140 sectors on a single-sided full size
floppy. Double-sided disks would hold exactly twice that number of
sectors. Double-density systems will hold more still.
The user,
however, need not keep count, for the system does this automatically. A
file will always be at least one sector long and can have as many as the
maximum number of sectors on the disk. The user should not be concerned
with the actual placement of the files on the disk since this is done by
the operating system.
File deletion is also supported and all
previously used sectors become immediately available again after a file
has been deleted.
All files on the disk have a name.
typical:

Names such

as the following

are

PAYROLL
INVNTORY
TEST1234
APRIL-78
WKLY-PAY
Anytime a file is created, referenced, or deleted, its name must be
used. Names can be most anything but must begin \,/ith a letter (not
numbers or symbols) and be followed by at most 7 additional characters,
called 'name characters'.
These 'name characters'
can be any
combination of the letters lA' through 'II or 'a' through IZ', any digit
'0' through '9 or one of the two special characters, the hyphen (-) or
the underscore' I, (a left arrow on some terminals).
1 ,

File names must also contain an 'extension'. The file extension further
defines the file and usually indicates the type of information contained
therein. Examples of extensions are: TXT for text type files, BIN for
machine readable binary encoded files, CMD for utility command files,
and BAS for BASIC source programs. Extensions may contain up to 3 'name
characters' with the first character being a letter. Most of the FLEX
commands assume a default extension on the file name and the user need
not be concerned with the actual extension on the file. The user may at
anytime assign new extensions, overiding the default value, and treat
the extension as just part of the file name. Some examples of file
names with thei r extens ions foll 0\,/:
APPEND.CMD
LEDGER. BAS
TEST. BIN
Note that the extension is always separated from the name by a period
"
The period is the name 'field separator'. It tells FLEX to treat
the following characters as a new field in the name specification.

-1.3-

FLEX User1 sManua 1
A file name can be further refined. The name and extension uniquely
define a file on a particular drive, but the same name may exist on
several drives simultaneously. To designate a particular drive a 'drive
number' is added to the file specification. It consists of a single
digit (0-3) and is separated from the name by the field separator '.'.
The drive number may appear either before the name or after it (after
the extension if it is given).
If the drive is not specified, the
system will default to either the 'system' drive or the 'working' drive.
These terms will be described a little later.
Some examples of file specifications with drive numbers follow:
O.BASIC
MONDAY.2
1. TEST. BIN
LIST. CMD.1
In summary, a file specification may contain up to three fields
separated by the field separator. These fields are; 'drive', 'name',
and 'extension'. The rules for the file specification can be stated
quite concisely using the following notation:
[.][.]
or
[.][.]
The '<>' enclose afield and do not actually appear in the
specification, and the
'[]'
surround optional
items of the
specification. The following are all syntactically correct:
O.NAME.EXT
NAME.EXT.O
NAME. EXT
O.NAME
NAME. 0
NAME
Note that the only required field is the actual 'name' itself and the
other values will usually default to predetermined values. Studying the
above examples will clarify the notation used. The same notation will
occur regularly throughout the manual.

-1.4-

FLEX User's Manual

ENTERING COMMANDS

When FLEX is displaying 1+++1, the system is ready to accept a command
line. A command line is usually a name followed by certain parameters
depending on the command being executed. There is no 'RUN ' command in
FLEX. The first file name on a command line is always loaded into memory
and execution is attempted. If no extension is given with the file
name, 'CMD ' is the default.
If an extension is specified, the one
entered is the one used. Some examples of commands and how they would
look on the terminal follow:
+++TTYSET
+++TTYSET.CMD
+++LOOKUP.BIN
The first two lines are identical to FLEX since the first would default
to an extension of CMD. The third line would load the binary file
'LOOKUP.BIN' into inemory and, assuming the file contained a transfer
address, the program would be executed. A transfer address tells the
program loader where to start the program executing after it has been
loaded. If you try to load and execute a program in the above manner and
no transfer address is present, the message, 'NO LINK' will be output to
the terminal, where'link' refers to the transfer address.
Some other
error messages which can occur are IWHAT? I if an illegal file
specification has been typed as the first part of a command line, and
'NOT THERE I if the file typed does not exist on the disk.
During the typing of a command line, the system simply accepts all
characters until a 'RETURN ' key is typed. Any time before typing the
RETURN key, the user may use one of two special characters to correct
any mi styped characters. One of these characters is the I back space I
and allows deletion of the previously typed character. Typing two back
spaces will delete the previous two characters. The back space is
initially defined to be a 'control HI but may be redefined by the user
using the TTYSET utility command. The second special character is the
line 'delete ' character. Typing this character will effectively delete
all of the characters which have been typed on the current line. A new
prompt will be output to the terminal, but instead of the usual 1+++1
prompt, to show the action of the delete character, the prompt will be
I???I. Any'time the delete character is used, the new prompt will be
I???I, and signifies that the last line typed did not get entered into
the computer. The delete character ;s initially a 'control XI but may
also be redefined using TTYSET.

-1.5-

FLEX User's Manual
As mentioned earlier, the first name on a command line is always
interpreted as a command. Following the command is an optional list of
names and parameters, depending on the particular command being entered.
The fields of a command line must be separated by either a space or a
comma. The general format of a command line is:
[,]
FLEX also allows several
A comma is shown, but a space may be used.
commands to be entered on one command line by use of the lend of line '
character. This character is initially a colon (1:1), but may be user
defined with the TTYSET utility. By ending a command with the end of
line character, it is possible to follow it immediately with another
command. FLEX will execute all commands on the line before returning
with the 1+++1 prompt. An error in any of the command entries will
cause the system to terminate operation of that command line and return
with the prompt. Some examples of valid command lines follow:
+++CAT 1
+++CAT l:ASN $=1
+++LIST LIBRARY:CAT l:CAT 0
As many commands may be typed in one command line as desired, but the
total number of characters typed must not exceed 128. Any excess
characters will be ignored by FLEX.
One 1ast system feature to be described is the idea of Isystem I and
'working ' drives. As stated earlier, if a file specification does not
specifically designate a drive number, it will assume a default value.
This default value will either be the current Isystem I drive assignment
or the current 'working ' drive assignment. The system drive is the
default for all command names, or in other words, all fi 1e names wh i ch
are typed first on a command line. Any other file name on the command
line will default to the working drive.
This version of FLEX also
supports automatic drive searching. When in the auto search mode if no
drive numbers are specified, the operating system will first search
drive 0 for the file.
If the file is not found, drive 1will be
searched and so on. When the system is first initialized the auto drive
searching mode will be selected. At this time, all drive defaults will
be to drive O. It is sometimes canvenient to assign drive 1 as the
working drive in which case all file references, except commands, will
automatically look on drive 1. It is then convenient to have a diskette
in drive 0 with all the system utility commands on it (the Isystem
drivel), and a disk with the files being worked on in drive 1 (the
'working drivel). If the system drive is 0 and the working drive is 1,
and the command 1i ne was:
.
+++LIST TEXTFILE
FLEX would go to drive 0 for the command LIST and to drive 1 for the
file TEXTFILE. The actual assignment of drives is performed by the ASN
utility. See its description for details.

-1.6-

FLEX User's Manual
VI.

COMMAND DESCRIPTIONS

There are two types of commands in FLEX, memory resident (those which
actually are part of the operating system) and disk utility commands
(those commands which reside on the disk and are part of the UCS).
There are only two resident commands, GET and MON. They will be
described here while the UCS is described in the following sections.
GET
The GET command is used to load a binary file into memory.
It is a
special purpose command and is not often used. It has the following
syntax:
GET[,]
where is: [,] etc.
Again the I[]I surround optional items. 'File spec l denotes a file name
as described earlier. The action of the GET command is to load the file
or files specified in the list into memory for later use.
If no
extension is provided in the file spec, BIN is assumed, in other words,
BIN is the default extension. Examples:
GET, TEST
GET~1.TEST,TEST2.0

where the first example will load the file named 'TEST.BIN ' from the
assigned working drive, and the second example will load TEST.BIN from
drive 1 and TEST2.BIN from drive O.
MON
MON is used to exit FLEX and return to the hardware monitor system such
as S-BUG. The syntax for this command is simply MON followed by the
I RETURN I key.
NOTE: to re-enter FLEX after using the MON command, you should enter the
program at location CD03 hex.

-1. 7.;.

UTILITY COMMAND SET
The following pages describe all of the utility commands currently
included in the UCS. You should note that the page numbers denote the
first letter of the command name, as well as the number of the page for
a particular command. For example, 'B.1.2' is the 2nd page of the
description for the 1st utility name starting with the letter 'B'.
COMMON ERROR MESSAGES
Several error messages are COmmon to many of the FLEX utility commands.
These error messages and their meanings include the following:
NO SUCH FILE. This message indicates that a file referenced in a
particular command was not found on the disk specified.
Usually the
wrong drive was specified (or defaulted), or a misspelling of the name
was made.
ILLEGAL FILE NAME.
This can happen if the name or extension did
not start with a letter, or the name or extension field was too long
(limited to 8 and 3 respectively). This message may also mean that the
command being executed expected a file name to follow and one was not
provided.
FILE EXISTS. This message will be output if you try to create a
file with a name the same as one which currently exists on the same
disk. Two different files with the same name are not allowed to exist on
the same disk.
SYNTAX ERROR, This means that the command line just typed does not
follow the rules stated for the particular command used. Refer to the
individual command descriptions for syntax rules.
GENERAL SYSTEM FEATURES
Any time one of the utility commands is sending output to the terminal,
it may be temporarily halted by typing the 'escape' character (see
TTYSET for the definition of this character).
Once the output is
stopped, the user has two choices: typing the 'escape' character again
or typing 'RETURN'. If the 'escape' character is typed again, the
output will resume.
If the 'RETURN' is typed, control will return to
FLEX and the command will be terminated. All other characters are
ignored while output is stopped.

-2.1-

APPEND
The APPEND command is used to append or concatenate two or more files,
creating a new file as the result. Any type of file may be appended but
it only makes sense to append files of the same type in most cases. If
appending binary files which have transfer addresses associated with
them, the transfer address of the last file of the list will be the
effective transfer address of the resultant file. All of the original
files will be left intact.
DESCRIPTION
The general syntax for the APPEND command is as follows:
APPEND,[,],
where can be an optional list of the specifications. The
last name specified should not exist on the disk since this will be the
name of the resultant file. If the last file name given does exist on
the di sk, the question "MAY THE EXISTING FILE BE DELETED? II wi 11 be
displayed. A Y response will delete the current file and cause the
APPEND operation to ·be completed. A N response will terminate the
APPEND operation. All other files specified must exist since they are
the ones to be appended together. If only 2 file names are given, . the
first file will be copied to the second file. The extension default is
TXT unless a different extension is used on the FIRST FILE SPECIFIED, in
which case that extension becomes the default for the rest of the
command line. Some examples will show its use:
APPEND,CHAPTERl,CHAPTER2,CHAPTER3,BOOK
APPEND,FILEl,1.FILE2.BAK,GOODFILE
The first line would create a file on the working drive called
'BOOK.TXT' which would contain the files 'CHAPTERl.TXT', CHAPTER2.TXT',
and 'CHAPTER3.TXT' in that order. The second example would append
'FILE2.BAK' from drive 1 to FILEl.TXT from the working drive and put the
result in a file called 'GOODFILE.TXT' on the working drive. The file
GOODFILE defaults to the extension of TXT since it is the default
extension. Again, after the use of the APPEND command, all of the
original files will be intact, exactly as they were before the APPEND
operation.

-A.l.l-

ASN
The ASN command is used for assigning the 'system' drive and the
'working' drive or to select automatic drive searching. The system
drive is used by FLEX as the default for command names or, in general,
the first name on a command line. The working drive is used by FLEX as
the default on all other file specifications within a command line.
Upon initialization, FLEX assigns drive #0 as both the system and
working drive. An example will show how the system defaults to these
values:
APPEND,FILEl,FILE2,FILE3
If the system drive is assigned to be #0 and the working drive is
assigned to drive #1, the above example will perform the following
operation: get the APPEND command from drive #0 (the system drive), then
append FILE2 from drive #1 (the working drive) to FILEI from drive #1
and put the result in FILE3 on drive #1. As can be seen, the system
drive was the default for APPEND where the working drive was the default
for all other file specs listed.
Automatic drive searching causes FLEX to automatically scan the ready
drives for the file specified. Hardware limitations prevent the mini
floppy versions from searching for "ready" drives. For this reason,
FLEX has been setup to ALWAYS assume drive 0 and 1 are ready. Thus if a
mlnl floppy version of FLEX attempts to search a drive which does not
have a disk loaded, it will hang up until a disk is inserted and the
door closed. Alternatively, the system reset could be hit and a warm
start exe.cuted (a jump to address $CD03). The full size floppy version
CAN detect a ready condi t i on and will not check dri ves wh i ch are out of
the ready state during automatic drive searching.
Automatic drive searching causes FLEX to first check drive #0 for the
file specified. If not there (or if not ready in the full size
version), FLEX Skips to drive #1. If the file is not found on drive #1
in the mini floppy version, FLEX gives up and a file not found error
results. In the full size version FLEX continues to search on drives #2
and #3 before reporting an error.
DESCRIPTION
The general syntax for the ASN command is as follows:
ASN[,W=][,S=]
where is a single digit drive number or the letter A.
If just
ASN is typed followed by a 'RETURN', no values will be changed, but the
system will output a message which tells the current assignments of the
system and working drives, for example:
+++ASN
THE SYSTEM DRIVE IS #0
THE WORKI NG DR IVE IS #0

-A.2.1-

FLEX User's Manual
Some examples of using the ASN command are:
ASN,W=l
ASN,S=l,W=O
where the first line would set the working drive to 1 and leave the
system drive assigned to its previous value. The second example sets
the system drive to 1 and the working drive to O. Careful use of drive
assignments can allow the operator to avoid the use of drive numbers on
file specifications most of the time!
If auto drive searching is desired, then the letter A for automatic,
should be used in place of the drive number.
Example:
ASN W=A
ASN S=A, W=l
ASN S=A, W=A

-A.2.2-

BUILD
The BUILD command is provided for those desiring to create small text
files quickly (such as STARTUP files, see STARTUP) or not wishing to use
the optionally available FLEX Text Editing System. The main purpose for
BUILD is to generate short text files for use by either the EXEC command
or the STARTUP facility provided in FLEX.
DESCRIPTION
The general syntax of the BUILD command is:
BUILD,
where is the name of the file you wish to be created.
The
default extension for the spec is TXT and the drive defaults to the
working drive. If the output file al ready exists the question "MAY THE
EXISTING FILE BE DELETED?" will be displayed. A Yresponse will delete
the existing file and build a new file while a N response will terminate
the BUILD command.
After you are in the 1BUILD 1 mode, the term; nal will respond with an
equals sign (1=1) as the prompt character. This is similar to the Text
Editing System's prompt for text input. To enter your text, simply type
on the terminal the desired characters, keeping in mind that once the
'RETURN ' is typed, the line is in the file and can not be changed. Any
time before the 'RETURN ' is typed, the backspace character may be used
as well as the line delete character. If the delete character is used,
the prompt will be I???I instead of the equals sign to show that the
last line was deleted and not entered into the file. It should be noted
that only printable characters (not control characters) may be entered
into text files using the BUILD command.
To exit the BUILD mode, i t i s necessary to type a pound si gn (I #
immediately following the prompt, then type 'RETURN ' • The file will be
finished and control returned back to FLEX where the three plus signs
should again be output to the terminal. This exiting is similar to that
of the Text Editing System.
1 )

-B.1.1-

BACKUP
The BACKUP command is used to copy an entire diskette quickly.
It
copies all the information on a diskette to another diskette. The
two diskettes must be the same size and format: each sector on the
source diskette is copied to the corresponding sector on the
destination diskette.
The previous contents of the destination
disk are lost. The copying process is exact:
files that were
segmented on the source diskette will be segmented the same way on
the destination diskette.
Each sector on the destination disk is
read back for verification.
BACKUP works properly only with
diskettes formatted with the Gimix FORMAT program.
DESCRIPTION
The general syntax of the BACKUP command is:
BACKUP,,[,CPU speed]
where is the drive holding the diskette to be
backed up, is the drive holding the diskette
to be backed up to, and CPU speed is a "1" or "2" indicating the
CPU clock rate assumed when the diskettes were formatted.
(This
is necessary because the Gimix FORMAT program has different
interleave patterns for 1 Mhz and 2 Mhz CPUs. BACKUP uses the
interleave pattern to read and write physically sequential sectors
on the diskettes, so that an entire track can be read or written
in one revolution.) This parameter defaults to 2. For example,
+++BACKUP,O,l

would copy the diskette in drive
to the diskette in drive 1,
assuming a 2 Mhz type interleave.
If the diskettes have different
interleave patterns or the wrong pattern is indicated in the
command line,
BACKUP will take up to 10 times as long to run.
This may also happen if either diskette has a non-Gimix format.
NOTE:
the actual clock speed of the CPU is irrelevant; BACKUP is
only concerned with the order of the.sectors as set by FORMAT.
Before
the copying begins, BACKUP prints
destination disk in the following prompt:

the

name

the

OKAY TO SCRATCH diskname.ext?
This is the last chance to abort BACKUP. The user must respond by
typing "Y" or "N".
If "N" is typed, BACKUP is aborted and control
returns to FLEX.
If "Y" is typed, BACKUP will proceed.
When
BACKUP is done it sends three BELL characters to the console and
prints "BACKUP COMPLETE!".
BACKUP will work with 5" or 8" drives, single or double density,
and single or double sided formats.
The number of tracks is
obtained
from the System Information Record of the source
diskette; any number is permitted provided both diskettes are :~he
same.
For more information on different disk formats see the
FORMAT command.
-B.2.1-

BACKUP is much faster than COpy when a large number of files are
copied. The approximate time required for BACKUP is given in the
following table.
These times assume a 56K system.
Note that data
density does not affect the time required.

Single-sided
Double-sided

8" 77-track

5" 80-track

5" 40-track

47 sec
106 sec

82 sec
130 sec

45 sec
66 sec

BACKUP checks a number of conditions before executing, and will
abort if necessary.
When this happens "BACKUP ABORTED" is
printed, followed by one of the following error messages.
PRINT SPOOLER ACTIVE - The BACKUP command cannot be used while the
print spooler is active. The user must de-activate the spooler
with the 'QCHECK' command or wait until all printing has finisbed.
INVALID DRIVE NUMBER - The user entered an
for the source or destination drive.

illegal

drive

number

HARD DISK NOT ALLOWED - The user attempted to back up to or from a
hard disk device.
DEST DISK IS PROTECTED - The destination disk is write protected,
either by hardware or software. This message will be generated if
the destination disk is a 96-tpi drive emulating a 48-tpi drive,
since Gimix FLEX 4.0 automatically write protects such a drive.
DISKS ARE DIFFERENT SIZES- The user bas attempted to back up a 5"
diskette to an 8" diskette, or vice versa.
DISKS HAVE DIFFERENT FORMATS - The number of sectors per track or
the number of tracks is different on the source and destination
diskettes.
Usually this means one diskette is double density or
double sided and the other is not.
ILLEGAL DISK FORMAT - The number of sectors per track on either
the source or destination diskette does not match any Gimix FLEX
format. Only Gimix-formatted disks work properly with BACKUP.
ILLEGAL CLOCK RATE
The user specified
command line other than 1 or 2 (Mhz).

a clock rate in the

NOT ENOUGH MEMORY - The system does not have enough user memory to
store one full track (13K for DS/DD 8" diskettes, less for other
formats) .

-B.2.2-

CAT
The CATalog command is used to display the FLEX disk file names in the
directory on each di sk. The user may di spl ay selected fi 1es on one or
mUltiple drives if desired.
OESCR I PTI ON
The general syntax of the CAT command is:
CAT[,][,]
where can be one or more drive numbers seperated by commas,
and is a set of name and extension characters to be matched
against names in the directory. For example, if only file names which
started with the characters 'VEl were to be cataloged, then VE would be
in the match list. If only files whose extensions were 'TXT' were to be
cataloged, then .TXT should appear in the match list.
A few specific
examples will help clarify the syntax:
+++CAT
+++CAT,l,A.T,DR
+++CAT,PR
+++CAT,O,l
+++CAT,O,l,.CMD,.SYS
The first example will catalog all file names on the working drive or on
all drives if auto drive searching is selected. The second example will
catalog only those files on drive 1 whose names begin with 'A' and whose
extensions begin with 'T', and also all files on drive 1 whose names
start with 'DR'. The next example will catalog all files on the working
drive (or on all drive if auto drive searching is selected) whose names
start with 'PRJ.
The next line causes all files on both drive and
drive 1 to be cataloged. Finally, the last example will catalog the
files on drive 0 and 1 whose extensions are CMD or SYS.

During the catalog operation, before each drive's files are displayed, a
header message stating the drive number is output to the terminal. The
name of the diskette as entered during the NEWDISK operation will also
be displayed. The actual directory entries are listed in the following
form:
NAME. EXTENSION

SIZE PROTECTION CODE

where size is the number of sectors that file occupies on the disk.
If
more than one set of matching characters was specified on the command
line, each set of names will be grouped according to the characters they
match.
For example, if all .TXT and .CMD files were cataloged, the TXT
types would be listed together, followed by the CMD types.
In summary, if the CAT command is not parameterized, then all files on
the assigned working drive will be displayed. If a working drive is not
assigned (auto drive searching mode) the CAT command will display files

-C.1.1-

FLEX User's Manual
on all on line drives. If it is parameterized by only a drive number,
then all files on that drive will be displayed. If the CAT command is
parameterized by only an extension, then only files with that extension
will be displayed.
If only the name is used, then only files which
start with that name wi 11 be di spl ayed.
If the CAT command is
parameterized by only name and extension, then only files of that root
name and root extension (on the working drive) will be displayed. Learn
to use the CAT command and all of its features and your work with the
disk will become a little easier.
The current protection code options that can be displayed are as
foll ows:

o
W

(blank)

File is delete protected (delete or rename prohibited)
File is write protected (delete, rename and write prohibited)
No special protection

-C.l.2-

COpy
The COPY command is used for making copies of files on a disk.
Individual files may be copied, groups of name-similar files may be
copied, or entire disks may be copied. The copy command is a very
versatile utility. The COpy command also re-groups the sectors of a
file in case they were spread allover the old disk. This regrouping
can make file access times much faster. It should be noted that before
copyi ng fil es to a new di sk, the di sk must be formatted fi rst. Refer to
NEWDISK for instructions on this procedure.
DESCRIPTION
The general syntax of the COPY command has three forms:
a. COPY,,
b. COPY,,
c. COPV,,[,]
where is the same as that described in the CAT command and
all rules apply to matching names and extensions. When copying files,
if the destination disk already contains a file with the same name as
the one being copied, the file name and the message, "FILE EXISTS DELETE
ORIGINAL?" will be output to the terminal. Typing Y will cause the file
on the destination disk to be deleted and the file from the source disk
will be copied to the destination disk. Typing N will direct FLEX not
to copy the file in question.
The first type of COPY allows copying a single file into another.
The
output file may be on a different drive but if on the same drive the
file names must be different. It is always necessary to specify the
extension of the input file but the output file's extension will default
to that of the input's if none is specified. An example of this form of
COPY is:
+++COPY,O.TEST.TXT,I.TEST25
This command line would cause the file TEST.TXT on drive 0 to be copied
into a file called TEST25.TXT on drive 1. Note how the second file's
extension defaulted to TXT, the extension of the input file.
The second type of COpy allows copying a file from one drive to another
drive with the file keeping its original name. An example of this is:
+++COPY,O.LIST.CMD,1
Here the file named
is again necessary
specification. This
previous form if the
copying process.

LIST.CMD on drive 0 would be copied to drive 1. It
to specify the file's extension in the file
form of the command is more convenient than the
file is to retain its original name after the

-C.2.1-

FLEX Userls Manual
The fi nal fonn of COpy is the most versatil e and the most powerful.
It
is possible to copy all files from one drive to another, or to copy only
those files which match the match list characters given. Some examples
will clarify its use:
+++COPY,O,l
+++COPY,l,O,.CMD,.SYS
+++COPY,O,l,A,B,CA.T

The first example will copy all files from drive to drive 1 keeping
the same names in the process. The second example will copy only those
files on drive 1 whose extensions are CMD and SYS to drive 0. No other
files will be copied. The last example will copy the files from drive a
whose names start with IAI or 18 1 regardless of extension, and those
files whose names start with the letters ICAI and whose extensions start
with ITI.,to the output drive which is drive 1. The last fonn of copy
is the most versatile because it will allow putting just the command
(CMD) files on a new disk, or just the SYS files, etc., with a single
command entry. During the COpy process, the name of the file which is
currently being copied will be output to the terminal, as well as the
drive to which it is being copied.

-C.2.2-

COpy (-TSC,-GMX)t
The COpy command is used for making copies of files on a disk.
Individual files may be copied, groups of name-similar files may
be copied, or entire disks may be copied. The COPY command is a
very versatile utility.
When files are copied onto a newly
formatted disk,
they are stored as contiguous groups of sectors,
resulting in minimum access times.
This can be a substantial
improvement over an old disk on which the files are highly
fragmented due to frequent rewriting.
DESCRIPTION
The general syntax of the COpy command has three forms:
a. COPY,
c. COPY,,[,]
where ,
This will cause the two files to be read as FLEX binary files and
compared. The default extension is BIN. The files are read as
binary records, in the format described on page 45 of the FLEX
Advanced Programmer's Guide. A binary record consists of a load
address, a byte count, and bytes of data to be stored in memory.
The data bytes from the first file are compared to the data bytes
from the second file. The current load address for each file is
also compared.
If either.is different, the address and data byte
from each file is printed. Example:
+++CMPBIN,A.BIN,AOLD.BIN
FILE A
FILE B
ADDRESS BYTE
BYTE ADDRESS
0209
A5
A7
0209
020A
56
29
020A
03E4
C6
4D
03E4
CMPBIN is a very simple-minded program, and works best only when
the two files load starting at the same address.
If the files
differ by one file having code inserted or removed,
then
mismatches will be found from the point where bytes were added or
removed to the end of the file.
If one file is longer than the
other, the extra bytes will all be mismatches, with the shorter
file's contents listed as "0106
00". If the data bytes are the
same, but the files were assembled to load at different addresses,
then every byte will be a mismatch, but only on the addresses,
which is easily seen.

-C.5.1-

DATE
The DATE command is used to display or change an internal FLEX date
register. This date register may be used by future programs and FLEX
util ities.
OEseR I PTI ON

The general syntax of the DATE command is:
DATE[,]
where Imonth l is the numerical month, Idayl is
Iyearl is the last two digits of the year.

the

numerical

day

and

+++DATE 5,2,79 Sets the date register to May 2, 1979
Typing
date.

DATE

Example:

followed by a carriage return will return the last entered

+++DATE
May 2, 1979

-0.1.1-

DELETE
The DELETE command is used to delete a file from the disk. Its name
will be removed from the directory and its sector space will be returned
to the free space on the disk.
DESCRIPTION
The general syntax of the DELETE command is:
DELETE,[,]
where can be an optional list of file specifications. It is
necessary to include the extension on each file specified.
As the
DELETE command is executing it will prompt you with:
DELETE "FILE NAME"?
The entire file specification will be displayed, including the drive
number. If you decide the file should be deleted, type IVI; otherwise,
any other response will cause that file to remain on the disk. If a IV I
was typed, the message IARE YOU SURE?I will be displayed on the
terminal. If you are absolutely sure you want the file deleted from the
disk, type another IV I and it will be gone. Any other character will
leave the file intact. ONCE A FILE HAS BEEN DELETED, THERE IS NO WAY TO
GET IT BACK!
Be absolutely sure you have the right file before
answering the prompt questions with ViS. Once the file is deleted, the
space it had occupied on the disk is returned back to the list of free
space for future use by other files. Few examples follow:
+++DELETE,MATHPACK.BIN
+++DELETE,l.TEST.TXT,O.AUGUST.TXT
The first example will DELETE the file named MATHPACK.BIN from the
working drive.
If auto drive searching is selected, the file will be
deleted from the first drive it is found on.
The second line will
DELETE the file TEST. TXT from drive 1, and AUGUST. TXT from drive 0.
There are several restrictions on the DELETE command.
First, a file
that is delete or write protected may not be deleted without first
removing the protection. Also a file which is currently in the print
queue (see the PRINT command) can not be deleted using the DELETE
command.

-0.2.1-

DCOPY
The DCOPY command is used to copy from one disk to another all
files which were created on or after a given date.
This permits
convenient backup of only those files which are new.
DESCRIPTION
The general syntax of the DCOPY command is:
DCOPY,,,[],[l,[][,R]
where the first drive number is the drive to be copied from,
the
second drive number is the drive to be copied to. R is an option
to replace existing files on the destination disk with the files
being copied.
,
, and indicate a date; only
files created on or after this date will be copied.
If any part
of the the date is left out, DCOPY defaults to the value in the
corresponding. FLEX date register. For example
DCOPY,2,1,6,1,R
would copy from drive 2 to drive 1 all files created after June 1
of the current year, replacing exist~ng copies on drive 1.
DCOPY,O,3",81

would copy from drive
to drive 3 all files created after todayfs
date in 1981 which were not already on the disk in drive 3.
DCOPY,1,O,R

would copy from drive 1 to drive
all files which were created
today, replacing existing copies of these files on drive 0.
DCOPY logs each file copied on the console with the message
n.filnam.ext TO DRIVE #n
These messages may be redirected to the printer or to a file
the P and 0 commands to provide a record of operations.

with

If the R option is selected, files on the destinat.3:on disk with
the same names as files to be copied will be deleted, and replaced
by the copied files, unless the date of the destination disk file
is more recent than that of the source disk file.
In that case,
DCOPY will print
DEST FILE IS NEWER - NOT COPIED
and go on to the next file. This prevents the user from "backing
up" an out-of-date file onto the current file.
NOTE: the date of a random-access file is the day it was created.
FLEX does not change this date when the file is accessed.
The
GIMIX-supplied UPDATE utility command can be used to update the
date of a random-access file.
-D.3.1-

EXEC
The EXECute command is used to process a text file as a list of
commands, just as if they had been typed from the keyboard. This is a
very powerful feature of FLEX for it allows very complex procedures to
be built up as a command file.
When it is desirable to run this
procedure, it is only necessary to type EXEC followed by the name of the
command file. Essentially all EXEC does is to replace the FLEX keyboard
entry routine with a routine which reads a line from the command file
each time the keyboard routine would have been called. The FLEX
utilities have no idea that the line of input is coming from a file
instead of the terminal.
DESCRIPTION
The general syntax of the EX command is:
EXEC,
where is the name of the command file. The default
extension is TXT. An example will give some ideas on how EXEC can be
used. One set of commands which might be performed quite often is the
set to make a new system diskette on drive 1 (see NEWDISK). Normally it
is necessary to use NEWDISK and then copy all .CMD and all .SYS files to
the new disk. Finally the LINK must be performed. Rather than having
to type this set of commands each time it was desired to produce a new
system diskette, we could create a command file called MAKEDISK.TXT
which contained the necessary commands. The BUILD utility should be
used to create this file.
The creation of this file might go as
foll ows:
+++BUILD,MAKEDISK
=NEWDISK,1
=COPY,O,I,.CMD,.OV,.LOW,.SYS
=LINK,1. FLEX
=#

+++

The first line of the example tells FLEX we wish to BUILD a file called
MAKEDISK (with the default extension of .TXT).
Next, the three
necessary command lines are typed in just as they would be typed into
FLEX. The COpy command will copy all files with CMD, OV, LOW, and SYS
extensions from drive 0 to drive 1. Finally the LINK will be performed.
Now when we want to create a system disk we only need to type the
fo 11 owi ng:
+++EXEC,MAKEDISK
We are assuming here that MAKEDISK resides on the same disk which
contains the system commands.
EXEC can also be used to execute the
STARTUP file (see STARTUP).

-E.1.1-

FLEX User's Manual
There are many applications for the EXEC command. The one shown is
certainly useful but experience and imagination will lead you to other
useful applications.
IMPORTANT NOTE: The EXEC ut i 1i ty is loaded into the very upper end of
user memory. This is done by first loading EXEC into the utility file
space, then calculating the proper starting address so that it will
reside right up against the end of the user memory space. Next EXEC is
moved to that location and a new end of memory is set to just below
EXEC. When the EXEC file is finished, if the user has not further
changed the memory end location, EXEC will reset it to the original
value.

-LI.2-

EXTEND

EXTEND enables the user to increase the amount of space allocated
to the directory on a newly formatted disk.
This prevents the
directory from becoming fragmented when the number of directory
entries exceeds the space allocated by the disk format program.
Fragmenting the directory increases the amount of time require to
access files on the disk.

DESCRIPTION
The general synatax of the EXTEND command is:
EXTEND[,dn,sn]
Where 'dn' is an optional drive number and 'sn' is the number of
additional sectors to be allocated to the directory.
If no drive
number is specified, EXTEND defaults to the work drive and adds 10
sectors.
If the work drive is set to 'ALL', EXTEND prints an
error message and reurns to FLEX.
The maximum number
of
additional sectors that can be allocated to the directory is 10.
Each sector adds space for 10 entries to the directory allocation.
Some examples follow:
+++EXTEND
+++EXTEND,2,5
The first example will EXTEND the directory of the disk in the
work drive by 10 sectors (100 entries).
The second example will
EXTEND the directory of the disk in drive #2 by 5 sectors (50
entries) .
The following table lists the number of sectors/directory
normally allocated by FORMAT:
8"

SECTORS
SINGLE SIDED
DOUBLE SIDED

NOTE:

6
16

entries

ENTRIES

SECTORS

60
160

11
26

ENTRIES
110
260

EXTEND can only be used on a freshly formatted disk.

EXTEND can generate the fbllowing error message:
DISK CANNOT BE EXTENDED
Either there are already files on the disk or the first sector on
track one was found bad when the disk was formatted.

-E.2.1-

FORMAT
FORMAT is used to format a new diskette.
Diskettes as purchased
will not work with FLEX until certain formatting information has
been put on them. The FORMAT utility writes this information on
the blank diskette and then verifys that the information can be
read back.
If FORMAT finds sectors that it cannot read it removes
them from the chain of free sectors and prints their location.
DESCRIPTION
The general

s~ntax

of the FORMAT command is:

FORMAT[,]
Where is the number of the drive in which the disk to be
formatted has been placed. If no drive number is specified the
'ALL' then
'WORK' drive is used.
If the 'WORK' drive is set to
the user is prompted for the drive number.
After FORMAT has determined the drive number it will ask:
SCRATCH DISK IN DRIVE #X ('Y' OR 'N')?
Where X is the drive number specified by the user or the 'WORK'
drive. If the user types an 'N' the program will abort and return
to FLEX. If a 'Y' is typed FORMAT continues with the following
prompt:
DISK SIZE ('5' OR '8')?
The user then types in the size
thiS FORMAT prompts:

tbedisk to be formatted.

After

FORMAT SINGLE OR DOUBLE SIDED ('S' OR 'D')?
If the drive being used to format is a double sided drive and the
user wants to format both sides of the disk type '0', otherwise
type'S'. The next prompt is:
SINGLE OR DOUBLE DENSITY ('S' OR 'D')?
The user then types in whether he wants the disk to be formatted
single or double density. Formatting a single density disk for
double density use is not recommended. FORMAT then prompts:
NUMBER OF TRACKS TO FORMAT?
FORMAT is asking literally how many tracks does the user wishes to
format.
Standard sizes for 5.25" disks are: 35, 40, 70, 77, 80.
Please consult the disk drive manufacturers data sheet for the
particular drive being used to find the maximum number of tracks
that the drive is capable of accessing.
Even though it is
possible to attempt to format a disk for more tracks then it is
capable of, it is not recommended as it might cause damage to the
disk drive. The next prompt is:
FORMAT SINGLE OR DOUBLE STEPPING ('S' OR 'DI)?
-F.1.1-

Some disk drives bave double tbe normal number of tracks for tbat
size drive.
Tbis is called a 'Double Tracking' disk drive. The
Double Tracking drives bave twice as many tracks per incb as
regular disk drives.
This makes them incompatible witb regular
drives. This option enables tbe user to create a disk that will
be usable on a regular disk drive, but was formatted on a Double
Tracking disk drive. Tbis can be useful for program exchange,
etc. Wben formatting a disk double stepped it is recommended tbat
only fresb, i.e. disks never used, are used. This will alleviate
possible intercbange problems resulting from tbe differences
between single and double tracking drives. The next prompt is:
1MHz OR 2 MHz CPU SPEED ('1' OR '2')?
Tbis information is used by FORMAT to determine whicb sector
interleave pattern to use when writing the disk. Tbe sector
interleave is optimized for fastest access time at eacb CPU speed.
If the system is running at 1.5MHz , enter 2MHz when formatting 5"
disks and 1MHz when formatting 8". Tbe next prompt is:
DISK NAME?
The user enters the name of the disk that is to appear in catalog
listings.
If the user just enters a carriage return a disk name
of 'GIMIX .CHI' is put on the disk. ~he next prompt is:
VOLUME NUMBER?
The user enters the volume number that is to appear in catalog
listings.
If carriage return is entered then the disk number will
be zero (0).
If the user entered a carriage return for the name
prompt, this prompt will be skipped and a volume number of '60609'
will be put on the disk.
After entering the volume number FORMAT then prints all the data
just entered and prompts:
IS THE ABOVE CORRECT ('Y' OR 'N')?
If tbe data typed in is correct then type 'Y' and FORMAT will go
on.
If an
'N' is typed then the prompts start over aga~n. The
final prompt is:
ABORT FORMAT ('Y' OR 'N')?
Tbis is the users LAST chance to stop the formatt~ng~and-save the
disk in the specified drive. Typing an 'N' will start the format
WITHOUT any further user interaction. Typing a 'Y' will abort th~
format and return to FLEX. FORMAT will now print:
FORMATTING TRACK:

Where XX is the track currently being formatted.
The track number
will be updated as ~achtrack is formatted. After ~ll tracks have
been forma tt.ed FORMAT will print:

-F.1. 2-

VERIFYING TRACK:

Where XX is the track currently being verified.
FORMAT reads
every sector on the disk after formatting.
If it finds a sector
that is can not read it removes the bad sector from the cahin of
available sectors.
Once a FORMAT has removed a sector it is
unavailable to FLEX unless the disk is reformatted and does not
error again.
If a disk continually gives alof of errors or gives
errors in different areas each time it is formatted the disk might
be defective.
Upon successful completion FORMAT will print the
following
message, ring the terminal bell and then return to FLEX:
FORMATTING COMPLETED
TOTAL SECTORS: XXXX
Where XXXX is the
number will vary
size of the disk,
sided and whether

number of sectors available to the user.
This
depending on the number of tracks formatted, the
whether the disk was formatted single or double
the disk was formatted single or double stepped.

The following is an explination of the possible
that can be generated by the FORMAT command:

error

messages

NOT EOUGH MEMORY INSTALLED IN SYSTEM
This means that according to the FLEX 'MEMEND' pointer there is
not enough memory installed in the system to format a disk.
The
user must have at least sixteen (16) 'k' of memory starting at
$0000 in addition to the RAM occupied by FLEX.
FORMATTING ABORTED
This error message is printed to inform the user that FORMAT
returned to FLEX prematurely and that formatting was unsuccessful.
TOO MANY TRACKS FOR DOUBLE STEPPING
This error message means that the user tried to format more tracks
than any drive is capable of handling when double stepped.
When
formatting double stepped the number of tracks on the drive is
HALVED. The user is then prompted for the number of tracks to
format, again.
ERROR WRITING BOOT SECTOR
This is a fatal error which causes the formatting to be aborted.
This means that FORMAT could not put the necessary loading
information on track 0, sector 1.

-F.l.3-

SECTOR WAS NOT WRITTEN TO ZEROS
This is a secondary error and is only printed after a bad sector
message has been printed.
It tells the user that the sector did
not clear when initially written to disk.
ERROR IN SECTOR LINKAGES
This is a secondary error and is only printed after a bad sector
message has been printed.
It tells the user that the pointers to
the next sector were not written correctly.
ERROR VERIFYING SECTOR
This is a secondary error and is only printed after a bad sector
message has been printed.
It tells the user that the specified
sector has a surface flaw and cannot be read.
FATAL ERROR
This tells the user that FORMAT found an error in a vital area
the disk and that the disk is unusable.

BAD SECTOR AT: TT-SS
This is the header message for the three secondary error messages.
TT is the track number of the error and SS is the sector number of
the error.
FORMAT then removes the bad sector from the disk. A
disk with a few bad sectors can still be used. Once a FORMAT has
removed a sector it is unavailable to FLEX unless the disk is
reformatted and does not error again. If a .disk continually gives
alot of errors or gives errors in different areas each time it is
formatted the disk might be defective.
NO GOOD SECTORS ON DISK
This is a fatal error and tells the user that FORMAT could not
find a single usable sector on the disk. This usually means that
the disk is defective.
Try formatting the disk again before
rejecting it.
DRIVE NOT READY
This tells the user that the drive to be formatted in either does
not have a disk in it or that the drive door is open.
DISK IS WRITE PROTECTED
This is a fatal error that tells tha user that the disk in the
specified drive. is write protected and cannot be formatted until
it is un-write protected. FORMAT Will, however~
format a disk
that has been write protected using the SETUP command (see the
'SETUP' command decsription for more information on this option).
The drive will be restored to whatever state is was in prior to
formatting, when FORMAT has finished.

-F.l.4-

WRITE FAULT IN WRITING TRACK
This indicates a hardware failure in the disk drive itself.
If
this message is gotten re-try tbe FORMAT and if it appears again
the cbances are tbat tbe disk drive is not functioning properly.
LOST DATA IN WRITING TRACK
Tbis error sbould not normally occur. Since FORMAT inbibitstbe
'IRQ' and 'FIRQ' interrupts tbe only way to get tbis error message
is if the system is getting
'NMI' interrupts. Eliminate tbe
source of tbe interrupts and try again.
If this error persists or
tbere are definately no interrupts being generated in your system
tben there migbt be a bardware failure.
If using tbe GIMIX 6809
PLUS CPU BOARD with tbe 58167 Time-of-Day clock option installed,
make sure tbat it is not enabled for 'NMI'
interrupts.
See tbe
Hardware Manual for information on bow to do tbis.
ERROR IN ACCESSING SYSTEM INFORMATION RECORD
This means that tbe format and verify went properly but after
verifying tbe disk wben FORMAT went to write tbe disk information
on track 0,
sector 3 it encountered an error. Tbis is a fatal
error.

-F.1.5-

CREATING SYSTEM DISKETTES
A system disk is the one from which the operating system can be
loaded. Normally the system disk will also contain the Utility
Command Set (UCS).
The following procedure should be used when
preparing system disks.
1.

Initialize the diskette using FORMAT as described
on the preceding pages.
NOTE: GIMIX/FLEX is distributed on single-sided,
single-density disks. When formatting a disk to
be used as a working system disk, it may be
desirable to format the disk for greater capacity
(double-density and/or double-sided). The BACKUP
command can then be use to generate additional copies
with the increased capacity.

Use the SYSGEN command to create a version of FLEX,
with any required modifications, on the new disk.

Copy all .CMD files desired to the new disk.

Copy all .SYS files to the new disk.
It should be
noted that steps 3 and 4 can be done with one command,
'COPY,O,l,.CMD,.LOW,.SYS', assuming you are copying
from drive
to drive 1. (the .LOW copies the SAVE. LOW
command)

Last it is necessary to LINK the file FLEX4G.SYS to
the system using the LINK commmand.

It is not necessary to make every disk a system diskette.
It is
also possible to create 'working' diskettes, disks which do not
have the operating system on them, for use with text files or
BASIC files.
Remember that a diskette can not be used for booting
the system unless the operating system in contained on it and it
has been linked. To create a working disk, simply run FORMAT on a
diskette.
It will now have all of the required information to
enable FLEX to make use of it. This disk, however, does not
contain the disk operating system and is not capable of booting
the system.

-F.1.6-

FIXDAY
The FIXDAY command is used to update the FLEX system date to the
current date in the hardware clock on the GIMIX CPU Board without
rebooting the system.
DESCRIPTION
The general syntax of the FIXDAY command is:
FIXDAY
This causes the day, month, and year in the hardware clock on the
GIMIX CPU Board to be copied to the FLEX date registers.
No
output is generated.
The date is normally set when FLEX is
booted. But in some applications the user may want to leave FLEX
running continuously several days at a time, or even permanently.
This utility allows the FLEX date to be brought up to date without
restarting the system.

-F.2.1-

FREEMAP
Tbe FREEMAP command is used to cbeck tbe list of available sectors
(free cbain) on a FLEX formatted disk (floppy or hard) to
determine the amount of fragmentation tbat exists.
DESCRIPTION
Tbe general syntax of tbe FREEMAP command is:
FREEMAP,
FREEMAP tben scans all tbe sectors in tbe free cbain of the disk
in tbe designated drive, and lists on tbe console all tbe groups
of continuous sectors found.
Tbe total number of such groups
(called segments) is displayed at tbe end.
By exam1n1ng this
list, tbe user can determine the degree of fragmentation of the
disk, and decide whether to run UNSNARL on it, or copy the files
on it to a new disk. Example:
FREEMAP,l
READING FREE CHAIN
0908-1012
0706-0708
1120-1306
2208-2209
220C-220C
SEGMENTS MAPPED:

Tbe segment count is printed in decimal. The output from this
program can be routed to tbe printer or to a file witb tbe P or 0
commands.
See the UNSNARL command for more information.

-F.3.1-

HARD(I,2,3,23)
The HARD commands are used to attach a hard disk subsystem to
Gimix FLEX 4.0 at any time.
(SYSGEN is used to make the FLEX boot
up with hard disk.)
DESCRIPTION
The general syntax of the HARD commands is:
HARD(drive #>
where (drive #> is the last character of the command name. The
Gimix hard disk subsystem will be initialized and linked to FLEX.
The hard disk subsystem can have one or two drives.
HARDI assigns
hard disk 0 as FLEX drive 1, HARD2 as drive 2, and HARD3 as drive
3.
HARD23 assumes two drives, and assigns hard disk 0 as drive 2
and bard disk 1 as drive 3.
HARDn requires 380 bytes of memory at $E500.
If tbe system does
not have a Gimix CPU board, tben the user must provide this memory
some other way.
HARDn runs two diagnostics on the controller when
If the controller fails, HARDn will print

loaded.

FAULT IN CONTROLLER BUFFER
or
FAULT IN CONTROLLER INTERNALS
If this happens,
please check all connections in the system and
try again.
If the problem persists, contact Gimix immediately.
If an error occurs during normal disk operations, HARDn prints
CONTROLLER ERROR - STATUS BYTES:

nn nn nn nn

where nn nn nn nn are the four "SENSE STATUS" bytes described in
the controller hardware manual.
If the error persists,
note the
value of these four bytes and contact Gimix.

-H.l.l-

HARDFORM
HARDFORM is used to format a Gimix hard disk drive for use with
Gimix FLEX 4.0.
It establishes the interleave,
free chain,
catalog, and System Information Record (SIR).
DESCRIPTION
The general syntax of the HARDFORM command is:
HARDFORM
HARDFORM responds with the prompt
WHICH DRIVE (LUN) TO FORMAT (O/l)?
The Gimix hard disk subsystem can support one or two hard disk
drives, which are referred as LUNO and LUNl.
If only one hard
disk drive is attached, it defaults to LUNO.
The
Once the drive is selected, HARDFORM begins to operate.
formatting process consists of several steps.
In the first step,
HARDFORM initializes the controller an~ drive, and performs two
diagnostic tests on the controller.
If either of these tests
fails, HARD FORM aborts with the message
ERROR IN INITIALIZING CONTROLLER
If this message comes up, check all connections in your system and
try again.
If it comes up again, contact Gimix immediately!
Next, HARDFORM has the controller generate the drivets internal
format.
This consists of the address, gap, data, and checksum
fields. HARDFORM prints
GENERATING INTERNAL FORMAT
at this time. Once this internal format bas been written to the
disk,
HARDFORM
checks this format by reading each track.
Defective tracks are flagged for exclusion from the free chain.
At the start of this step HARD FORM prints
CHECKING INTERNAL FORMAT
NOW CHECKING AT nnnn
where nnnn is the disk address of the last track checked.
NOTE:
HARDFORM reprints this message on the same line after every track
and may cause problems on a hard copy console.
When HARDFORM finds a defective track, it prints
ERROR IN INTERNAL FORMAT AT nnnn
where

nnnn is the address of the defective track.

-H.2.l-

HARDFORM keeps

count of the defective tracks.
If the number of defective
exceeds 100, HARDFORM will abort with the message

tracks

100 BAD TRACKS!! - FORMATTING ABORTED
If this happens, contact Gimix immediately.
through checking the internal format, it prints

When HARDFORM is

INTERNAL FORMAT COMPLETE
ESTABLISHING FLEX FORMAT
and begins writing out FLEX pointer data to all the sectors in the
free chain. While HARDFORM does this, it prints
NOW FORMATTING AT nnnn
once every 256 sectors, where nnnn is the last sector written.
This message is reprinted on the same line each time, and may
cause problems on a hard copy console. After all the free chain
pointers are done, HARDFORM sets up the catalog.
187 sectors are
reserved for the catalog; if you need more, use the EXTEND command
before putting any files on the disk.
HARDFORM will abort with the message
FATAL ERROR - FORMATTING ABORTED
for a number of reasons, some of which have already
mentioned. HARDFORM will also abort with these messages.

been

ERROR ON TRACK 00
There was a formatting or write error in the catalog or SIR areas
of the disk.
ERROR IN WRITING FREE LIST
There was a write error in a sector of the free chain.

-H.2.2-

The I command allows a utility to obtain input characters from a disk
file rather than the terminal.
DESCRIPTION
The general syntax of the I command is:
I,,
where is the name of the file containing the characters to
be used as input and is the FLEX utility command that will be
executed and that will receive that input from . The default
extension on is .TXT.
For example, say that on a startup you always wanted the file DATA.DAT
deleted from the disk without having to answer the "ARE YOU SURE?"
questions. This could be done in the following manner:
+++BUILD, YES
=YY
=#

The first Y will answer the "DELETE O~DATA.DAT?" question while the
second Y will answer the "ARE YOU SURE?" question.
+++BUILD,STARTUP
=I,YES,DELETE,DATA.DAT
=#

Upon boot i ng the di sk, FLEX wi 11 execute the STARTUP fi 1e and perform
the following operation: delete the file DATA.DAT receiving all answers
to any questions from the input file YES. TXT rather than from the
terminal.
See the description of the STARTUP command for more information on
STARTUP.

-1.1.1-

JUMP
The JUMP command is provided for convenience.
It is used to
execution of a program already stored in computer RAM memory.

start

DESCRIPTION
The general syntax of the JUMP command is:
JUMP,
where is a 1 to 4 digit hex number representing the
address where program execution should begin. The primary reason for
using JUMP is if there is a long program in memory already and you do
not wish to load it off of the disk again. Some time can be saved but
you must be sure the program really exists before JUMPing to it!
As an example, suppose we had a BASIC interpreter in memory and it had a
'warm start' address of 103 hex. To start its execution from FLEX we
type the following:
+++JUMP,103
The BASIC interpreter would then be executed. Again, remember that you
must be absolutely sure the program you are JUMPing to is actually
present in memory.

-J.1.1-

LINK
The LINK command is used to tell the bootstrap loader where the FLEX
operating system file resides on the disk. This is necessary each time
a system disk is created using NEWDISK. The NEWDISK utility should be
consulted for complete details on the use of LINK.
DESCRIPTION
The general syntax of the LINK command is:
LINK,
where is usually FLEX.
examples of the use of LINK follow:

The default extension ;s SYS.

Some

+++LINK,FLEX
+++LINK,l.FLEX
The first line will LINK FLEX.SYS on the working drive, while the second
example w;ll LINK FLEX.SYS on drive 1. For more advanced details of the
LINK util ity, consult the "Advanced Programmers Guide".

-L.1.1-

LIST
The LIST command is used to LIST the contents of text or BASIC fil es on
the terminal. It is often desirable to examine a files without having
to use an editor or other such program. The LIST ut il ity allows
examining entire files, or selected lines of the file. Line numbers may
also be optionally printed with each line.
DESCRIPTION
The general syntax of the LIST command is:
LIST,[,][,+(options)]
where the designates the file to be LISTed (with a default
extension of TXT),and is the first and last line number of
the file which you wish to be displayed. All lines are output if no
range specification is given. The LIST command supports two additional
options.
If a +N option is given, line numbers will be displayed with
the listed file. If a +P option is given, the output will be formatted
in pages and LIST will prompt for "TITLE" at which time a title for the
out put may be entered. The TITLE may be up to 40 characters long. Thi s
feature is useful for obtaining output on a printer for documentation
purposes (see P command). Each page will consist of the title, date,
page number, 54 lines of output and a hex OC formfeed character.
Entering a +NP will select both options. A few examples will clarify
the syntax used:
+++LIST,RECEIPTS
+++LIST,CHAPTERl,30-200,+NP
+++LIST,LETTER,lOO
The first example will list the file named 'RECEIPTS.TXT ' without line
numbers. All lines will be output unless the lescape character I is used
as described in the Utility Command Set introduction. The seco~d
example will LIST the 30th line through the 200th line of the file named
'CHAPTERl.TXT ' on the terminal.
The hyphen (I_I) is required as the
range number separator. Line numbering and page formatting. will be
output because of the '+NP' option. The last example shows a special
feature of the range specification. If only one number is stated, it
will be interpretted as the first line to be displayed. All lines
following that line will also be LISTed. The last example will LIST the
1 i nes from 1i ne 100 to the end of the fi 1e. No 1i ne numbers wi 11 be
output since the 'N ' was omitted.

-L. 2.1-

NAME

The NAME utility enables the user to change the name, extension,
volume number and date in the system information sector of a disk.

DESCRIPTION
The general synatax of the NAME command is:
NAME[,dn]
Where 'dn' is an optional drive number.
If no drive is specified
NAME will use the work drive.
If the work drive is set to 'ALL'
an error message is printed. Some examples follow:
+++NAME
+++NAME,2
The first example will change the information on the disk in the
work drive, assuming that the work drive is not set to all.
The
second example will change the information on the disk in drive
#2.
NAME prints the current disk name, extension, volume number and
date and then prompts for the new name.
The new name and
extension should be entered,
followed by a carriage return.
Entering only a carriage return will retain the old name.
NAME
then prompts for the new volume number. The new volume number
should be entered , followed by a carriage return.
Entering only
a carriage return will retain the original volume number. After
the new name and volume number have been entered, NAME prompts:
CHANGE DATE ('Y' OR 'N')?
Entering 'Y' changes the date on the disk to the
Entering 'N' retains the old date.

"current

date",

NAME can generate the following error message:
ILLEGAL DRIVE NUMBER
Legal drive numbers are 0, 1, 2, and 3. A drive
if the work drive is set to 'ALL'.

number

must

NOTE: If NAME is used in a command line with multipe commands,
must be the last command on the line.

specifi~d

-N .1.1-

TheN utility enables the user to automatically answer "N" (no) to
"Y or N" prompts from other utilities.
The N utility is
especially useful when writing EXEC files.
DESCRIPTION
The general synatax of the N command is:
N,
If
Where is a valid command line to be executed.
N is used in a line with multiple commands, using the end of line
character,
it only affects the command immediately following it.
For example:
+++N,COPY,0,1
Will copy, from drive #0 to drive #1, only those files that do not
already .exist on drive #1, automatically answering "N" (no) to any
"DELETE ORIGINAL?" and "ARE YOU SURE?" prompts that occur because
of duplicate files on the two disks.

-N.2.1-

(

a
The a (not zero) command can be used to route all displayed output from
a utility to an output file instead of the terminal. The function of a
is similar to P (the printer command) except that output is stored in a
file rather than being printed on the terminal or printer. Other TSC
software may support this utility.
Check the supplied software
instructions for more details.
DESCRIPTION
The general syntax of the

a command

is:

O,,
where can be any standard utility command line and
is the name of the desired output file. The default extension on is .OUT. If a is used with multiple commands per line (using the
'end of line' character ': ') it will only have affect on the command it
immed i ately precedes. Some exampl es wi 11 cl arify its use.
+++O,CAT,CAT

writes a listing of the current disk directory into
a file called CAT.OUT

+++O,BAS,ASMB,BASIC.TXT
writes the assembled source listing of the text
source file 'BASIC.TXT' into a file called 'BAS.OUT'
when using the assembler

-0.1.1-

The P command is very special and unlike any others currently in the
UCS. P is the system print routine and will allow the output of any
command to be routed to the printer. This is very useful for getting
printed copies of the CATalog or used with the LIST command will allow
the printing of FLEX text files.
DESCRIPTION
The general syntax of the P command is:
P,
where can be any standard utility command line. If P is used
with multiple commands per line (using the 'end of line' character), it
will only have affect on the command it immediately preceeds.
Some
examples will clarify its use:
+++P,CAT
+++P,LIST,MONDAY:CAT,l
The first example would print a CATalog of the directory of the working
drive on the printer. The second example will print a LISTing of the
text file MONDAY.TXT and then display on the terminal a CATalog of drive
1 (this assumes the 'end of line' character is a ': I). Note how the P
did not cause the 'CAT,l' to go to the printer. Cons~lt the 'Advanced
Programmer's Guide' for details concerning adaption of the P command to
various printers.
The P command tries to load a file named PRINT.SYS from the same disk
which P itself was retrieved. The PRINT.SYS file which is supplied with
the system diskette contains the necessary routines to operate a SWTPC
PR 40 printer connected through a parallel interface on PORT 7 of the
computer. If you wish to use a different printer configuration, consult
the 'Advanced Programmer's Guide' for details on writing your own
printer driver routines to· replace the PRINT.SYS file. The PR 40
drivers, however, are compatible with many other parallel interfaced
printers presently on the market.

-P.l.l-

PRINT
FLEX has the ability to output file stored data to a printer at the same
time that it is performing other tasks.
This feature is especially
useful when it is necessary to print a long listing without tying up the
computer. This method of printing is called PRINTER SPOOLING. In order
for the printer spooling function to work, a SWTPC MP-T interrupt timer
board must be installed in I/O position #4 on the computer's mother
board.
DESCRIPTION
The general syntax of the PRINT command is as follows:
PRINT,[,+]
where is the name of the file to be printed. The default
is the number of
extension on is .OUT.
additional copies of the file you wish to be printed.
For example, say that your disk had a very large number of files on it
and a printer catalog listing was desired. A file containing the output
information should first be created by using the 0 command such as:
+++O,CAT.OUT,CAT.CMD
or
+++O,CAT,CAT
(see the description of the 0 command)
when printer output is desired the command
+++PRINT,CAT.OUT

+++PRINT,CAT

should be entered.
At this time the file CAT.OUT is stored in a buffer called a print queue
(waiting list). If another PRINT command is issued before the first is
finished, the second file will be in the next available location in the
print queue.
After the file name to be printed has been stored in the print queue,
control will return to the FLEX operating system. At this time you may
perform any disk operation you want, such as deleting files, copying
disks, etc. While you are using FLEX, PRINT will be outputting the
desired file to the printer. PRINT will automatically wait for the
printer to become ready (power up) even after the file has been entered
into the print queue.
After printing the first file, the second file in the queue will be
printed (if there is one), etc. The print queue may be examined or
modified at any time by using the QCHECK utilty.

-P.2.1-

FLEX User's Manual
NOTE: There are several things that the user should be aware of when
using the printer spooling:
1) Any file that is in the print queue may not be deleted,
renamed, or changed in any way until it has been printed
or removed by the QCHECK pri nt queue manager ut i 1i ty •.
2)

Disks which contain the files in the print queue should
not be removed while the files are still in the queue.

3) The P command should not be used while files are waiting
in the print queue.
4) Any paper or cassette tape load or any other operation
which requires that the computer accept data at precise
time intervals should not be executed during a printer
spooling operation.

-P.2.2-

PROT
The PROT command is used
each file. When a file
wi th it thereby all owi ng
file. Delete or write
PROT command.

to change a protection code associated with
is first saved, it has no protection associated
the user to write to, rename, or delete the
protection can be added to a file by using the

DESCRIPTION
The general syntax of the PROT command is:
PROT,[,(option list)]
where the designates the file to be protected and
list) is any combination of the following options.
D

(option

A IDI will delete protect a file. A delete protected file cannot be
affected by using the DELETE or RENAME Commands, ·or by the delete
functions of SAVE, APPEND, etc.

W A IW I will write protect a file. A write protected file cannot be
deleted, renamed or have any additional information written to it.
Therefore a write protected file is automatically delete protected
as well.
C

A ICI will Catalog protect a file. Any files with a C protection
code will function as before but will not be displayed when a
CAT command is issued.
.

An IX I will remove all protection options on a specific file.

Examples:
+++PROT CAT.CMD,XW
+++PROT CAT.CMD,X
+++PROT INFO.SYS,C

Remove any previous protection on the CAT.CMD
Utility and write protect it.
Remove all protection from the CAT.CMD utility.
Prohibit INFO.SYS from being displayed in a
catalog listing.

-P.3.1-

QCHECK
The QCHECK utility can be used to examine the contents of the print
queue and to modify it contents. QCHECK has no additional arguments
with it. Simply type QCHECK. QCHECK will stop any printing that is
taking place and then display the current contents of the print queue as
foll ows:
+++QCHECK
POS
1
2
3
COMMAND?

NAME
TEST.
CHPTR.
CHPTR2.

TYPE
.OUT
.OUT
.TXT

RPT
2

a
a

This output says that TEST.OUT is the next file to be printed (or that
it is in the process of being printed) and that 3 copies (1 plus a
repeat of 2) of this file will be printed. After these three copies
have been printed, CHPTR.OUT will be printed and then CHPTR2.TXT.
The
COMMAND? prompt means QCHECK is waiting for one of the following
commands:
COMMAND

FUNCTION

(carriage return) Re-start printing, return to the FLEX command mode.
Q

A Q command will print the queue contents again.

R,#N,X

An R command repeats the file at position #N X times.
If X is omitted the repeat count will be cleared.
Example: R,#3,5

D,#N

A D command removes the file at queue position #N.
If N=I, the current print job will be terminated.
Example: D,#3

A T command will terminate the current print job.
This will cause the job currently printing to quit
and printing of the next job to start. If the
current files RPT count was not zero, it will
print again until the repeat count is O. To
completely terminate the current job use use the
D,#1 command.

N,#N

A N command will make the file at position #N the
next one to be printed after the current print job
is finished. Typing Q after this operation will
show the new queue order.
Example: N,#3

An S command will cause printing to stop. After
the current job is finished, printing will halt
until a G command is issued.

-Q.l.l-

FLEX User's Manual
G

A G command will re-start printing after an S
command has been used to stop it.

A K command will kill the current print process.
All printing and queued jobs will be removed from
the queue. The files are not deleted from disk.

-Q.1. 2-

RENAME
The RENAME command is used to give an existing file a new name in the
directory. It is useful for changing the actual name as well as changing
the extension type.
DESCRIPTION
The general syntax of the RENAME command is:
RENAME,,
where is the name of the file you wish to RENAME and is the new name you are assigning to it. The default extension
for file spec 1 is TXT and the default drive is the working drive. If
no extension is given on , it defaults to that of .
No drive is requird on the second file name, and if one is
given it is ignored. Some examples follow:
+++RENAME,TEST1.BIN,TEST2
+++RENAME,1.LETTER,REPLY
+++RENAME,O.FIND.BIN,FIND.CMD
The first example will RENAME TEST1.BIN to TEST2.BIN. The next example
RENAMEs the file LETTER. TXT on drive 1 to REPLY. TXT. The last line
would cause the file FIND.BIN on drive to be renamed FIND.CMD.
This
is useful for making binary files created by an assembler into command
files (changing the extension from BIN to CMD). If you try to give a
file ,a name which already exists in the directory, the message:

FILE EXISTS
will be displayed on the terminal.
Keep in mind that RENAME only
changes the file's name and in no way changes the actual file's
contents.
One last note of interest. Since utility commands are just like any
other file, it is possible to' rename them also. If you would prefer
some of the command names to be shorter, or different all together,
simply use RENAME and assign~them the names you desire.

-R.1.1-

REPORT
The REPORT command is used to list out the current system
configuration: the type, size, data density, step rate, write
enable, and step size for each disk drive, and the setting of the
print spooler timing.
DESCRIPTION
The general syntax of the REPORT command is:
REPORT
REPORT takes no parameters and prints the system status as defined
by the defaults, SYSGEN, and the SETUP command.
To use the REPORT command, type the following:
+++REPORT
The output is self-explanatory.
SETUP command.

For

information

see

This command uses the FLEX output routines, and its output may
routed to the ,printer or a file using the "P" or "0" commands.

-R.2.1-

the'
be

SAVE
The SAVE command is used for saving a section of memory on the disk.
Its primary use is for saving programs which have been loaded into
memory from tape or by hand.
DESCRIPTION
The general syntax of the SAVE command is:
SAVE,,,[,]
where is the name to be assigned to the file. The default
extension is BIN and the default drive is the working drive~
The
address fields define the beginning and ending addresses of the section
of memory to be written on the disk. The addresses should be expressed
as hex numbers.
The optional would be included if
the program is to be loaded and executed by FLEX.
This address tells
FLEX where execution should begin. Some examples will clarify the use
of SAVE:.
+++SAVE,DATA,100,lFF
+++SAVE,1.GAME,0,1680,100
The first line would SAVE the memory locations 100 to IFF hex on the
disk in a file called DATA.BIN. The file would be put on the working
drive and no transfer address would be assigned. The second example
would cause the contents of memory locations through 1680 to be SAVEd
on the disk in file GAME. BIN on drive 1. Since a transfer address of
100 was specified as a parameter, typing 'GAME. BIN' in response to the
FLEX prompt after saving would cause the file to be loaded back into
memory and execution started at location 100.

If an attempt is made to save a program under a file name that already
exists, the prompt "MAY THE EXISTING FILE BE DELETED? will be
displayed. A Y response will replace the file with the new data to be
saved while a N response will terminate the save operation.
II

Sometimes it is desirable to save noncontiguous segments of memory. To
do thi s it woul d be necessary to fi rst SAVE each segment as a separate
file and then use the APPEND command to combine them into one file. If
the final file is to have a transfer address, you should assign it to
one of the segments as it is being saved. After the APPEND operation,
the final file will retain that transfer address.

-S.l.l-

FLEX User's Manual
SAVE. LOW
There is another form of the SAVE command resident in the UCS.
It is
called SAVE.LOW and loads in a lower section of memory than the standard
SAVE command. Its use is for saving programs in the Utility Command
Space where SAVE.CMD is loaded. Those interested in creating their own
utility commands should consult the 'Advanced Programmer's Guide' for
further details.

..S.1.2..

STARTUP
STARTUP is not a utility command but is a feature of FLEX. It is often
desirable to have the operating system do some special action or actions
upon initialization of the system (during the bootstrap loading
process). As an example, the user may always want to use BASIC
immediately following the boot process. STARTUP will allow for this
without the necessity of calling the BASIC interpreter each time.
DESCRIPTION
FLEX always checks the disk's directory immediately following the system
initialization for a file called STARTUP.TXT. If none is found, the
three plus sign prompt is output and the system is ready to accept
user's commands.
If a STARTUP file is present, it is read and
interpreted as a single command line and the appropriate actions are
performed. As an example, suppose we wanted FLEX to execute BASIC each
time the system was booted. First it is necessary to create the STARTUP
fi 1e:
+++BUILD,STARTUP
=BASIC
=#

+++

The above procedure using the BUILD command will create the desired
file. Note that the file consisted of one line (which is all FLEX reads
from the STARTUP file anyway). This line will tell FLEX to load and
execute BASIC.
Now each time this disk is used to boot the operating
system, BASIC will also be loaded and run.
Note that this example
assumes two things. First, the disk must contain FLEX.SYS and must have
been LINKed in order for the boot to work properly.
Second, it is
assumed that a file called BASIC.CMD actually exists on the disk.
Another example of the use of STARTUP is to set system environment
paramters such as TTYSET parameters or the assigning of a system and
working drive. If the STARTUP command consisted of the following line:
TTYSET,DP=16,WD=60:ASN,W=1:ASN:CAT,0
each time the system was booted the following actions would occur.
First, TTYSET would set the 'depth' to 16 and the'width ' to 60. Next,
assuming the 'end of line ' character is the I: I, the ASN command would
assign the working drive to drive 1.
Next ASN would display the
assigned system and working drives on the terminal. Finally, a CATalog
of the files on drive 0 would be displayed. For details of the actions
of the individual commands, refer to their descriptions elsewhere in
this manual.
As it stands, it looks as if the STARTUP feature is limited to the
execution of a single command line. This is true but there is a way
around the restriction, the EXEC command.
If a longer list of
operations is desired than will fit on one line, simply create a command

-S.2.1-

FLEX User's Manual
file containing all of the commands desired.
file placing the single line:

Then create the STARTUP

EXEC,
where would be replaced by the name assigned to the command
file created. A little imagination and experience will show many uses
for the STARTUP feature.
By directing STARTUP to a file that does not have a return to DOS
command it is possible to lockout access to DOS. You can correct the
problem by hitting the RESET button and beginning execution at address
$CD03. The STARTUP file may then be deleted and if desired, modified.
Directing execution to CD03, the DOS warm start address, bypasses the
DOS STARTUP function.

...S.2.2-

SETTIME

Tbe SETTIME command is provided so tbat tbe user may set the time
on the Time-of-Day clock on the GIMIX 6809 PLUS CPU BOARD with the
Time_of-Day clock option installed.

DESCRIPTION
Tbe general format of the SETTIME command is:
SETTIME
SETTIME takes no parameters and prompts the user for all pertinent
information needed to set the clock.
To use the SETTIME command merely type the following:
+++SETTIME
Tbe computer will tben ~espond like this~
MINUTES (1 - 59)?
Tbe user tben types in the minutes to be set to. Tbe program'tben
proceeds to prompt the user for bours, day of the week, day of the
month and month.
If tbe computer responds to any of the prompts with tbis

message:

INVALID INPUT, PLEASE RE-TRY.
It means that you did not enter a valid input for that prompt.
This program uses the FLEX line buffer to enable the user to
delete or backspace bis entry before carriage return is typed. To
correct an error after carriage return has been typed tbe user
must re-execute the SETTIME command.
After the time has been entered and the following line is showing:
TYPE ANYCHARACTER.TO START THE CLOCK?
The time on the clock will ~tay wbe~e it has been set to until a
cbaracter is typed on the keyboard.
Since this command uses the FLEX line buffer it cannot be use in
multiple statement lines unless it is tbe last statement on the
line.

-S.3.1-

SETUP
The SETUP command is used to set and display the control
information kept by the operating system for each floppy disk.
Using SETUP,
the user can set the step rate, drive size, write
protect, and double step options for each drive, and set the
constant used for
interval timing by the print spooler.
SETUP
also prints a table giving this information.
SETUP operates
either by interpreting a command line or in an interactive mode.
DESCRIPTION
The general syntax of the SETUP command is:
SETUP[,]
where is a list of 2 letter parameter names, each
followed by an equals sign ('='), and then by the value being assigned.
Each parameter should be separated by a comma or a space. If no
parameters are given, the values of all of the TTYSET parameters will be
displayed on the terminal.
The default number base for numerical values is the base most
appropriate to the parameter. In the descriptions that follow, 'hh' is
used for parameters whose default base is hex; 'ddt is used for those
whose default base is decimal. Values which should be expressed in hex
are displayed in the TTYSET parameter listing preceded by a '$'.
Some
examples follow:
+++TTYSET
+++TTYSET,DP=16,WD=63
+++TTYSET,BS=8,ES=3
The fi rstexampl e simply lists the current values of all TTYSET
parameters on the terminal. The next line sets the depth 'DP' to 16
lines and the terminal width, 'WD' to 63 columns. The last example sets
the backspace character to the value of hex 8, and the escape character
to hex 3.
The following fully describes all of the TTYSET parameters available to
the user. Their initial values are defined, as well as any special
characteristics they may possess.
BS=hh

BackSpace character

This sets the 'backspace' charcter to the character having the ASCII hex
value of hh. This character is initially a 'control H' (hex 08), but
may be defined to any ASCII character. The action of the backspace
character is to delete the last character typed from the terminal. If
two backspace characters are typed, the last two characters will be
deleted, etc. Setting BS=O will disable the backspace feature.

-T.1.1-

FLEX User's Manual
BE=hh

Backspace Echo character

This defines the character to be sent to the terminal after a
'backspace' character is received. The character printed will have the
ASCII hex value of hh. This character is initially set to a null but
can be set to any ASCII character.
The BE command also has a very special use that will be of interest to
some terminal owners, such as SWTPC CT-64.
If a hex 08 is specified as the echo character, FLEX will output a space
(20) then another 08. This feature is veryuesful for terminals which
decode a hex 08 as a cursor left but which do not erase characters as
the cursor is moved.
Example:

Say that you mis-typed the word cat as shown below:
+++CAY

typing in one CTRL-H (hex 08) would position the cursor on top of the Y
and delete the Y from the DOS input buffer. FLEX would then send out a
space ($20) to erase the Y and another 08 (cursor left) to re-position
the cursor.
DL=hh

DeLete character

This sets the 'delete current line' character to the hex value hh. This
character is initially a 'control X' (hex 18). The action of the delete
character is to 'erase' the current input line before it is accepted
into the computer for execution. Setting DL=O will disable the line
delete feature.
EL=hh

End of Line character

This character is the one used by FLEX to separate multiple commands on
one input line.
It is initially set to a colon (':'), a hex value of
3A. Setting this character to 0 will disable the multiple command per
line capability of FLEX. The parameter 'EL=hh' will set the end of line
character to the character having the ASCII hex value of hh.
This
character must be set to a printable character (control characters not
a 11 owed).
DP=dd

Depth count

This parameter specifies that a page consists of dd (decimal) physical
lines of output. A page may be considered to be the number of lines
between the fold if using fan folded paper on a hard copy terminal, or a
page may be defined to be the number of lines which can be displayed at
anyone time on a CRT type terminal.
Setting DP=O will disable the
paging (this is the initial value).
See EJ and PS below for more
details of depth.

-T.l.2-

FLEX User's Manual
WD=dd

WiDth

The WD parameter specifies the (decimal) number of characters to be
displayed on a physical line at the terminal (the number of columns).
Lines of text longer than the value of width will be 'folded ' at every
multiple of WD characters. For example, if WD is 50 and a line of 125
characters' is to be displayed, the first 50 characters are displayed on
a physical line at the terminal, the next 50 characters are displayed on
the next physical line, and the last 25 characters are displayed on the
third physical line.
If WD is set to 0, the width feature will be
disabled, and any number of characters will be permitted on a physical
1 i nee

NL=dd

NuLl count

This parameter sets the (decimal) number of non-printing (Null) 'pad '
characters to be sent to the terminal at the end of each line. These
pad characters are used so the terminal carriage has enough time to
return to the left margin before the next printable characters are sent.
The initial value is 4. Users using CRT type terminals may want to set
NL=O since no pad characters are usually required on this type of
termi nal •
TB=hh

TaB character

The tab character is not used by FLEX but some of the utilities may
require one (such as the Text Editing System). This parameter will set
the tab character to the character having the ASCII hex value hh. This
character should be a printable character.
EJ=dd

EJect count

This parameter is used to specify the (decimal) number of leject lines '
to . be sent to the terminal at the bottom of each page. If Pause is
lon', the leject sequence l is sent to the terminal after the pause is
terminated. If the value dd is zero (which it is by default), no leject
lines ' are issued. An eject line is simply a blank line (line feed)
sent to the terminal. This feature is especially useful for terminals
with fan fold paper to skip over the fold (see Depth). It may also be
useful for certain CRT terminals to be able to erase the previous screen
contents at the end of each page.
PS=Y

PS=N

PauSe control

This parameter enables (PS=Y) or disables (PS=N) the end-of-page pause
feature. If Pause is on and depth is set to some nonzero value, the
output display is automatically suspended at the end of each page. The
output may be restarted by typing the lescape l character (see ES
description). If pause is disabled, there will be no end-of-page
pausing. This feature is useful for those using high-speed CRT terminals

-T.1.3-

FLEX User's Manual
to suspend output long enough to read the page of text.
ES=hh

EScape character

The character whose ASCII hex value is hh is defined to be the 'escape
character'. Its initial value is $lB, the ASCII ESC character. The
escape character is used to stop output from being displayed, and once
it is stopped, restart it again •. It is also used to restart output
after Pause has stopped it. As an example, suppose you are LISTing a
long text file on the terminal and you wish to temporarily halt the
output. Typing the 'escape character' will do this (this feature is not
supported on computers using a Control
Port for terminal
communications). At this time (output halted), typing another 'escape
character' will resume output, while typing a RETURN key will cause
control to return to FLEX and the three plus sign prompt will be output
to the terminal.
It should be noted that line output stopping always
happens at the end of a line.

-T.l.4-

TIME

The TIME command is provided so that the user may read the time on
the Time-of-Day clock on the GIMIX 6809 PLUS CPU CARD with the
Time-of-Day clock option installed.

DESCRIPTION
The general syntax of the TIME command is:
TIME
TIME takes
clock.

parameters

and

prints the time as read from the

To use the TIME command merely type the following:
+++TIME
The computer oUtput will have the following format:
FRIDAY

SEPTEMBER 05, 09:44:41 AM

If the computer responds:
ERROR READING TIME,

CLOCK NOT SET

It means that the program detected an invalid value ·from the clock
and the clock needs to be set. To set the time use the SETTIME
command.
This command uses the FLEX output routines and therefore the
output can be re-directed with any of·the FLEX output re-direction
command (i.e.
'PI, '0', etc.).
If there is no Time-of-Day clock installed in your system this
program may cause the CPU to loop infinitely.
If this happens the
only way to exit the loop is to press the 'RESET' button on the
front panel.

-T.2.1-

UPDATE

The UPDATE utility enables the user to change the date in a file's
directory entry to the "current date".

DESCRIPTION
The general synatax of the UPDATE command is:
UPDATE,
Where is the name of the file for which the date is to
be changed.
If the file extension is not specified, UPDATE
defaults to an extension of .TXT. The file's directory entry is
changed to reflect the current date.
UPDATE does not alter the
contents of the file itself.

-U. L 1-

UNSNARL
The UNSNARL command is used to reorganize the free chain on a FLEX
disk (the list of all unused sectors).
This helps reduce
fragmenting of files on the disk, and improves access times.
DESCRIPTION
The general syntax of the UNSNARL command is:
UNSNARL, is the number of the drive with the disk to be
reorganized, and is the number of the drive where
the FREEMAP.TMP file can be stored. This must be different from
the work drive and defaults to drive 0.
UNSNARL will then read
all the sectors in the free chain of the indicated disk, and make
a list of all the segments in the chain.
A segment is a sector or group of sectors linked in logical order.
On a newly formatted disk there is only one segment, which has all
the sectors on the disk. As files are created and deleted, this
segment is broken into smaller and smaller segments, and the links
among them become more and more random. This results in files
being stored in fragments scattered over the disk, and increases
access times, especially for random-access files.
UNSNARL scans the free chain and creates a list of all the
segments in the free chain. For lnsurance this list is saved on
the backup disk as the FREEMAP.TMP file. Then UNSNARL sorts the
list of segments in ascending order of disk address. Next the
sector link in the last sector of each segment is pointed to the
first sector of the next segment. This frequently causes several
small segments to be merged into one large segment.
Finally the
pointers . to the start and end of the free chain in the System
Information Record are corrected. At each step, UNSNARL displays
a descriptive message on the console. Example:
+++UNSNARL,l,O
READING FREE CHAIN
FREE CHAIN READ, NOW SAVING MAP
MAP SAVED, NOW SORTING EXTENT LIST
LIST SORTED, NOW RELINKING FREE CHAIN
RELINK DONE, DELETING MAP FILE
+++
The FREEMAP.TMP file is created as insurance against power
glitches or other interruptions.
If UNSNARL is interrupted while
it is relinking the free chain, the free chain will be left in a
confused state, and creating or deleting files on that disk would
be impossible. FREEMAP.TMP makes it possible for UNSNARL to pick
up where it left off. The UNSN1 command is the same as UNSNARL,

-U.2.1-

FLEX User's Manual
except that instead of reading the free chain to create the
of segments,
it reads the list from the FREEMAP.TMP file.
UNSNARL or UNSNl successfully completes the relinking,
FREEMAP.TMP file is deleted.

list
Once
the

UNSNARL has no effect whatever on files, so a fragmented file will
remain fragmented until it is rewritten onto an unfragmented
segment of free chain.
Thus to keep fragmentation to a minimum
UNSNARL should be used periodically, in order to clean up the
fragmentation left by formerly fragmented files now using segments
from the reorganized free chain.
UNSNARL only reduces file fragmentation, it does not eliminate it.
The only way to eliminate fragmentation entirely is to format a
new disk and perform a sequential copy of all files to the blank
disk.
This method is practical for floppies, but not for high
capacity hard disks such as the GIMIX Winchester Disk Subsystems.
Therefore GIMIX has developed the UNSNARL command as a way for
users of our hard disk systems to avoid the degradation of system
performance caused by severe file fragmentation.
NOTE: the degree of fragmentation in the free chain, and therefore
the need for running UNSNARL, can be determined with the FREEMAP
command.

-U.2.2-

VERIFY
The VERIFY command is used to set the File Management System'·s write
verify mode. If VERIFY is on, every sector which is written to the disk
is read back from the disk for verification (to make sure there are no
errors in any sectors). With VERIFY off, no verification is performed.
DESCRIPTION
The general syntax of the VERIFY command is:
VERIFY[,ON]
or
VERIFY[,OFF]
where ON or OFF sets the VERIFY mode accordingly. If VERIFY is typed
without any parameters, the current status of VERIFY will be displayed
on the terminal. Example:
+++VERIFY,ON
+++VERIFY
The first example sets the VERIFY mode to ON.
The second line would
di spl ay the current status (ON or OFF) of the VERIFY mode. VERIFY
causes slower write times, but it is recommended that it be left on for
your protection.

-V.l.l-

VERSION
The VERSION utility is used to display the version number of a utility
command. If problems or updates ever occur in any of the util ities, they
may be repl aced wi th updated versi ons. The VERSION command wi 11 all ow
you to determine which version of a particular utility you have.
DESCRIPTION
The general syntax of the VERSION command is:
VERSION,
where is the name of the utility you wish to check. The
default extension is CMD and the drive defaults to the working drive.
As an example:
+++VERSION,O.CAT
would display the version number of the CAT command (from drive 0)
the termi nal •

-V.2.1-

XOUT
XOUT is a special form of the delete command which deletes all files
having the extension .OUT.
DESCRIPTION The general syntax of XOUT is:
XOUT[,]
where is the desired drive number.
If no drive is
specified all, .OUT files on the working drive will be deleted and if
auto drive searching is enabled, all .OUT files on drives 1 and 2 will
be deleted. XOUT will not delete any files which are delete protected
or which are currently in the print queue.
Example:
+++XOUT
+++XOUT 1

-X.l.l-

YEAR

The YEAR command is used to display or cbange tbe year in the
internal FLEX date register. Tbis command is used wben FLEX is
patched to load tbe current day and montb from tbe Time-of-Day
clock on tbe GIMIX 6809 CPU board (see tbe section on patcb~ng
FLEX to use tbe Time-of-Day clock). Tbe YEAR command should be
included in tbe STARTUP file to set tbe year wben tbe system is
booted.

DESCRIPTION
Tbe general syntax of tbe YEAR command is:
YEAR,[YY]
Wbere YY is the last two digits of tbe current year.
If no year
is entered the current year in the FLEX system date area will be
printed.
To use the YEAR command type tbe following:
+++YEAR
or
+++YEAR,81
The first example prints tbe year in the FLEX date register.
second example sets the year to 1981.
Tbe error message
INVALID YEAR IN INPUT LINE
Indicates that an illegal value was entered for tbe year [YY}.

-Y.l.1-

The

The Y utility enables the user to automatically answer "Y" (yes)
to
"Y or N" prompts from other utilities.
The Y utility is
especially useful when writing EXEC files.
DESCRIPTION
The general synatax of the Y command is:
Y,
Where [,],
Default extension: .TXT
Description page: A.1
ASN[,W=][,S=]
Description page: A.2
BUILD,
Default extension: .TXT
Description pge: B.1
BACKUP,,[,CPU speed]
Description page: B.2
CAT[,][,]
Description page: C.1
COPY,,
COPY,,
COPY,,[,]
Descripyion page: C.2
CLEAN
Description page: C.3
CHECKSUM[,]
Description page: C.4
CMPBIN,,
Description page: C.5
DATE[,]
Description page: D.1
DELETE,[,]
Description page: D.2
DCOPY,,,[],[],[](,R]
Description page: D.3
EXEC,
Default extension: .TXT
Description page: E.1
EXTEND[,,]
Description page: E.2
FORMAT[,]
Description page: F.1
FIXDAY
Description page: F.2
FREEMAP,
Description page: F.3
4.1

GET,[,]
Default extension: .BIN
Description page: G.1
HARD
Description page: H.1
HARDFORM
Description page: H.2
I,(file spec>,
Default extension: .TXT
Description page: 1.1
JUMP,
Description page: J.1
LINK,
Default extension: .SYS
Description page: L.1
LIST,[,][,N]
Default extension: .TXT
Description page: L.2
MON
Description page: 1.7
NAME[,]
Description page: N.1
N,
Description page: N.2
O,,
Default extension: .OUT
Description page: 0.1
P,(command>
Description page: P.1
PRINT,(file spec>
Default extension: .OUT
Description page: P.2
PROT,[,(options)]
Description page: P.3
QCHECK
Description page: Q.1
RENAME,(file spec>,
Default extension: .TXT
Description page: R.1

4.2

REPORT
Description page: R.2
SAVE,,,[,]
Default extension: .BIN
Description page: S.l
STARTUP
Description page: S.2
SETTIME
Description page: S.3
SETUP[,[options][,]
Description page: T.1
TIME
Description page: T.2
UPDATE,
Default extension: .TXT
Description page: U.1
UNSNARL,,
Description page: U.2
VERIFY[,]
Description page: V.1
VERSION,
Default extension: .CMD
Description page: V.2
XOUT[,]
Description page: X.1
YEAR[,YY]
Description page: Y.1
Y,
Description page: Y.2

4.3

FLEX Programmer's Manual

COPYR IGHT © 1978 by
Technical Systems Consultants, Inc.
P.O. Box 2570
West Lafayette, Indiana 47906
All Rights Reserved

'" A...EX is a trademark of Technical Systems Consultants, Inc.

This entire manual is provided for the personal use and enjoyment of the purchaser. Its
contents are copyrighted by Technical Systems Consultants, Inc., and reproduction, in
whole or in part, by any means is prohibited. Use of this program, or any part thereof,
for any purpose other than single end use by the purchaser is prohibited.

DISClAIMER

The supplied software is intended for use only as described in this manual. Use of
undocumented features or parameters may cause unpredictable results for which Technical
Systems Consultants, Inc. cannot assume responsibility. Although every effort has been
made to make the supplied software and its documentation as accurate and functional as
possible, Technical Systems Consultants, Inc. will not assume responsibility for any
damages incurred or generated by such ma terial. Technical Systems Consultants, Inc.
reserves the right to make changes in such material at any time without notice.

CONTENTS
1

I. Introduction
II.

3
3
8
16

Disk Operating System
DOS Memory Map
User Callable Routines
User Written Commands
Disk Resident Commands
Comments About Commands
Examples of DOS Calls

18
19
21
22
26
27
28
37
38

I II. File Management System
File Control Blocks
FMS Entry Poi nts
FMS Global Variables
FMS Function Codes
Random Files
Error Numbers

IV. Disk Drivers

43
43
44
44
45
46

V. Disk Structures
Diskette Initialization
Directory Sectors
Data Sectors
Binary Files
Text Files

47
49

VI. Writing Utility Commands
Example Program

VII. The DOS LINK Utility

53
54

VI II. Printer Routines
The P Utility

57
57
57

IX. General Information
Interrupts in FLEX
System Memory Map

-iii-

Preface
The purpose of the Advanced Programmer's Manual is to provide the
assembler language programmer with the information required to make
effective use of the available system routines and functions.
This
manual applies to the 6809 version of FLEX. The programmer should keep
this manual close at hand while learning the system. It is organized to
make it convenient as a quick reference guide as well as a thorough
reference manual. The manual is not written for the novice programmer
and assumes the user to have a thorough understanding of assembler
language programming techniques.

-v-

Introduction
The FLEX Operating System consists of three main parts: the Disk
Operating System (DOS) which processes commands, the File Management
System (FMS) which manages files on a diskette, and the Utility Command
Set, which are the user-callable commands. The Utility Command Set is
described in the FLEX User's Guide.
Details of the Disk Operating
System and File Management System portions of FLEX are described in this
manual, which is intended for the programmer who wishes to write his
own commands or process disk files from his own program.
When debugging programs which use disk files and the File Management
System, the user should take the following precautions:
1.
Write-protect the system diskette by exposing or covering the
write-protect cutout on the diskette. See the FLEX User's Guide for
further details on this operation. This will prevent destruction of the
system disk in case the program starts running wild.

Use an empty scratch diskette as the working diskette to which your
2.
program will write any data files. If something goes wrong and the
diskette is destroyed, no valuable data will have been lost.
3. Test your program repeatedly, especially with "special cases" of
data input which may not be what the program is expecting. Well-written
programs abort gracefully when detecting errors, not dramatically.
A careful programmer, using the information in this manual, should be
able to make the fullest use of his floppy disk system.

-1-

FLEX Advanced Programmer's Guide
DISCLAIMER
This product is intended for use only as described in this document and
the FLEX User's Guide. Technical Systems Consultants will not be
responsible for the proper functioning of features or parameters.
The
user is urged to abide by the warnings and cautions issued in this
document lest valuable data or diskettes be destroyed.

PATCHING "FLEX"
It is not possible to patch FLEX. Technical Systems Consultants cannot
be responsible for any destructive side-effects which may result from
attempts to patch FLEX.

-2-

FLEX Advanced Programmer's Guide
THE DISK OPERATING SYSTEM
The Disk Operating System (~OS) forms the communication link between the
user (via a computer terminal) and the File Management System. All
commands are accepted through ~OS. Functions such as file specification
parsing, command argument parsing, terminal I/O, and error reporting are
all handled by ~OS. The following sections describe the DOS global
variable storage locations (Memory Map), the DOS user callable
subroutines, and give examples of some possible uses.
DOS MEMORY MAP
The following is a description of those memory locations within the DOS
portion of FLEX which contain information of interest to the programmer.
The user is cautioned against utilizing for his own purposes any
locations documented as being either "reserved" or "system scratch", as
this action may cause destruction of data.
$C080-$COFF - Line Buffer
The line buffer is a 128 byte area into which characters typed at
the keyboard are placed by the routine INBUF. All characters
entered from the keyboard are placed in this buffer with the
exception of· control characters.
Characters which have been
deleted by entering the backspace character do not appear in the
buffer, nor does the backspace character itself appear. The
carriage return signaling the end of the keyboard input is,
however, put in the buffer. This buffer is also used to hold the
STARTUP file during a coldstart (boot) operation.
$CCOO - TTYSET Backspace Character
This is the character which the routine INBUF will interpret as the
Backspace character.
It is user definable through the TTYSET DOS
Utility. Default = $08, a Control-H (ASCII BS).
$CC01 - TTYSET Delete Character
This is the character which the routine INBUF will interpret as the
line cancel or Delete character. It is user definable through the
TTYSET DOS Utility. Default = $18, a control-X (ASCII CAN).
$CC02 - TTYSET End of Line Character
This is the character DOS recognizes as the multiple command per
line separato.r.
It is user definable through the TTYSET Utility.
Default = $3A, a colon (:).
$CC03 - TTYSET Depth Count
This byte determines how many lines DOS will print on a page before
It may be set by the user with the
Pausing or issuing Ejects.
TTYSET command. Default = O.
$CC04 - TTYSET Width Count
This byte tells DOS how many characters to output on each line. If
zero, there is no limit to the number output. This count may be
set by the user using TTYSET. Default = O.

-3-

FLEX Advanced Programmer I s Guide
$CC05 - TTYSET Null Count
This byte informs DOS of the number of null or pad characters to be
output after each carriage return, line feed pair. This count may
be set using TTYSET. Default = 4.
$CC06 - TTYSET Tab Character
This byte defines a tab character which may be used by other
programs, such as the Editor. DOS itself does not make use of the
Tab character. Default = 0, no tab character defined.
$CC07 - TTYSET Backspace Echo Character
This is the character the routine INBUF will echo upon the receipt
of a backspace character. If the backspace echo character is set
to a $08, and the backspace character is also a $08, FLEX will
output a space ($20) prior to the outputting of the backspace echo
character. Default = O.
$CC08 - TTYSET Eject Count
The Eject Count instructs DOS as to the number of blank lines to be
output after each page. (A page is a set of lines equal in number
to the Depth Count). If this byte is zero, no Eject lines are
output. Default = O.
$CC09 - TTYSET Pause Control
The Pause byte instructs DOS what action to take after each page is
output. A zero value indicates that the pause feature is enabled;
a non-zero value, pause is disabled. Default = $FF, pause
disabled.
$CCOA - TTYSET Escape Character
The Escape character causes DOS to
Default = $lB, ASCII ESC.

pause after an output line.

$CCOB - System Drive Number
This is the number of the disk drive from which commands are
loaded. If this byte is $FF, both drives 0 and 1 will be searched.
Default = drive #0.
$CCOC - Working Drive Number
This is the number of the default disk drive referenced for
non-command files. If this byte is $FF, both drives 0 and 1 will
be searched. Default = drive #0.
$CCOD - System Scratch
$CCOE-$CC10 - System Date Registers
These three bytes are used to store the system date. It is stored
in binary form with the month in the first byte, followed by the
day, then the year. The year byte contains only the tens and ones
digits.

-4-

FLEX Advanced Programmer's Guide
$CC11 - Last Terminator
This location contains the most recent non-alphanumeric character
encountered in processing the line buffer. See commentary on the
routines NXTCH and CLASS in the section "User-Callable System
Routines".
$CC12-$CC13 - User Command Table Address
The programmer may store into these locations the address of a
command table of his own construction. See the section called
"User-Written Commands" for details.
Default = 0000, no user
command table is defined.
$CC14-$CC15 - Line Buffer Pointer
These locations contain the address of the next character in the
Line Buffer to be processed. See documentation of the routines
INBUFF,
NXTCH,
GETFIL,
GETCHR, and DOCMND in the section
"User-Callable System Routines" for instances of its use.
$CC16-$CC17 - Escape Return Register
These locations contain the address to which to jump if a RETURN is
typed while output has been stopped by an Escape Character. See
the FLEX User's Guide, TTYSET, for information on Escape
processing.
See also the documentation for the routine PCRLF in
the section called "User-Callable System Routines".
$CC18 - Current Character
This location contains the most recent character taken from the
Line Buffer by the NXTCH routine. See documentation of the NXTCH
routine for additional details.
$CC19 - Previous Character
This location contains the previous character taken from the Line
Buffer by the NXTCH routine.
See documentation of the NXTCH
routine for additional details.
$CC1A - Current Line Number
This location contains a count of the number of lines currently on
the page.
This value is compared to the Line Count value to
determine if a full page has been printed.
$CC1B-$CC1C - Loader Address Offset
These locations contain the 16-bit bias to be added to the load
address of a routine being loaded from the disk. See documentation
of the System Routine LOAD for details. These locations are also
used as scratch by some system routines.
$CC1D - Transfer Flag
After a program has been loaded from the disk (see LOAD
documentation), this location is non-zero if a transfer address was
found during the loading process. This location is also used as
scratch by some system routines.

-5-

FLEX Advanced Programmer's Guide
$CClE-$CClF - Transfer Address
If the Transfer Flag was set non-zero by a load from the disk (see
LOAD documentation), these locations contain the last transfer
address encountered. If the Transfer Flag was set zero by the disk
load, the content of these locations is indeterminate.
$CC20 - Error Type
This location contains the error number returned by several of the
File Management System functions. See the "Error Numbers" section
of this document for an interpretation of the error numbers.
$CC2l - Speci al I/O Fl ag
If this byte is non-zero, the PUTCHR routine will ignore the TTYSET
Width feature and also ignore the Escape Character.
The routine
RSTRIO clears this byte. Default = O.
$CC22 - Output Switch
If zero, output performed by the PUTCHR routine is through the
routine OUTCH. If non-zero, the routine OUTCH2 is used. See
documentation of these routines for details.
$CC23 - Input Switch
If zero, input performed by GETCHR is through the routine INCH. If
it is non-zero, the routine INCH2 is used.
See documentation of
these routines for details.
$CC24-$CC25 - File Output Address
These bytes contain the address of the File Control Block being
used for file output. If the bytes are zero, no file output is
performed. See PUTCHR description for details. These locations are
set to zero by RSTRIO.
$CC26-$CC27 - File Input Address
These bytes contain the address of the File Control Block being
used for file input.
If the bytes are zero, no file input is
performed. The routine RSTRIO clears these bytes. See GETCHR for
details.
$CC28 - Command Flag
This location is non-zero if DOS was called from a user program via
the DOCMND entry point. See documentation of DOCMND for details.
$CC29 - Current Output Column
This location contains a count of the number of characters
currently in the line being output to the terminal. This is
compared to the TTYSET Width Count to determine when to start a new
line. The output of a control character resets this count to zero.
$CC2A - System Scratch

-6-

FLEX Advanced Programmer's Guide
$CC2B-$CC2C - Memory End
These two bytes contain the end of user memory. This location is
set during system boot and may be read by programs requiring this
information.
$CC20-$CC2E - Error Name Vector
If these bytes are zero, the routine RPTERR will use the file
ERRORS.SYS as the error file.
If they are non-zero, they are
assumed to be the address of an ASCII string of characters (in
directory format) of the name of the file to be used as the error
file. See the description of RPTERR for more details.
$CC2F If
a
If

File Input Echo Flag
this byte is non-zero (default) and input is being done through
file, the character input will be echoed to the output channel.
this byte is zero, the character retrieved will not be echoed.

$CC30-$CC40 - System Scratch
$CC4E-$CCBF - System Constants
$CCCO-$CC07 - Printer Initialize
This area is reserved for the overlay of the system printer
initializization subroutine.
$CC08-$CCE3 - Printer Ready Check
This area is reserved for the overlay of the system "check for
printer ready" subroutine.
$CCE4-$CCF7 - Printer Output
This area ;s reserved for the overlay of the system printer output
character routine. See Printer Routine descriptions for details.
$CCF8-$CCFF - System Scratch

-7-

FLEX Advanced Programmer's Guide
USER-CALLABLE SYSTEM ROUTINES
Unless specifically documented otherwise, the content of all registers
should be presumed destroyed by calls to these routines. All routines,
unless otherwise indicated,should be called with a JSR instruction. In
the 6809 version of FLEX the Y and U registers are preserved across all
the following routines. The A,B and X registers should be considered
changed except where noted otherwise.
Often a value or status is
returned in one of these registers.
$CDOO (COLDS) Coldstart Entry Point
The BOOT program loaded from the disk jumps to this address to
initialize the FLEX system. Both the Disk Operating System (DOS)
portion and the File Management System portion (FMS) of FLEX are
initialized. After initialization, the FLEX title line is printed
and the STARTUP file, if one exists, is loaded and executed.
This
entry point is only for use by the BOOT program, not by user
programs. Indiscriminate use of the Coldstart Entry Point by user
programs could result in the destruction of the diskette.
Documentation of this routine is
included here only for
completeness.
$CD03 (WARMS) Warmstart Entry Point
This is the main re-entry point into DOS from user programs. A JMP
instruction should be used to enter the Warmstart Entry Point. At
this point, the main loop of DOS is entered. The main loop of DOS
checks the Last Terminator location for a TTYSET end-of-line
character.
If one is found, it is assumed that there is another
command on the line, and DOS attempts to process it.
If no
end-of-line is in the Last Terminator location DOS assumes that the
current command line is finished, and looks for a new line to be
input from the keyboard. If, however, DOS was called from a user
program through the DOCMND entry point, control will be returned to
the user program when the end of a command line is reached.
$CD06 (RENTER) DOS Main Loop Re-entry Point
This is a direct entry point into the DOS main loop. None of the
Warmstart initialization is performed. This entry point must be
entered by a JMP instruction. Normally, this entry point is used
internally by DOS and user-written programs should not have need to
use it.
For an example of use, see "Printer Driver" section for
details.

-8-

FLEX Advanced Programmer's Guide
$C009 (INCH) Input Character
$COOC (INCH2) Input Character
Each of these routines inputs one character from the keyboard,
returning it to the calling program in the A-register. The address
portion of these entries points to a routine in the Custom I/O
package. They may be altered by changing that package. The GETCHR
routine normally uses INCH but may be instructed to use INCH2 by
setting the IIlnput Switch" non-zero (see Memory Map).
The user's
program may change the jump vector at the INCH address to refer to
some other input routine such as a routine to get a character from
pape~ tape.
The INCH2 address should never be altered. The
Warmstart Entry Point resets the INCH jump vector to the same
routine as INCH2 and sets the Input Switch to zero. RSTRIO also
resets these bytes. User programs should use the GETCHR routine,
documented below, rather than calling INCH, because INCH does not
check the TTYSET parameters.
$COOF (OUTCH) Output Character
$C012 (OUTCH2) Output Character
On entry to each of these routines, the A-register should contain
the character being output. Both of these routines output the
character in the A-register to an output device. The OUTCH routine
usually does the same as OUTCH2; however, OUTCH may be changed by
programs to refer to some other output routine. For example, OUTCH
may be changed to drive a line printer. OUTCH2 is never changed,
and always points to the output routine in the Custom I/O package.
This address may not be patched to refer to some other output
routine.
The routine PUTCHR, documented below, calls one of these
two routines, depending on the content of the location "Output
Switch" (see Memory Map).
The Warmstart Entry Point resets the
OUTCH jump vector to the same routine as OUTCH2, and sets the
Output Switch to zero. RSTRIO also resets these locations. User
routines should use PUTCHR rather than calling OUTCH or OUTCH2
directly since these latter two do not check the TTYSET parameters.
$C015 (GETCHR) Get Character
This routine gets a single character from the keyboard. The
character is returned to the calling program in the A-register.
The Current Line Number location is cleared by a call to GETCHR.
Because this routine honors the TTYSET parameters, its use is
preferred to that of INCH.
If the 1ocati on "Input Swi tch" is
non-zero, the routine INCH2 will be used for input. If zero, the
byte at IIFile Input Address" is checked. If it is non-zero, the
address at this location is used as a File Control Block of a
previously opened input file and a character is retrieved from the
file. If zero, a character is retreived via the INCH routine. The
X and B registers are preserved.

-9-

FLEX Advanced Programmer's Guide
$CD18 (PUTCHR) Put Character
This routine ~utputs a character to a device, honoring all of the
TTYSET parameters. On entry, the character should be in the
A-register. If the "Special I/O Flag" (see Memory Map) is zero, the
column count is checked, and a new line is started if the current
line is full.
If an ACIA is being used to control the monitor
terminal, it is checked for a TTYSET Escape Character having been
typed.
If so, output will pause at the end of the current line.
If the location "Output Switch" is non-zero, the routine OUTCH2 is
used to send the character.
If zero, the location File Output
Address is checked.
If it is non-zero the contents of this
location is used as a address of a File Control Block of a
previously opened for write file, and the character is written to
the file.
If zero, the routine OUTCH is called to process the
character. Normally, DUTCH sends the character to the termi nal •
The user program may, however, change the address portion of the
DUTCH entry point to go to another character output routine. The X
and B registers are preserved.
$CD1B (INBUFF) Input into Line Buffer
This routine inputs a line from the keyboard into the Line Buffer.
The TTYSET Backspace and Delete characters are checked and
processed if encountered. All other control characters except
RETURN and LINE FEED, are ignored. The RETURN is placed in the
buffer at the end of the line. A LINE FEED is entered into the
buffer as a space character but is echoed back to the terminal as a
Carriage Return and Line Feed pair for continuation of the text on
a new line. At most, 128 characters may be entered on the line,
including the final RETURN. If more are entered, only the first
127 are kept, the RETURN being the 128th. On exit, the Line Buffer
Pointer is pointing to the first character in the Line Buffer.
Caution: The command line entered from the keyboard is kept in the
Line Buffer. Calling INBUF from a user program will destroy the
command line, including all unprocessed commands on the same line.
Using INBUF and the Line Buffer for other than DOS commands may
result in unpredictable side-effects.
$CD1E (PSTRNG) Print String
This routine is similar to the PDATA routine in SWTBUG and DISKBUG.
On entry, the X-register should contain the address of the first
character of the string to be printed. The string must end with an
ASCII EOT character ($04). This routine honors all of the TTYSET
conventions when printing the string. A carriage return and line
feed are output before the string. The B register is preserved.

-10-

FLEX Advanced Programmer's Guide
$CD21 (CLASS) Classify Character
This routine is used for testing if a character is alphanumeric
(i.e. a letter or a number). On entry, the character should be in
the A-register.
If the character is alphanumeric, the routine
returns with the carry flag cleared.
If the character is not
alphanumeric, the carry flag is set and the character is stored in
the Last Termi nator 1ocati on. All regi sters are preserved by thi s
routine.
$CD24 (PCRLF) Print Carriage Return and Line Feed
In addition to printing a carriage return and line feed, this
routine checks and honors several TTYSET conditions.
On entry,
this routine checks for a TTYSET Escape Character having been
entered while the previous line was being printed.
If so, the
routine waits for another TTYSET Escape Character or a RETURN to be
typed. If a RETURN was entered, the routine clears the Last
Terminator location so as to ignore any commands remaining in the
command line, and then jumps to the address contained in the Escape
Return Register locations. Unless changed by the user's program,
this address is that of the Warmstart Entry Point. If, instead of
a RETURN, another TTYSET Escape Character was typed, or it wasn't
necessary to wait for one, the Current Line Number is checked.
If
the last line of the page has been printed and the TTYSET Pause
feature is enabled, the routine waits for a RETURN or a TTYSET
Escape Character, as above. Note that all pausing is done before
the carriage return and line feed are printed. The carriage return
and line feed are now printed, followed by the number of nulls
specified by the TTYSET Null Count. If the end of the page was
encountered on entry to this routine, an "eject" is performed by
issuing additional carriage return, line feeds, and nulls until the
total number of blank lines is that specified in the TTYSET Eject
Count. The X register is preserved.
$CD27 (NXTCH) Get Next Buffer Character
The character in location Current Character is placed in location
Previous Character. The character to which the Line Buffer Pointer
points is taken from the Line Buffer and saved in the Current
Character location. Multiple spaces are skipped so that a string
of spaces looks no different than a single space. The Line Buffer
Pointer is advanced to pOint to the next character unless the
character just fetched was a RETURN or TTYSET End-of-Line
character. Thus, once an end-of-line character or RETURN is
encountered, additional calls to NXTCH will continue to return the
same end-of-line character or RETURN.
NXTCH cannot be used to
cross into the next command in the buffer. NXTCH exits through the
routine CLASS, automatically classifying the character. On exit,
the character is in the A-register, the carry is clear if the
character is alphanumeric, and the B-register and X- register are
preserved.

-11-

FLEX Advanced Programmer's Guide
$CD2A (RSTRIO) Restore I/O Vectors
This routine forces the OUTCH jump vector to point to the same
routine as does the OUTCH2 vector. The Output Switch location and
the Input Switch location are set to zero. The INCH jump vector is
reset to poi nt to the same address as the INCH2 vector. Both the
File Input Address and the File Output Address are set to zero.
The A-register and B-register are preserved by this routine.
$CD2D (GETFIL) Get File Specification
On entry to this routine, the X-register must contain the address
of a File Control Block (FCB), and the Line Buffer Pointer must be
pointing to the first character of a file specification in the Line
Buffer. This routine will parse the file specification, storing
the various components in the FCB to which the X-register points.
If a drive number was not specified in the file specification,
the working drive number will be used. On exit, the carry bit will
be clear if no error was detected in processing the file
specification. The carry bit will be set if there was a format
error in the file specification. If no extension was specified in
the file specification, none is stored. The calling program should
set the default extension desired after GETFIL has been called by
using the SETEXT routine. The Line Buffer Pointer is left pointing
to the character immediately beyond the separator, unless the
separator is a carriage return or End of Line character. If an
error was detected, Error number 21 is stored in the error status
byte of the FCB. The X register is preserved with a call to this
routine.
$CD30 (LOAD) File Loader
On entry, the system File Control Block (at $C840) must contain the
name of a file which has been opened for binary reading. This
routine is used to load binary files only, not text files.
The
file is read from the disk and stored in memory, normally at the
load addresses specified in the binary file itself. It is possible
to load a binary file into a different memory area by using the
Loader Address Offset locations. The 16-bit value in the Loader
Address Offset locations is added to the addresses read from the
binary file. Any carry generated out of the most significant bit
of the address is lost.
The transfer address, if any is
encountered, is not modified by the Loader Address Offset.
Note
that the setting of a value in the Loader Address Offset does not
modify any part of the content of the binary file.
It does not
act as a program relocator in that it does not change any
addresses in the program itself, merely the location of the program
in memory.
If the the file is to be loaded without an offset, be
certain to clear the Loader Address Offset locations before calling
this routine.
On exit, the Transfer Address Flag is zero if no
transfer address was found. This flag is non-zero if a transfer
address record was encountered in the binary file, and the Transfer
Address locations contain the last transfer address encountered.
The disk file is closed on exit. If a disk error is encountered,

-12-

FLEX Advanced Programmer's Guide
an error message is issued and control is returned to
Warmstart Entry Point.

DOS at the

$C033 (SETEXT) Set Extension
On entry, the X-register should contain the address of the FCB into
which the default extension is to be stored if there is not an
extension already in the FCB. The A-register, on entry, should
contain a numeric code indicating what the default extension is to
be. The numeric codes are described below. If there is already an
extension in the FCB (possibly stored there by a call to GETFIL),
this routine returns to the calling program immediately. If there
is no extension in the FCB, the extension indicated by the numeric
code in the A-register is placed in the FCB File Extension area.
The legal codes are:

1
2
3
4

5 6 -

7 8 9 -

1011-

BIN
TXT
CMO
BAS
SYS
BAK
SCR
OAT
BAC
OIR
PRT
OUT

Any values other than those above are ignored, the routine
returning without storing any extension.
The X register is
preserved in this routine.
$C036 (AODBX) Add B-register to X-register
The content of the B-register is added to the content of the
X-register. This routine is here for compatibility with 6800 FLEX.
$CD39 (OUTDEC) Output Decimal Number
On entry, the X-register contains the address of the most
significant byte of a 16-bit (2 byte), unsigned, binary number.
The B-register, on entry, should contain a space suppression flag.
The number will be printed as a decimal number with leading zeroes
suppressed. If the B-register was non-zero on entry, spaces will
be substituted for the leading zeroes. If the B-register is zero
on entry, printing of the number will start with the first non-zero
digit.
$CD3C (OUTHEX) Output Hexadecimal Number
On entry, the X-register contains the address of a single binary
byte. The byte to which the X-register points is printed as 2
hexadecimal digits. The B and X registers are preserved.

-13-

FLEX Advanced Programmer's Guide
$CD3F (RPTERR) Report Error
On entry to this routine, the X-register contains the address of a
File Control Block in which the Error Status Byte is non-zero. The
error code in the FCB is stored by this routine in the Error Type
location. A call to the routine RSTRIO is made and location Error
Vector is checked. If this location is zero, the file ERRORS.SYS
is opened for random read. If this location is non-zero, it is
assumed to be an address pointing to an ASCII string (containing
any necessary null pad characters) of a legal File name plus
extension (string should be 11 characters long).
This user
provided file is then opened for random read. The error number is
used in a calculation to determine the record number and offset of
the appropriate error string message in the file.
Each error
message string is 63 characters in length, thus allowing 4 messages
per sector. If the string is found, it is printed on the terminal.
If the string is not found (due to too large of error number being
encountered) or if the error file itself was not located on the
disk, the error numberis reported to the monitor terminal as part
of the message:
DISK ERROR #nnn
Where "nnn" is the error number being reported. A description of
the error numbers is given elsewhere in this document.
$CD42 (GETHEX) Get Hexadecimal Number
This routine gets a hexadecimal number from the Line Buffer •. On
entry, the Line Buffer Pointer must point to the first character of
the number in the Line Buffer. On exit, the carry bit is cleared
if a valid number was found, the B-register is set non-zero, and
the X-register contains the value of the number. The Line Buffer
Pointer is left pointing to the character immediately following the
separator character, unless that character is a carriage return or
End of Line. If the first character examined in the Line Buffer is
a separator character (such as a comma), the carry bit is still
cleared, but the B-register is set to zero indicating that no
actual number was found. In this case, the value returned in the
X-register is zero. If a non-hexadecimal character is found while
processing the number, characters in the Line Buffer are skipped
until a separator character is found, then the routine returns to
the caller with the carry bit set. The number in the Line Buffer
may be of any length, but the value is truncated to between a and
$FFFF, inclusive.
$CD45 (OUTADR) Output Hexaecimal Address
On entry, the X register contains the address of the most
significant byte of a 2 byte hex value. The bytes to which the X
register points are printed as 4 hexadecimal digits.

-14-

FLEX Advanced Programmer's Guide
$CD48 (INDEC) Input Decimal Number
This routine gets an unsigned decimal number from the Line Buffer.
On entry, the Line Buffer Pointer must point to the first character
of the number in the Line Buffer.
On exit, the carry bit is
cleared if a valid number was found, the B-register is set
non-zero, and the X-register contains the binary value of the
number. The Line Buffer Pointer is left pointing as described in
the routine GETHEX. If the first character examined in the buffer
is a separator character (such as a comma), the carry bit is still
cleared, but the B-register is set to zero indicating that no
actual number was found. In this case, the number returned in X is
zero.
The number in the Line Buffer may be of any length but the
result is truncated to 16 bit precision.
$CD4B (DOCMND) Call DOS as a Subroutine
This entry point allows a user-written program to pass a command
string to DOS for processing, and have DOS return control to the
user program on completion of the commands.
The command string
must be placed in the Line Buffer by the user program, and the Line
Buffer Pointer must be pointing to the first character of the
command string. Note that this will destroy any as yet unprocessed
parameters and commands in the Line Buffer. The command string
must terminate with a RETURN character ($D hex). After the
commands have been processed, DOS will return control to the user's
program with the B-register containing any error code received
from the File Management System. The B-register will be zero if no
errors were detected.
Caution: do not use this feature to load
programs which may destroy the user program in memory. An example
of a use of this feature of DOS is that of a program wanting to
save a portion of memory as a binary file on the disk. The program
could build a SAVE command in the Line Buffer with the desired file
name and parameters, and call the DOCMND entry point.
On return,
the memory will have been saved on the disk.
$CD4E (STAT) Check Terminal Input Status
This routine may be called to check the status of the terminal
input device (to see if a character has been typed on the
keyboard). If a character has been hit, the Z condition code will
be cleared on return (a not-equal condition). If no character has
been hit, the Z condition code will be set (an equal condition).
No registers, other than the CC-register, are altered.

-15-

FLEX Advanced Programmer's Guide
USER-WRITTEN COMMANDS
The programmer may write his own commands for DOS. These commands may
be either disk-resident as disk files with a CMD extension, or they may
be memory-resident in either RAM or ROM.
MEMORY-RESIDENT COMMANDS:
A memory-resident command is a program, already in memory, to which DOS
will transfer when the proper command is entered from the keyboard. The
command which invokes the program, and the entry-point of the program,
are stored in a User Command Table created by the programmer in memory.
Each entry in the User Command Table has the following format:
FCC I command I (Name that will invoke the program)
FCB 0
FDB entry address (Thi s is the entry address of the program)
The entire table is ended by a zero byte. For example, the following
table contains the commands DEBUG (entry at $3000) and PUNT (entry at
$3200) :
FCC
FCB
FOB
FCC
FCB
FOB
FCB

'DEBUG '
0
$3000
'PUNT '
0
$3200
0

Command Name
Entry address for DEBUG
Command name
Entry address for PUNT
End of command table

The address of the User Command Table is made known to DOS by storing it
in the User Command Table Address locations (See Memory Map).
The User Command Table is searched before the disk directory, but after
DOS I sown c.ommand table is searched. The DOS command table conta i ns
only the GET and MON commands. Therefore, the user may not define his
own GET and MON commands.
Since the User Command Table is searched before the disk directory, the
programmer may have commands with the same name as those on the disk.
However, in this case, the commands on the disk will never be executed
while the User Command Table is known to DOS. The User Command Table
may be deactivated by clearing the User Command Table Address locations.

-16-

FLEX Advanced Programmer's Guide
DISK-RESIDENT COMMANDS
A disk-resident command is an assembled program, with a transfer
address, which has been saved on the disk with a CMD extension. The
ASMB section of the FLEX User's Guide describes the way to assign a
transfer address to a program being assembled.
Disk commands, when loaded into memory, may reside anywhere in the User
RAM Area; the address is determined at assembly time by using an ORG
statement. Most commands may be assembled to run in the Utility Command
Space (see Memory Map). Most of the commands supplied with FLEX run in
the Utility Command Space. For this reason, the SAVE command cannot be
used to save information which is in the Utility Command Space or System
FCB space as this information would be destroyed when the SAVE command
is loaded.
The SAVE. LOW command is to be used in this case. The
SAVE.LOW command loads into memory at location $100 and allows the
saving of programs in the $C100 region.
The System FCB area is used to load all commands from the disk.
Commands written to run in the Utility Command Space must not overflow
into the System FCB area. Once loaded, the command itself may use the
System FCB area for scratch or as an FCB for its own disk I/O. See the
example in the FMS section.

-17-

FLEX Advanced Programmer's Guide
GENERAL COMMENTS ABOUT COMMANDS
User-written commands are entered by a JMP instruction. On completion,
they_ should return control to DOS by jumping (JMP instruction) to the
Warmstart Entry Point (see Memory Map).
Processing Arguments.
User-written commands are required to process any arguments entered from
the keyboard. The command name and the arguments typed are .in the Line
Buffer area (see Memory Map). The Line Buffer Pointer, on entry to the
command, is pointing to the first character of the first argument, if
one exists. If there are no arguments, the Line Buffer Pointer is
pointing to either an end-of-line character or a carriage return. The
DOS routines NXTCH, GETFIL, and GETHEX should be used by the command for
processing the arguments.
Processing Errors.
If the command, while executing, receives an error status from either
DOS or FMS of 'such a nature that the command must be aborted, the
program should jump to the Warmstart Entry Point of DOS after issuing an
appropriate error message. Similarly, if the command should detect an
error on its own, it should issue a message and return to DOS through
the Warmstart Entry Point.

-18-

FLEX Advanced Programmer's Guide
EXAMPLES OF USING DOS ROUTINES
1. Setting up a file spec in the FCB can be done in the following
manner. This example assumes the Line Buffer Pointer is pointing to the
first character of a file specification, and the desired resulting file
spec should default to a TXT extension.

LDX
JSR
BCS
LM

JSR

#FCB
GETFIL
ERROR
#1
SETEXT

Point to FCB
Get file spec into FCB
Report error if one
Set extension code (TXT)
Set the default extension

The user may now open the file for the desired action, since the file
spec is correctly set up in the FCB. Refer to the FMS examples for
opening files.
2. The following examples demonstrate some simple uses of the basic I/O
functions provided by DOS.
LOA
JSR

#'A
Setup an ASCII A
PUTCHR Call DOS out character

LOX
JSR

#STRING Point to string
PSTRNG Print CR & LF + string

The above simple examples are to show the basic mechanism for calling
and using DOS I/O routines.

-19-

FLEX Advanced Programmer's Guide

-20-

FLEX Advanced Programmer's Guide
THE FILE MANAGEMENT SYSTEM
The File Management System (FMS), forms the communication link between
the DOS and the actual Disk Hardware.
The FMS performs all file
allocation and removal on the disk.
All file space is allocated
dynamically, and the space used by files is immediately reusable upon
that file's deletion. The user of the FMS need not be concerned with
the actual location of a file on the disk, or how many sectors it
requires.
Communication with the FMS is done through File Control Blocks. These
blocks contain the information about a file, such as its name and \'ihat
drive it exi sts on.
All di sk I/O performed through FMS is "one
character at a time" I/O. This means that programs need only send or
request a single character at a time while doing file data transfers.
In effect, the disk looks no different than a computer terminal.
Files
may be opened for either reading or writing. Any number of files may be
opened at anyone time, as long as each one is assigned its own File
Control Block.
The FMS is a command language whose commands are represented by various
numbers called Function Codes. Each Function Code tells FMS to perform
In
a specific function such as open a file for read, or delete a file.
general, making use of the various functions which the H~S offers, is
quite simple. The index register is made to point to the File Control
Block which is to be used, the Function Code is stored in the first byte
of the File Control Block, and FMS is called as a subroutine (JSR).
At
no time does the user ever have to be concerned with where the file is
being located on the disk, how long it is, or where its directory entry
is located. The FMS does all of this automatically.
Since the file structure of FLEX is a linked structure, and the disk
space is allocated dynamically, it is possible for a file to exist on
the disk in a set of non-contiguous sectors. Normally, if a disk has
just been formatted, a file will use consecutive sectors on the disk.
As files are created and deleted, however, the disk may become
"fragmented". Fragmentation results in the sectors on the disk becoming
out of order physically, even though logically they are still all
sequential. This is a characteristic of "linked list" structures and
dynamic file allocation methods. The user need not be concerned with
this fragmentation, but should be aware of the fact that files may exist
whose sectors seem to be spattered allover the disk. The only result
of fragmentation is the slowing down of file read times, because of the
increased number of head seeks necessary while reading the file.

-21-

FLEX. Advanced Programmer's Gui de
THE FILE CONTROL BLOCK (FCB)
TheFCB is the heart of the FLEX File Management System (FMS).
An FCB
is a 320 byte long block of RAM, in the user's program area, which is
used by programs to communicate with FMS. A separate FCB is needed for
each open fi 1e. After a fi 1e has been closed, the FCB may be re-used to
open another file or to perform some other disk function such as Delete
or Rename. An FCB may be placed anywhere in the user's program area
(except page zero) that the programmer wishes. The memory reserved for
use as an FCB need not be preset or initialized in any way. Only the
parameters necessary to perform the function need be stored in the FCB;
the File Management System will initialize those areas of the FCB needed
for its use.
In the following description of an FCB, the byte numbers are relative to
the beginning of the FCB; i.e. byte 0 is the first byte of the FCB.

DESCRIPTION OF AN FCB
Byte 0

Function Code

The desired function code must be stored in this byte by the user
before calling FMS to process the FCB. See the section describing
FMS Function Codes.
Byte 1

Error Status Byte

If an error was detected during the processing of a function, FMS
stores the error number in this byte and returns to the user with
the CPU Z-Condition Code bit clear, i.e. a non-zero condition
exists. This may be tested by the BEQ or BNE instruction.
Byte 2 Activity Status
This byte is set by FMS to a "1" if the file is open for read, or
"2" if the file is open for writing. This byte is checked by
several FMS function processors to determine if the requested
operation is legal. A Status Error is returned for illegal
operations.
The next 12 bytes (3-14) comprise the "File Specification" of the file
being referenced by the FCB.
A "File Specification" consists of a
drive number, file name, and file extension. Some of the FMS functions
do not require the file name or extension. See the documentation of the
individual function codes for details.
Byte 3

Drive Number

This is the hardware drive number whose diskette contains the file
bei ng referenced. It shoul d be binary 0 to 3.

-22-

FLEX Advanced Programmer's Guide
The next 24 bytes (4-27) comprise the "Directory Information" portion of
the FCB. This is the exact same information which is contained in the
diskette directory entry for the file being referenced.
Bytes 4-11 File Name
This is the name of the file being referenced. The name must start
with a letter and contain only letters, digits, hyphens, and/or
underscores. If the name is less than 8 characters long, the
remaining bytes must be zero. The name should be left adjusted in
its field.
Bytes 12-14 Extension
This is the extension of the file name for the file being
referenced. It must start with a letter and contain only letters,
digits, hyphens, and/or underscores. If the extension is less than
3 characters long, the remaining bytes must be zero. The extension
should be left adjusted. Files with null extensions should not be
created.
Byte 15 File Attributes
At present, only the most significant 4 bits are defined in this
byte. These bits are used for the protection status bits and are
assigned as follows:
BIT
BIT
BIT
BIT

7
6
5
4

=
=
=
=

Write Protect
Delete Protect
Read Protect
Catalog Protect

Setting these bits to 1 will activate the appropriate protection
status. All undefined bits of this byte should remain O!
Byte 16

Reserved for future system use

Bytes 17-18

Starting disk address of the file

These two bytes contain the hardware track and sector numbers,
respectively, of the first sector of the file.
Bytes 19-20 Ending disk address of the file
These two byes contain the hardware track and
respectively, of the last sector of the file.
Bytes 21-22
This

sector numbers,

File Size
is a 16-bit number indicating the number of sectors in the

fil e.

-23-

FLEX Advanced Programmer's Guide
Byte 23 File Sector Map Indicator
If this byte is non-zero (usually $02), the file has been created
as a random access file and contains a File Sector Map. See the
description of Random Files for details.
Byte 24 Reserved for future system use
Bytes 25-27 File Creation Date
These three bytes contain the binary date of the files creation.
The first byte is the month, the second is the day, and the third
is. the year (only the tens and ones digits).
Bytes 28-29

FCB List Pointer

All FCBs which are open for reading or writing are chained
together. These two bytes contain the memory address of the FCB
List Pointer bytes of the next FCB in the chain. These bytes are
zero if this FCB is the last FCB in the chain. The first FCB in
the chain is pointed to by the FCB Base Pointer. (See Global
Variables).
Bytes 30-31

Current Position

These bytes contain the hardware track and sector numbers,
respectively, of the sector currently in the sector buffer portion
of the FCB. If the file is being written, the sector to which
these bytes point has not yet been written to the diskette; it is
still in the buffer.
Bytes 32-33

Current Record Number

These bytes contain the current logical Record Number of the sector
in the FCB buffer.
Byte 34

Data Index

This byte contains the address of the next data byte to be fetched
from (if reading) or stored into (if writing) the sector buffer.
This address is relative to the beginning of the sector, and is
advanced automatically by the Read/Write Next Byte function.
The
user program has no need to manipulate this byte.
Byte 35

Random Index

This byte is used in conjuction with the Get Random Byte From
Sector function to read a specific byte from the sector buffer
without having to sequentially skip over any intervening bytes.
The address of the desired byte, relative to the beginning of the
sector, is stored in Random Index by the user, and the Get Random
Byte From Sector function is issued to FMS.
The specified data
byte will be returned in the A-register. A value less than 4 will

-24-

FLEX Advanced Programmer's Guide
access one of the linkage bytes in the sector.
an index value of 4.

User data starts at

Bytes 36-46 Name Work Buffer
These bytes are used internally by FMS as temporary storage for a
file name. These locations are not for use by a user program.
Bytes 47-49 Current Directory Address
If the FCB is being used to process directory information with the
Get/Put Information Record functions, these three bytes contain the
track number, sector number, and starting data index of the
directory entry whose content is in the Directory Information
portion of the FCB. The values in these three bytes are updated
automatically by the Get Information Record function.
Bytes 50-52

First Deleted Directory Pointer

These bytes are used internally by Ft~S when 1ooki ng for a free
entry in the directory to which to assign the name of a new file.
Bytes 53-63

Scratch Bytes

These are the bytes into which the user stores the new name and
extension of a file being renamed. The new name is formatted the
same as described above under File Name and File Extension.
Byte 59

Space Compression Flag

If a file is open for read or write, this byte indicates if space
compression is being performed. A value of zero indicates that
space compression is to be done when reading or writing the data.
This is the value that is stored by the Open for Read and Open for
Write functions.
A value of $FF indicates that no space
compression is to be done. This value is what the user must store
in this byte, after opening the file, if space compression is not
desired. (Such as for binary files). A positive non-zero value in
this byte indicates that space compression is currently in
progress; the value being a count of the number of spaces processed
thus far. (Note that although this byte overlaps the Scratch Bytes
described above, there is no conflict since the Space Compression
Flag is used only when a file is open, and the Scratch Bytes are
used only by Rename, which requires that the file be closed). In
general, this byte should be 0 while working with text type files,
and $FF for binary files.
Bytes 64-319 Sector Buffer
These bytes contain the data contained in the sector being read or
written. The first four bytes of the sector are used by the
system. The remaining 252 are used for data storage.

-25-

FLEX Advanced Programmer's Guide
FILE MANAGEMENT SYSTEM - Entry Points
$0400 - FMS Initialization
This entry point is used by the DOS portion of FLEX to initialize
the File Management System after a coldstart. There should be no
need for a user-written program to use this entry point. Executing
an
FMS Initialization at the wrong time may result in the
destruction of data files, necessitating a re-initialization of the
diskette.
$0403 - FMS Close
This entry point is used by the DOS portion of FLEX at the end of
each command line to close any files left open by the command
processor. User-written programs may also use this entry point to
close all open files; however, if an error is detected in trying to
close a file, any remaining files will not be closed. Thus the
programmer is cautioned against using this routine as a substitute
for the good programming practice of closing files individually.
There are no arguments to this routine. It is entered by a JSR
instruction as though it were a subroutine. On exit, the CPU
Z-Condition code is set if no error was detected (i.e.
a "zero"
condition exists).
If an error was detected, the CPU Z-Condition
code bit is clear and the X-register contains the address of the
FCB causing the error.
$0406 - FMS Call
This entry point is used for all other calls to the File Management
System. A function code is stored in the Function Code byte of the
FCB, the address of the FCB is put in the X-register, and this
entry point is called by a JSR instruction. The function codes are
documented elsewhere in this document. On exit from this entry
point, the CPU Z-Condition code bit is set if no error was detected
in processing the function. This bit may be tested with a BEQ or
BNE instruction. If an error was detected, the CPU Z-Condition
code bit is cleared and the Error Status byte in the FCB contains
the error number. Under all circumstances, the address of the FCB
is still in the X-register on exit from this entry point. Some of
the functions require additional parameters in the A and/or
B-registers.
See the documentation of the Function codes for
details. The B,X,Y and U registers are always preserved with a call
to FMS.

-26-

FLEX Advanced Programmer's Guide
GLOBAL VARIABLES
This section describes those variables within the File Management System
which may be of interest to the programmer. Any other locations in the
FMS area should not be used for data storage by user programs.
$0409 - $040A

FCB Base Pointer

These locations contain the address of the FCB List Pointer bytes
of the first FCB in the chain of open files. The address in these
locations is managed by FMS and the programmer should not store any
values in these locations. A user program may, however, want to
chain through the FCBs of the open files for some reason, and the
address stored in these locations is the proper starting point.
Remember that the address is that of the FCB List Pointer locations
in the FCB, not the first word of the FCB.
A value of zero in
these locations indicates that there are no open files.
$040B - $040C

Current FCB Address

These locations contain the address of the last FCB processed by
the File Management System. The address is that of the first word
of the FCB.
$0435

Verify F1 ag

A non-zero
each sector
zero value
performed.

value in
written for
indicates
The default

this location indicates that FMS will check
errors immediately after writing it.
A
that no error checking on writes is to be
value is "non-zero".

-27-

FLEX Advanced Programmer's Guide
FMS FUNCTION CODES
The FLEX File Management System is utilized by the user through function
codes.
The proper function code number is placed, by the user, in the
Function Code byte of the File Control Block (FCB) before calling FMS
(Byte 0).
FMS should be called by a JSR to the "FMS Call" entry. On
entry to FMS, the X-register should contain the address of the FCB.
On
exit from FMS, the CPU Z-Condition code bit will be clear if an error
was detected while processing the function. This bit may be tested by
the BNE and BEQ instructions. Note: In the following examples, the line
"JSR FMS" is referencing the FMS Call entry at $D406.
Function 0 - Read/Write Next Byte/Character
If the fi le is open for readi ng, the next byte is fetched from the
file and returned to the calling program in the A-register. If the
file is open for writing, the content of the A-register on entry is
placed in the buffer as the next byte to be written to the file.
The Compression Mode Flag must contain the proper value for
automatic
space compression to take place, if desired (see
On
Description of the FCB, Compression Mode Flag for details).
exit, this function code remains unchanged in the Function Code
byte of the FCB; thus, consecutive read/writes may be performed
When
without having to repeatedly store the function code.
reading, an End-of-File error is returned when all data in the file
has been read.
When the curr,ent sector being read is empty, the
next sector in the file is prepared for processing automatically,
without any action being required of the user. Similarly, when
writing, full sectors are automatically written to the disk without
user intervention.
Example:
If reading LDX #FCB
JSR FMS
BNE ERROR
The character

Point to the FCB
Call FMS
Check for error
read is now in A.

If writing LDA CHAR
LDX #FCB
JSR FMS
BNE ERROR
The character

Get the character
Point to the FCB
Call FMS
Check for errors
in A has been written

-28-

FLEX Advanced Programmer's Guide
Function 1 - Open for Read
The file specified in the FCB is opened for read-only access.
If
the file cannot be found, an error is returned. The only parts of
the FCB which must be preset by the programmer before issuing this
function are the file specification parts (drive number, file name,
and file extension) and the function code. The remaining parts of
the FCB will be initialized by the Open process. The Open process
sets the File Compression Mode Flag to zero, indicating a text
file.
If the file is binary, the programmer should set the File
Compression Mode Flag to $FF, after opening the file, to disable
the space compression feature. On exit from FMS, after opening a
file, the function code in the FCB is automatically set to zero
(Read/Write Next Byte Function) in anticipation of I/O on the file.
Example:
LOX #FCB
Point to the FCB
[ Set up file spec in FCB ]
LOA #1
Set open function code
STA O,X
Store in FCB
JSR FMS
Call FMS
BNE ERROR Check for errors
The file is now open for text reading
To set for binary - continue with the following
LOA #$FF
Set FF for sup. flag
STA 59,X
Store in suppression flag
Function 2 - Open for Write
This is the same as Function 1, Open for Read, except that the file
must not already exist in the diskette directory, and it is opened
for write-only· access.
A file opened for write may not be read
unless it is first closed and then re-opened for read-only.
The
space compression flag should be treated the same as described in
"Open for Read". A file is normally opened as a sequential file
but may be created as a random file by setting the FCB location
File Sector Map byte non-zero immediately following an open for
write operation.
Refer to the section on Random Files for more
details. The file will be created on the drive specified unless the
drive spec is $FF in which case the file will be created on the
first drive found to be ready.
Example:
LOX #FCB
Point to FCB
[ Setup file spec in FCB ]
LOA #2
Setup open for write code
STA O,X
Store in FCB
JSR FMS·
Call FMS
BNE ERROR Check for errors
File is now open for text write.
For binary write, follow example in Read open.

-29-

FLEX Advanced Programmer's Guide
Function 3 - Open for Update
This function opens the file for both read and write. The file
must not be open and must exist on the specified drive.
If the
drive spec is $FF, all drives will be searched. Once the file has
been opened for update, four operations may be performed on it; 1.
sequential read, 2. random read, 3. random write, and 4. close
file. Note that it is not possible to do sequential writes to a
file open for update.
This implies that it is not possible to
increase the size of a file which is open for update.

Function 4 - Close File
If the file was opened for reading, a close merely removes the FCB
from the chain of open files. If the file was opened for writing,
any data remaining in the buffer is first written to the disk,
padding with zeroes if necessary, to fill out the sector. If a
file was opened for writing but never written upon, the name of the.
file is removed from the diskette directory since the file contains
no data.
Example:
LOX #FCB
LOA #4
STA O,X
JSR FMS
BNE ERROR
File has now

Point to FCB
Setup close code
Store in FCB
Call FMS
Check for errors
been closed~

Function 5 - Rewind File
Only files which have been opened for read may be rewound. On exit
from FMS, the function code in the FCB is set to zero, anticipating
a rea"d ope rat i on on the fi 1e. If .the programmer wi shes to rewi nd a
file which is open for writing so that it may now be read, the
file must first be closed, then re-opened for reading.
Example:
Assuming the file is open for read:
LOX #FCB
Point to FCB
LOA #5
Setup rewind code
STA O,X
Store in FCB
JSR FMS
Call FMS
BNE ERROR Check for errors
File is now rewound & ready for read

-30-

FLEX Advanced Programmer's Guide
Function 6 - Open Directory
This function opens the directory on the diskette for access by a
program. The FCB used for this function must not already be open
for use by a file. On entry, the only information which must be
preset in the FCB is the drive number; no file name is required.
The directory entries are read by using the Get Information Record
function. The Put Information Record function is used to write a
directory entry. The normal Read/Write Next Byte function will not
function correctly on an FCB which is opened for directory access.
It is not necessary to close an FCB which has been opened for
directory access after the directory manipulation is finished. The
user should normally not need to access the directory.

Function 7 - Get Information Record
This function should only be issued on an FCB which has been opened
\'1ith the Open Directory funcion. Each time the Get Information
Record function is issued, the next directory entry will be loaded
into the Directory Information area of the FeB (see Description of
the FCB for details of the format of a directory entry). All
directory entries, including deleted and unused entries are read
when using this function. After an entry has been read, the FCB is
said to "poi nt" to the di rectory entry just read; the Current
Directory Address bytes in the FCB refer to the entry just read.
An End-of-File error ;s returned when the end of the directory is
reached.
Example:
To get the 3rd directory entry LDX #FCB
Point to FCB
LOA DRIVE Get the drive number
STA 3,X
Store in the FeB
LOA #6
Setup open dir code
STA O,X
Store in FCB
JSR FMS
Call FMS
BNE ERROR Check for errors
LOB #3
Set counter to 3
LOOP LDA #7
Setup get rec code
STA O,X
Store in FCB
JSR FMS
Call FMS
BNE ERROR Check for errors
OECB
Decrement the counter
BNE LOOP
Repeat til finished
The 3rd entry is now in the FCB

-31-

FLEX Advanced Programmer1s Guide
Function 8 - Put Information Record
This function should only be issued on an FCB which has been opened
with the Open Directory function. The directory information is
copied from the Directory Information portion of the FCB into the
directory entry to which the FCB currently points. The directory
sector just updated is then re-written automatically on the
diskette to ensure that the directory is up-to-date. A user
program should normally never have to write into a directory.
Careless use of this function can lead to the destruction of data
files, necessitating a re-initialization of the diskette.

Function 9 - Read Single Sector
This function is a low-level interface directly to the disk driver
which permits the reading of a single sector, to which the Current
Position bytes of the FCB point, into the Sector Bufffer· area of
the FCB. This function is normally used internally within FLEX and
a user program should never need to use it.
The Read/Write Next
Byte function should be used instead, whenever possible. Extreme
care should be taken when using this function since it does not
conform to the usual conventions to which most of the other FLEX
functions adhere.
Example:
LDX #FCB
LDA TRACK
STA 30,X
LOA SECTOR
STA 31,X
LOA #9
STA O,X
JSR FMS
BNE ERROR
The sector is

Point to FCB
Get track number
Set current track
Get sector number
Set current sector
Setup function code
Store in FCB
Call FMS
Check for errors
now in the FCB

Function 10 ($OA hex) - Write Single Sector
This function, like the Read Single Sector function, is a low-level
interface directly to the disk driver which permits the writing of
As such ,it requires extreme care in its use.
a single sector.
This function is normally used internally by FLEX, and a user
program should never need to use it. The Read/Write Next Byte
function should be used whenever possible.
Careless use of the
Write Single Sector Function may result in the destruction of data,
necessitating the re-initialization of the diskette.
The disk
address being written is taken from the Current Position bytes of
the FCB; the data is taken from the FCB Sector Buffer.
This
function honors the Verify Flag (see Global Variables section for a
description of the Verify Flag), and will check the sector after
writing it if directed to do so by the Verify Flag.

-32-

FLEX Advanced Programmer's Guide
Function 11 ($OB hex) - Reserved for future system use
Function 12 ($OC hex) - Delete File
This function deletes the file whose specification is in the FCB
(drive numbers, file name, and extension). The sectors used by the
file are released to the system for re-use. The file should not be
open when this function is issued. The file specification in the
FCB is altered during the delete process.
Example:
LDX #FCB
[ setup file
LDA #12
STA O,X
JSR FMS
BNE ERROR
File has now

Point to FCB
spec in FCB ]
Setup function code
Store in FCB
Call FMS
Check errors
been deleted

Function 13 ($OD hex) - Rename File
On entry, the file must not be open, the old name must be in the
File Specification area of the FCB, and the new name and extension
must be in the Scratch Bytes area of the FCB. The file whose
specification is in the FCB is renamed to the name and extension
stored in the FCB Scratch Bytes area. Both the new name and the
new extension must be specified; neither the name nor the extension
can be defaulted.
Example:
LDX #FCB
Point to FCB
[ setup both file specs in FCB ]
LDA #13
Setup function code
STA O,X
Store in FCB
JSR FMS
Call FMS
BNE ERROR Check for errors
File has been renamed
Function 14 ($OE hex) - Reserved for future system use.

-33-

FLEX Advanced Programmer's Guide
Function 15 ($OF hex) - Next Sequential Sector
On entry the file should be open for either reading or writing (not
update). If the file is open for reading, this function code will
cause all of the remaining (yet unread) data bytes in the current
sector to be skipped, and the data pointer will be. positioned at
the first data byte of the next sequential sector of the file. If
the file is open for write, this operation will cause the remainder
of the current sector to be zero filled and written out to the
disk. The next character written to that file will be placed in the
first available data location in the next sequential sector. It
should be noted that all calls to this function code will be
ignored un]essat least one byte of data has either been written or
read from the current sector.
Function 16 ($10 hex) - Open System Information Record
On entry, only the drive number need be specified in the FCB; there
is no file name associated with this function. The FCB must not be
open for use by a file.
This function accesses the System
Information Record for the diskette whose drive number is in the
FCB. There are no separate functions for reading or changing this
sector. All references to the data contained in the System
Information Record must be made by manipulating the Sector Buffer
directly.
This function is used internally within FLEX; there
should be no need for a user-written program to change the System
Information ·Record. Doing so may result in the destruction of
data, necessitating the re-initialization of the diskette.
There
is no need to close the FCB when finished.

Function 17 ($11 hex) - Get Random Byte From Sector
On entry, the file should be open for reading or update. Also, the
desired byte's number should be stored in the Random Index byte of
the FCB. This byte number is relative to the beginning of the
sector buffer. On exit, the byte whose number is stored in the
Random Index is returned to the calling program in the A-register.
The Random Index should not be less than 4 since there is no user
data in the first four bytes of the sector.
Example:
To read the 54th data byte of the current sector .
Point to the FCB
LDX #FCB
LDA #54+4 Set to item + 4
STA 35,X
Put it in random index
Setup function code
LDA #17
STA O,X
Store in FCB
JSR FMS
Call FMS
BNE ERROR Check for errors
Character is now in acc. A

-34-

FLEX Advanced Programmer's Guide
Function 18 ($12 hex) - Put Random Byte in Sector
The file must be open for update. This function is similar to Get
Random Byte except the character in the A accumulator is written
into the sector at the data location specified by Random Index of
the FCB. The Random Index should not be less than 4 since only
system data resides in the first 4 bytes of the sector.
Example:
To write into
LOX #FCB
LOA #54+4
STA 35,X
LOA #18
STA O,X
LOA CHAR
JSR FMS
BNE ERROR
Character has

the 54th data byte of the current sectorPoint to the FCB
Set to item + 4
Put it in Random Index
Setup Function Code
Store in FCB
Get character to be written
Call FMS
Check for errors
been written

Function 19 ($13 hex) - Reserved for future system use
Function 20 ($14 hex) - Find Next Drive
This function is used to find the next online drive which is in the
"ready" state. Due to hardware limitations, the minifloppy version
of FLEX performs thi s command di fferently than the full si ze floppy
version. The functioning of the full size floppy version is as
follows. If the drive number in the FCB is hex FF, the search for
drives will start with drive O. If the drive number is 0, 1, or 2,
the search will start with drive 1, 2, or 3 respectively. If a
ready drive is found, its drive number will be returned in the
drive number byte of the FCB and the carry bit will be cleared. If
no ready drive is found, the carry bit will be set and error #16
(Drives Not Ready) will be set.
The minifloppy version functions as follows.
If called with a
Drive Number in the FCB of hex FF, the function will return with 0
as the drive number in the FCB. If called with a 0, it will return
with the drive number set to 1. In both cases the carry is cleared
on return. If called with a drive number of 1 or higher, the drive
number is left unchanged, the carry bit is set on return and error
#16 (Drives Not Ready) ;s set.

-35-

FLEX Advanced Programmer's Guide
Function 21 ($15 hex) - Position to Record N
Thi sis one of the 2 function codes provi ded for random fi 1e
accessing by sector. The desired record number to be accessed
should be stored in the FCB location Current Record Number (a 16
bit binary value). The file must be open for read or update before
using this function code. The first data record of a file is
record number one. Positioning to record 0 will read in the first
sector of the File Sector Map.
After a successful Position
operation, the first character read with a sequential read will be
the first data byte of the specified record. An attempt to
position to a nonexistent record will cause an error. For more
information on random files, see the section titled 'Random Files'.
Example:
To position to record #6 LOX #FCB
Point to the FCB
LOA #6
Set position
STA 33,X
Put in FCB
CLR 32,X
Set M.S.B to 0
LOA #21
Setup Function Code
STA O,X
Store in FCB
JSR FMS
Call FMS
BNE ERROR Check for errors
Record ready to be read

Function 22 ($16 hex) - Backup One Record
This is also used for random file accessing. This function takes
A
the Current Record .Number in the FCB and decrements it by one.
Position to the new record is performed. This has the effect of
back spacing one full record. For example, if the Current Record
Number is 16 and the Backup One Record funct ion is performed, the
file would be positioned to read the first byte of record #15. The
file must be open for read or update before this function may be
used. See 'Random Files' section for more details.

-36-

FLEX Advanced Programmer's Guide
RANDO~1

FILES

FLEX version 9.0 supports random files.
The random access technique
allows access by record number of a file and can reach any specified
sector in a file, no matter how large it is, in a maximum of two disk
reads. With a small calculation using the number of data bytes in a
sector (252), the user may also easily reach the Nth character of a file
using the same mechanism.
Not all files may be accessed in a random manner. It is necessary to
create the file as a random file.
The default creation mode is
sequential and is what all of the standard FLEX Utilities work with.
The only random file in a standard FLEX system is the ERRORS.SYS file.
FLEX uses a random access technique when reporting error messages.
A
file which has been created as a random access file may read either
randomly or sequentially. A sequential file may only be read
sequentially.
To create a random file, the normal procedure for opening a file for
write should be used. Immediately following a successful open, set the
File Sector Map location of the FCB to any non-zero value and proceed
with the file's creation. It only makes sense to create text type files
in the random mode. As the file is built, the system creates a File
Sector Map.
This File Sector Map (FSM) is a map or directory which
tells the system where each record (sector) of the file is located on
the disk.
The FSM is always two sectors in length and is assigned
record number 0 in the file. This implies that a data file requiring 5
sectors for the data will actually be 7 sectors in length. The user has
no need for the FSM sectors and they are automatically skipped when
opening a file for read. The FMS uses them for the Position and Backup
function code operations.
The directory information of a file states whether or not a file is a
random file. If the File Sector Map byte is non-zero, the file is
random, otherwise it is sequential only. It should be noted that random
files can be Copied from one disk to another without losing its random
properties, but it can not be appended to another file.

-37-

FLEX Advanced Programmer's Guide
FLEX ERROR NUMBERS
1 - ILLEGAL FMS FUNCTION CODE ENCOUNTERED

FMS was called with a function code in the Function Code byte of
the FCB that was too large or illegal.

2 - THE REQUESTED FILE IS IN USE
An Open for Read, Update, Or Write function was issued on an FCB
that is already open.
3 - THE FILE SPECIFIED ALREADY EXISTS
a. An Open for Write was issued on an FCB containing the
specification for a file already existing in the diskette
directory.
b. A Rename function was issued specifying a new name that was the
same as the name of a file already existing in the diskette
directory.
4 - THE SPECIFIED FILE COULD NOT BE FOUND
An Open for Read or Update, a Rename, or a Delete function was
requested on an FCB containing the file specification for a file
which does not exist in the diskette directory.
5 - SYSTH1 DIRECTORY ERROR - REBOOT SYSTEM
Reserved for future system use.
6 - THE SYSTEM DIRECTORY SPACE IS FULL
This error should never occur since the directory space is self
expanding, and can never be filled. Only disk space can be filled
(error #7).
7 - ALL AVAILABLE DISK SPACE HAS BEEN USED
All of the available space on the diskette has been used up by
files. If this error is returned by FMS, the last character sent to
be \,/ritten to a file did not actually get written.
8 - READ PAST END OF FILE
A read operation on a file encountered an end-of-file. All of the
data in the file has been processed. This error will also be
returned when reading a directory with the Get Information Record
function when the end of the directory is reached.
9 - DISK FILE READ ERROR
A checksum error was encountered by the hardware in attempting to
DOS has already attempted to re-read the failing
read a sector.
sector several times, without success, before reporting the error.
This error may also result from illegal track and sector addresses
being put in the FCB.

-38-

FLEX Advanced Programmer's Guide
10 - DISK FILE WRITE ERROR
A checksum error was detected by the hardware in attempting to
write a sector.
DOS has already tried several times, without
success, to re-write the failing sector before reporting the error.
This error may also result from illegal track and sector numbers
being put in the FCB. A write-error status may also be returned if
a read error was detected by DOS in attempting to update the
diskette directory.
11 - THE FILE OR DISK IS WRITE PROTECTED
An attempt was made to write on a diskette which has been
write-protected by use of the write-enable cutout in the diskette
or to a file which has the write protect bit set.
12 - THE FILE IS PROTECTED - FILE NOT DELETED
The file attempted to be deleted has its delete protect bit set and
can not be deleted.
13 - ILLEGAL FILE CONTROL BLOCK SPECIFIED
An attempt was made to access an FCB from the open FCB chain, but
it was not in the chain.
14 - ILLEGAL DISK ADDRESS ENCOUNTERED
Reserved for future system use.
15 - AN ILLEGAL DRIVE NUMBER WAS SPECIFIED
Reserved for future system use.
16 - DRIVES NOT READY
The drive does not have a diskette in it or the door is open. This
message cannot be issued for mini floppys since there is no means
of detecting such a state.
17 - THE FILE IS PROTECTED - ACCESS DENIED
Reserved for future system use.
18 - SYSTEM FILE STATUS ERROR
a. A read or Rewind was attempted on a file which was closed, or
open for write access.
b. A write was attempted on a file which was closed, or open for
read access.
19 - FMS DATA INDEX RANGE ERROR
The Get Random Byte from Sector function was issued with a Random
Byte number greater than 255.
20 - FMS INACTIVE - REBOOT SYSTEM
Reserved for future system use.
21 - ILLEGAL FILE SPECIFICATION
A format error was detected in a file name specification. The name
must begin with a letter and contain only letters, digits, hyphens,
and/or underscores. Similarly with file extensions.
File names
are limited to 8 characters, extensions to 3.

-39-

FLEX Advanced Programmer's Guide
22 -SYSTEM FILE CLOSE ERROR
Res2rved for future system use.
23 - SECTOR MAP OVERFLOW - DISK TOO SEGMENTED
An attempt was made to create a very large random access file on a
disk which is very segmented. All record information could not fit
in the 2 sectors of the File Sector Map. Recreating the file on a
new diskette will solve the problem.
24 - NON-EXISTENT RECORD NUMBER SPECIFIED

A record number larger than the last record number of the file was
specified in a random position access.

25 - RECORD NUMBER MATCH ERROR - FILE DAMAGED
The record located by the FMS random search is not the correct
record. The file is probably damaged.
26 -

COMMAND SYNTAX ERROR - RETYPE COMMAND
The command line just typed has a syntax error.

27 - THAT COMMAND IS NOT ALLOWED WHILE PRINTING

The command just entered is not allowed to operate while the system
printer spooler is activated.
28 - WRONG HARDWARE CONFIGURATION

This error usually implies insufficient memory installed in the
computer for a particular function or trying to use the printer
spooler without the hardware timer board installed.

-40-

FLEX Advanced Programmer's Guide
DISK DRIVERS
The following information is for those users who wish to write their own
disk drivers to interface with some other disk configuration than is
supplied by the vendor. Technical Systems Consultants is not in a
position to write disk drivers for other configurations, nor do they
guarantee the proper functioning of FLEX with user-written drivers.
The disk drivers are the interface routines between FLEX and the
hardware driving the floppy disks themselves. The drivers released with
the FLEX System are designed to interface with the Western Digital 1771
or 1791 Floppy Disk Formatter/Controller chip.
The disk drivers are located in RAM at addresses $DEOO - $DFAO.
All
disk functions are vectored jumps at the beginning of this area. The
disk drivers need not handle retries in case of errors; FLEX will call
them as needed. If an error is detected, the routines should exit with
the disk hardware status in the B-register and the CPU Z-Condition code
bit clear (issue a TST B before returning to accomplish this). FLEX
expects status responses as produced by the Western Digital 1771
Controller.
These statuses must be simulated if some other controller
is uSE;!d. All drivers should return with the X,Y and U registers
unchanged. All routines are enterd with a JSR instruction.
$DEOO - Read
Entry - (X) = FCB Sector Buffer Address
(A) = Track Number
(B) = Sector Number
The sector referenced by the track and sector numbers is to be read
into the Sector Buffer area of the indicated FCB.
$DE03 - Write
Entry - (X) = FCB Sector Buffer Address
(A) = Track Number
(B) = Sector Number
The content of the Sector Buffer area of the indicated FCB is to be
written to the sector referenced by the track and sector numbers.
$DE06 - Verify
Entry - (No parameters)
The sector just written is to be verified to determine if there are
CRC errors.
$DE09 - Restore
Entry - (X) = FCB Address
Exit - CC, NE, & B=$B if write protected
CS, NE, & B=$F if no drive
A Restore Operation (also known as a Seek to Track 00)
performed on the drive whose number is in the FCB.

-41-

is to

FLEX Advanced Programmer's Guide
$DEOC - Drive Select
Entry - (X) = FCB Address
The drive whose number is in the FCB is to be selected.
$DEOF - Check Drive Ready
Entry - (X) = FCB Address
Exit - NE &CS if drive not ready
EQ & CC if drive ready
This routine is setup for FLEX systems where it is possible to
check the drive whose number is in the FCB for a ready status after
selecting that drive and delaying long enough for the drive motor
to come up to speed (approx. 2 seconds). This is not possible in
the minifloppy version due to hardware limitations. In this case,
this routine should not delay and should simply return a drive
ready status if the drive number in the FCB is 0 or 1 or a drive
not ready status for any other drive number.
$DEI2 - Quick Check Drive Ready
This routine is the same as Drive Check Ready except the 2 second
delay is not done. This assumes the drive motor is already up to
speed. For minifloppy versions, there is no difference in the two
and this routine can simply be a jump to the Check Drive Ready
routine.

-42-

FLEX Advanced Programmer's Guide
Diskette Initialization
The NEWOISK command is used to "initialize" a diskette for use by the
FLEX Operating System. The initialization process writes the necessary
track and sector addresses in the sectors of a "soft- sectored" diskette
such as is used by FLEX. In addition, the initialization process links
together all of the sectors on the diskette into a chain of available
sectors.
The first track on the diskette, track 0, is special.
None of the
sectors on track a are available for data files, they are reserved for
use by the FLE X system. The fi rst two sectors conta ina "boot program
which is loaded by the "0" command of the SBUG monitor or by whatever
comparable ROM based bootstrap is in use.
The boot program, once
loaded, then loads FLEX from the diskette. Another sector on track a is
the System Information Record.
This sector contains the track and
sector addresses of the beginning and ending sectors of the chain of
free sectors, those available for data files. The rest of track a is
used for the directory of file names.
II

After initialization, the free tracks on the diskette have a common
format. The first two bytes of each sector contain the track and sector
number of the next sector in the chain. The next two bytes are used to
store the logical record number of the sector in the file. The
remaining 252 bytes are zero. Initially, all record number bytes are
zero. When data is stored in· a file, the two linkage bytes at the
beginning of each sector are modified to point to the next sector in the
file, not the next sector in the free chain. The sectors in the
diskette directory on track a also have linkage bytes similar to those
in the free chain and data files.
A FLEX diskette is not initialized in the strict IBM standard format.
In the standard format, the sectors on the diskette should be phYSically
in the same order as they are logically, i.e. sector 2 should follow
sector 1, 3 follow 2, etc.
On a FLEX diskette, the sectors are
interleaved so that there is time, after having read one sector, to
process the data and request the next sector before it has passed under
the head. If the sectors are physically adjacent, the processing time
must be very short. The interleaving of the sectors allows more time
for processing the data. The phenomena of missing a sector because of
long processing times is called "missing revolutions", and results in
very slow running time for programs. The FLEX format reduces the number
of missed revolutions, thus speeding up programs.

-43-

FLEX Advanced Programmer's Guide
DESCRIPTION OF A DIRECTORY SECTOR
Each sector in the directory portion of a FLEX diskette contains 10
directory entries. Each entry refers to one file on the diskette.
In
each sector, the first four bytes contain the sector linkage information
and the" next 12 bytes are not used. When reading information from the
directory using the FMS Get Information Record function, these 16 bytes
are skipped automatically as each sector is read; the user need not be
concerned with them.
Each entry in the directory contains the exact same information that is
stored in the FCB bytes 4-27. See the description of the File Control
Block (FCB) for more details.
A directory entry which has never been used has a zero in the first byte
of the file name. A directory entry which has been deleted has the
leftmost bit of the name set (i.e. the first byte of the name is
negative) •

DESCRIPTION OF A DATA SECTOR
Every sector on a FLEX diskette (except the two BOOT sectors)
following format:
Bytes 0-1 Link to the next sector
Bytes 2-3 File Logical Record Number
Bytes 4-255 Data

has the

If a file occupies more than one sector, the "link to the next sector"
portion contains the track and sector numbers, respectively, of the next
sector in the fil e. These bytes are zero in the last sector of a fi 1e,
indicating that no more data follows (an "end-of-file" condition). The
user should never manually change the linkage bytes of a sector. These
bytes are automatically managed by FMS. In fact, the user need not be
concerned at all with sector linkage information.

-44-

FLEX Advanced Programmer's Guide
DESCRIPTION OF A BINARY FILE
A FLEX binary file may contain anything as data; all ASCII characters
are allowed. Each binary file is composed of one or more binary
records. There may be more than one binary record in a single sector.
A binary record looks as follows: (byte numbers are relative to the
start of the record, not the beginning of a sector)
Byte 0 Start of record indicator ($02, the ASCII STX)
Byte 1 Most significant byte of the load address
Byte 2 Least significant byte of the load address
Byte 3 Number of data bytes in the record
Byte 4-n The binary data in the record
The load address portion of a binary record contains the address where
the data resided when it was written to the file with the FLEX SAVE
command.
When the file is loaded for execution or use, it will be put
in the same memory areas from which it was SAVED.
A binary file may also contain an optional transfer address record.
This record gives the address in memory of te entry point of a binary
program. The format of a transfer address record is as follows:
Byte 0 Transfer Address Indicator ($16, ASCII ACK)
Byte 1 Most significant byte of the transfer address
Byte 2 Least significant byte of the transfer address
If . a file contains more than one transfer address record (caused by
appending binary files which contain transfer addresses), the last one
encountered by the load process is the one that is used, the others are
ignored.
When reading or writing a binary file through the File Management System
from a user program, the calling program must process the record
indicator bytes and load addresses itself; FLEX does not supply or
process this information for the user.

-45-

FLEX Advanced Programmer's Guide
DESCRIPTION OF A TEXT FILE
A text file (also called an "ASCII file" or "coded file") contains only
printable ASCII characters plus a few special-purpose control
characters. There is no "load address" associated with a FLEX text file
as there is with FLEX binary files. It is the responsibility of the
program which is reading the text file to put the data where it belongs.
The only control character which FLEX recognizes and processes in a FLEX
text file are:
$00 (ASCII CR or RETURN)
This character is used to mark the end of a line or record
fi 1e.

the

$00 (ASCII NULL)
Ignored by FLEX; if encountered in the file, it is not returned to
the calling program.
$18 (ASCII CANCEL)
Ignored by FLEX; if encountered in the file, it is not returned
the calling program.

$09 (ASCII HT or HORIZONTAL TAB)
This isa flag character which indicates that a string of spaces
has been removed from the file as a space-saving measure. The next
byte following the flag character is a count of the number of space
removed (2-127).
The calling program sees neither the flag
character nor the count character. The proper number of spaces are
returned to the user program as successive characters are requested
by the Read Next Byte function. When writing a file, the spaces
are automatically deleted as the user program· sends them to the
File Management System using the Write Next Byte function. The
data compression is, therefore, transparent to the calling program.
(The above discussion is only valid if the file is open for Text
operations. If open for Binary, the compression flag and count get
passed exactly as they appear in the file.)

-46-

FLEX Advanced Programmer's Guide
WRITING UTILITY COMMANDS
Utility commands are best prepared by the use of an assembler. FLEX
reserves a block of memory in which medium size utilities may be placed.
This memory starts at hex location $CI00 and extends through location
$C6FF. The system FCB at location $C840 may also be used in user written
utilities for either FCB space or temporary storage. No actual code
should reside in this FCB space since it would interfere with the
loading of the utility (FLEX is using that FCB while loading utilities).
An example will be given to demonstrate some of the conventions and
techniques which should be used when writing utilities. The example,
which can be found on the following pages, is a simple text file listing
utility. Its syntax is:
LIST,[]
The default extension on the file spec is TXT. The utility will simply
display the contents of a text file on the terminal, line for line.
The following is a section by section description of the LIST utility.
The first section of the source listing is a set of EQUATES which tell
the assembler where the various DOS routines reside in memory. These
equates represent the addresses given in this manual for "User Callable
DOS System Routines".
The next two sections are also equates, the first to the FMS entry
points, and the second references the system FCB. The actual program
finally starts with the ORG statement. In this program, we will make
use of the Utility Command space located at $CI00, therefore, the ORG is
to $C100.
One of the conventions which should be observed when writing DOS
utilities is to always start the program with a BRA instruction.
Following this instruction should be a 'VN FCB I' which defines the
The 1 should of course be set to
version number of the utility.
whatever the actual version number is. In this example, the version
number is 1.
This convention allows the FLEX VERSION Util ity to
correctly identify the version number of a command.
Moving down the program to the label called 'LIST2', the program needs
to retrieve the file specification and get it into the FCB. Pointing X
to the FCB, we can make use of the DOS resident subroutine called
'GETFIL' to automatically parse the file spec, check for errors, and set
the name in the FCB correctly. If all goes well in GETFIL, the carry
should be clear, otherwise there were errors in the file spec and this
fact needs reported. If the carry is set, control is passed to the line
with the label 'LIST9'. At this point, the error message is reported
and control is returned to FLEX.
If the file spec was correct, and the carry was clear after the return
from GETFIL, we want to set a default file name extension of TXT.
The
DOS subroutine named SETEXT will do exactly that. First it is necessary

-47-

FLEX Advanced Programmer's Guide
to put the code for TXT in the A accumulator (the code is 1).
X needs
to be pointing to the FCB which it still is. The 'I I is also put in the
FCB for the future open operation. The call is made to SETEXT and the
file name is now correctly set up in the FCB. Note that no errors can
be generated by a call to SETEXT.
Now that we have the fil e spec, it is necessary to open the requested
file for read. X is still pointing to the FCB so it is not necessary to
reset.
The FMS Function Code for lopen a file for read ' is 1 which was
previously put in the FCB location O. A call to FMS is now made in an
attempt to open the file. Upon return, if the Z-condition code is set,
there were no errors. If there was an error, the 'BNE LIST9 1 will take
us to the code to report the error. This section of code is the desired
way to handle most FMS caused disk errors. The first thing to do is
call the DOS routine RPTERR which will print the disk error message on
the monitor terminal. Next, all open disk files should be closed. This
can be easily accomplished by a call to the FMS close entry (FMSCLS).
Finally, return control back to DOS by jumping to the WARM START entry.
If the file opened successfully, control will be transfered to the line
with the label 'LIST41. At this time it is desirable to fetch
characters one at a time from the file, printing them on the monitor
terminal as they are received. Since line feeds are not stored in text
files (carriage returns mark the end of lines, but the next line will
follow immediately), each carriage return received from the file is not
output as is, but instead a call to the DOS routine 'PCRLF ' is made to
print a carriage return and a line feed. As each character is received
from the file (by a call to FMS at label LIST4), the error status is
checked. If an error does occur, control is transferred to 'LIST6 1•
Since FLEX does not store an End of File character with a file, the only
mechanism for determining the end of a file is by the End of File error
generated by FMS. At 'LIST6 1, the error status is checked to see if it
is 8 (end of file status). If it is not an 8, control is transfered to
the error handling routine described above. If it is an End of File, we
are finished listing the file so it must now be closed.
The FMS
Function Code for closing a file is 4. This is loaded into A and stored
Upon return,
in the FCB. Calling FMS will attempt to close the file.
errors are checked, and if none found, control is transfered back to DOS
by the jump to 'WARMS ' •
This example illustrates many of the methods used when writing
utilities. Many of the DOS and FMS routines were used. The basic idea
of file opening and closing were demonstrated, as well as file I/O. The
methods of dealing with various types of errors were also presented.
Studying this example until it is thoroughly understood will make
writing your own disk commands and disk oriented programs an easy task.

-48-

FLEX Advanced Programmer's Guide

*
* SIMPLE TEXT FILE LIST UTILITY
*
* COPYRIGHT (C) 1979 BY
*
* TECHNICAL SYSTEMS CONSULTANTS, INC.
* DOS EQUATES
C003
C020
C018
C024
C033
C03F

WARMS
GETF IL
PUTCHR
PCRLF
SETEXT
RPTERR

EQU
EQU
EQU
EQU
EQU
EQU

$C003
$C02D
$C018
$C024
$C033
$C03F

DOS WARMS START ENTRY
GET FILE SPECIFICATION
PUT CHARACTER ROUTINE
PRINT CR & LF
SET DEFAULT NAME EXT
REPORT DISK ERROR

* FMS EQUATES
0406 FMS
0403 FMSCLS

EQU
EQU

$0406
$0403

* SYSTEM EQUATES
C840 FCB

EQU

$C840

SYSTEM FCB

* LIST UTILITY STARTS HERE
ORG

$C100

LIST

BRA

LIST2

GET AROUND TEMPS

FCB

VERS ION NUMBER

LIST2

LOX
JSR
BCS
LOA
STA
JSR
JSR
BNE
LOX
JSR
BNE

#FCB
GETFIL
LIST9
#1
O,X
SETEXT
FMS
LIST9
#FCB
FMS
LIST6
#$0
LIST5
PCRLF
LIST4
PUTCHR
LIST4

POINT TO FCB
GET FILE SPEC
ANY ERRORS?
SET UP CODE
SAVE FOR REAO OPEN
SET TXT EXTENSION
CALL FMS - 00 OPEN
CHECK FOR ERROR
POINT TO FCB
CALL FMS - GET CHAR
ERRORS?
IS CHAR A CR?

C100
CIaO 20

C102 01
C103
C106
C109
C10B
CIaO
C10F
C1l2
C115
C1l7
CllA
CllD
CllF
C121
C123
C126
C128
C12B

8E
BO
25
86
A7
BO
BO
26
8E
BO
26
81
26
BO
20
BO
20

C840
C020
34
01
84
C033
0406
28
C840
0406
OE
00
05
C024
EF
C018
EA

LIST4

C~1PA

LIST5

BNE
JSR
BRA
JSR
BRA

-49-

OUTPUT CR & LF
REPEAT
OUTPUT THE CHARACTER
REPEAT SEQUENCE

FLEX Advanced Programmer's Guide
A6
81
26
86
A7
BO
26
7E

01
08
OC
04
84
0406
03
C003

LIST6

C13F BO
C142 SO
C145 7E

C03F
0403
C003

LIST9

C120
C12F
C131
C133
C135
C137
C13A
C13C

LOA
CMPA
BNE
LOA
STA
JSR
BNE
JMP

I,X
#8
LIST9
#4
O,X
FMS
LIST9
WARMS

CLOSE FILE CODE
STORE IN FCB
CALL FMS - CLOSE FILE
ERRORS?
RETURN TO FLEX

JSR
JSR
JMP

RPTERR
FMSCLS
WARMS

REPORT ERROR
CLOSE ALL FILES
RETURN TO FLEX

END

LIST

-50-

GET ERROR STATUS
IS IT EOF ERROR?

FLEX Advanced Programmer's Guide
THE DOS LINK UTILITY
The LINK Utility provided with FLEX is a special purpose command. Its
only function is to inform the "disk boot", which is on track 0, where
the program resides which is to be loaded during the boot operation.
Normally, LINK is used to set the pointer to the DOS program. Since DOS
may reside anywhere on the disk, LINK takes the starting disk address of
the file and stores it in a pointer in the boot sector. When the boot
program is later executed, it simply takes this disk address, and loads
the binary file which resides at that location.
The load process is
terminated upon the receipt of a transfer address record. At this time,
control is transferred to the program just loaded by jumping to the
address specified in the transfer address record. If the 'linked'
program is ever moved on the disk, then it must be re-linked so the boot
knows the new disk address.
LINK may be used in some specialized applications.
One is the
development of custom operating systems. The user may write his own
operating system, link it to the boot, and use it exactly as FLEX is
used now.
It may also be desirable for special disks to boot in
specialized programs rather than the operating system. If this is done,
remember that unless the DOS is loaded during the boot process, there
will not be any disk drivers or File Management System resident in
memory.

-51-

FLEX Advanced Programmer's Guide

-52-

FLEX Advanced Programmer's Guide
PRINTER ROUTINES
There are two printer related programs provided with FLEX. One is the P
Utility, the other is the PRINT.SYS file which is the actual set of
printer drivers (initialize printer and output character).
The P
command source listing is provided on the following pages and should be
self explanatory. Below you will find the requirements of the PRINT.SYS
file. No source listing is provided here since one is given in the
II FLE X User's Manua 111 •
'PRINT.SYS' FILE REQUIREMENTS
The PRINT.SYS file needs to provide the system with three basic printer
routines, one for printer port initialization, one for printer status,
and one for output character to printer routine. The P routine and the
system printer spooler use these routines to communicate with the
printer. A source listing of the provided routines are included in the
IIFLEX User's Manual ll and will not be duplicated here.
The three
routines and their requirements are listed here.
PINIT
PCHK
POUT

($CCCO-CCD7) This routine should initialize the printer port.
No registers need be preserved.
($CCD8-CCE3) This routine should check to see if the printer can
accept another character.
Return Negative CC status if can
accept, Plus if can not. Preserve A, B, X, Y, and U.
($CCE4-CCF7) This routine should output the character in A after
calling PCHK to verify the printer can accept the character.
Preserve B, X, Y, and U.

THE SYSTEM PRINTER SPOOLER
FLEX contains a printer spooler module. It requires the installation of
an interval timer board for operation. Essentially, the spooler is a
multi-tasking system, with the output to printer function being a low
priority task. Any requested disk service will cause the printer task
to temporarily halt until the disk has been used. It should be noted
that the SWI3 CPU vector is adjusted in this task scheduler. The PRINT
command is used to activate the spooler which in turn prints the files
(if any) in the print queue. Exact details of the spooling operation
are not available at this time.

-53-

FLEX Advanced Programmer's Guide

*
*
**
*
*
*
**

"P" UTILITY COMMAND
THE P COMMAND I NITIALIZES A PORT AND
CHANGES THE OUTCH JUMP VECTOR IN FLEX
COPYRIGHT (C) 1979 BY
TECHNICAL SYSTEMS CONSULTANTS, INC.

* EQUATES
C840
CD30
D406
D403
CD06
0004
CC09
CDIE
CD3F
CD03
CC11
CC02
CCCO
CCE4
CDOF
CCFC

EQU
EQU
EQU
EQU
EQU
EQU
EQU
EQU
EQU
EQU
EQU
EQU
EQU
EQU
EQU
EQU

$C840
$CD30
$D406
$D403
$CD06
$4
$CC09
$CDIE
$CD3F
$CD03
$CCll
$CC02
$CCCO
$CCE4
$CDOF
$CCFC

ORG

$ClOO

BRA

BRANCH AROUND TEMPS

FCB

VERS ION NUMBER

LDA
BEQ
LDX
LDB
STB
BRA
LDA
CMPA
BEQ
CMPA
BEQ
CLR

PRI
P12
#FCB
#27
1,X
P3
LSTIRM
#$D
P8
EOL
P8
PAUSE

CHECK SYSTEM PROCESS REG
IS IT BUSY?
POINT TO FCB
SET BUSY ERROR
STUFF IN FCB
GO REPORT ERROR
GET LAST TERMINATOR
IS IT A CR?

FCB
LOAD
FMS
FMSCLS
RENTER
NFER
PAUSE
PSTRNG
RPTERR
WARMS
LSTTRM
EOL
PINIT
POUT
OUTCH
PRI

CIOO
CIOO 20

Cl02 01
Cl03
Cl06
Cl08
CIOB
ClOD
CIOF
C11l
C114
C116
C118
C11B
C11D

B6
27
8E
C6
E7
20
B6
81
27
Bl
27
7F

CCFC
09
C840
lB
01
45
CC11
OD
47
CC02
42
CC09

PI2

- continued -

-54-

IS IT EOL CHARACTER?
DISABLE THE PAUSE FEATURE

FLEX Advanced Programmer's Guide
C120
C123
C125
C127
C12A
C12C
C12E
C131
C133
C135
C138
C13B
C13E
C141
C144

86
81
26
8E
86
A7
BD
26
86
A7
BD
BD
8E
BF
7E

CCE4
39
14
C840
01
84
0406
14
FF
88 3B
CD30
CCCO
CCE4
COlO
CD06

C147
C149
C14B
C14D
C151
C154

A6
81
26
30
BD
20

P2
01
04
09
80 0014
P25
COlE
03

P15

P3
P4

C156 BD
C159 BD
C15C 7E

CD3F
0403
CD03

C15F 30
C163 20

80 0018 P8
EC

C165
C17A
C17B
C19C

22 50 52 49
04
22 50 22 20
04

NOPST
ERSTR

*
*
*
*
C843
C843
C844
C849
C84C

FF
50 52 49 4E
00 00 00
53 59 53

GET 1ST BYTE OF SPACE
IS IT RTS?
IF NOT - THEN LOADED
POINT TO FCB
OPEN FILE FOR READ

LOA
CMPA
BNE
LOX
LOA
STA
JSR
BNE
LOA
STA
JSR
JSR
LOX
STX
JMP

POUT
#$39
P15
#FCB
#1
O,X
FMS
P2
#$FF
59,X
LOAD,
PINIT
#POUT
OUTCH+1
RENTER

LOA
CMPA
BNE
LEAX
JSR
BRA

1,X
#NFER
P3
NOPST,PCR
PSTRNG
P4

GET ERROR CODE
IS IT "NO SUCH FILE"?

JSR
JSR
JMP

RPTERR
FMSCLS
WARMS

REPORT ERROR
CLOSE ALL FILES
RETURN TO FLEX

LEAX
BRA

ERSTR,PCR POINT TO STRING
GO PRINT IT
P25

FCC
FCB
FCC
FCB

'"PRINT.SYS" NOT FOUND'
4
'liP" MUST BE FOLLOWED BY A COMMAND'
4

CALL FMS
CHECK FOR ERRORS
SET FOR BINARY READ
SET COMPRESSION FLAG
CALL FLEX'S LOADER
GO INITIALIZE PORT
GET OUTPUT ADDRESS
STUFF IN FLEX
RETURN TO FLEX

POINT TO MESSAGE
GO PRINT IT

THE FOLLOWING CODE IS LOADED INTO
THE SYSTEM FCB WHEN THE P COMMAND IS
LOADED INTO MEMORY.
IT PRESETS THE FILE NAME IN THE FCB.
ORG

$C843

FCB
FCC
FCB
FCC

$FF
'PRINT'
0,0,0
'SYS'

END

-55-

FLEX Advanced Programmer's Guide

-56-

FLEX Advanced Programmer's Guide
INTERRUPTS IN FLEX
FLEX makes extensive use of interrupts during printer spooling. Anytime
there are files in the PRINT Queue (as a result of using the PRINT
command) the timer board (MP-T in I/O slot #4) is activated. This board
is initialized to output interrupts every 10 milliseconds.
These are
IRQ type interrupts and FLEX sets the IRQ vector to poi nt to its IRQ
routine. When the PRINT Queue is empty, the timer is shut off and no
interrupts are generated. The SWI3 instruction is also used quite
extensively in FLEX. The SWI3 vector in RAM is set by FLEX to point to
its SWI3 routine. Because of the SWI3 and IRQ use, the MON command will
not permit leaving FLEX while there is a file in the PRINT queue.
All FLEX utilities, the Editor, the Assembler, the Text Processor, and
BASIC are interruptable programs •. When writing your own programs, if
they are to be used while printing with the PRINT command (files in the
print queue), they should be written to be interruptable as well. At no
time should the IRQ or SWI3 vectors be changed in a utility which is to
be run while printing. In general, good programming practice will yield
interruptable programs.

SYSTEM MEMORY MAP
The following memory map shows the location of user RAM and several
major sections of the FLEX operating system. All addresses are in.
hexadecimal.
ADDRESS
0000 - BFFF
COOO
C080
ClOO
C700
C840
C980
CCOO
D400
DEOO

C07F
GOFF
C6FF
C83F
C97F
CBFF
D3FF
DDFF
DFFF

DESCRIPTION
User RAM (Some of the lower end of this area is used
by certain util ities such as NEWDISK.)
Stack Area (SP is initialized to C07F)
Input Buffer
Utility Command Area
Scheduler & Printer Spooler
System FCB
System Files Area
DOS
FMS
Disk Drivers

-57-

Source Exif Data:

File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.3
Linearized                      : No
XMP Toolkit                     : Adobe XMP Core 4.2.1-c043 52.372728, 2009/01/18-15:56:37
Create Date                     : 2014:07:14 15:22:18-08:00
Modify Date                     : 2014:07:14 14:45:02-07:00
Metadata Date                   : 2014:07:14 14:45:02-07:00
Producer                        : Adobe Acrobat 9.55 Paper Capture Plug-in
Format                          : application/pdf
Document ID                     : uuid:6ec0a3e9-aacf-e844-ada4-31e3bd5fd113
Instance ID                     : uuid:caf2636e-fb4f-4246-b931-b44f4b4cc7aa
Page Layout                     : SinglePage
Page Mode                       : UseNone
Page Count                      : 227

EXIF Metadata provided by EXIF.tools

Gimix_6809_Flex_V4 Gimix 6809 Flex V4

Gimix_6809_Flex_V4 Gimix_6809_Flex_V4

Navigation menu

Versions of this User Manual:

Views

Navigation