VAX 11 KS500 OBJECT CONVERSION UTILITY USER'S MANUAL
====================================================
D.J.HONEY SOFTWARE SCIENCED LTD, APRIL 1982
========= =================================
CONTENTS
========
1 INTRODUCTION
2 OPERATION
3 DEFINING PROCESS AND CHANNEL RECORDS
4 KS500 ABSOLUTE FILE FORMAT
5 ERROR MESSAGES
Command Errors
Input File Errros
Output File(s) Errors
Miscellaneous Errors
1 INTRODUCTION
============
This document describes the object conversion utility KSABS which
runs on the VAX series of computers. KSABS converts absolute files
produed by the BSO link loader MLINK into standard KS500 absolute
format. It also provides a dump facility for listing the absolute
file as an octal dump. KSABS provides options for prefixing the
KS500 absolute file with a bank switch record, and defining
process and/or channel records to be appended to the file.
2 OPERATION
=========
The object conversion utility is run under VMS by entering a
command of the form:
KSABS / / ... /
where is a valid VMS file specification of a file
produced by the BSO link loader in BSO ROB format. A default file
type of ".ABS" is assumed if a file type is not specified.
KSABS provides a number of options as listed below. The options may
be abbreviated providing that the short form unambiguously indicates
a unique option. For example, the option /NO_OUPUT may be entered as
/NO_O, but not as /NO_ since this would be ambiguous with /NO_DUMP,
/NO_BANK etc. Spaces and tabs may be freely inserted between any
of the slashes '/' and the option names, around '=' signs, and
between options. Spaces or tabs cannot be inserted within option
names or within filenames.
KSABS Options, (D) means selected by default
/NO_OUTPUT Don't produce a KS500 absolute file.
/OUTPUT (D) Produce a KS500 absolute file using
the default file of
.KAB.
/OUTPUT= Produce a KS500 absolute file using
the specified filename.
/NO_DUMP (D) Don't produce an octal dump.
/DUMP Produce an octal dump using the default
file of .DMP.
/DUMP= Produce an octal dump to the file
specified by .
/NO_BANK (D) Don't prefix the KS500 absolute file
with a bank switch record.
/BANK= Prefix the KS500 absolute file with a
bank switch record containing the
bank code specified by the octal
number .
/NO_PROCESS (D) Don't append any process records to
the KS500 absolute file.
/PROCESS= Append a process record to the KS500
absolute file for the process called
. The level head address is
obtained from the input file as
described in section 3.
/NO_CHANNEL (D) Don't append any channel records to
the KS500 absolute file.
/CHANNEL= Append a channel record to the KS500
absolute file for the channel called
. The channel address is
obtained from the input file as
described in section 3.
3 DEFINING PROCESS AND CHANNEL RECORDS
====================================
The cross assembler KS500ASS implements the directives MAIN and
CHAN as being equivalent to the NTRY directive, i.e. it defines
a global symbol. This is because the BSO link loader MLINK does
not know about processes or channels. The KSABS utility provides
means by which the process and/or channel records may be reconstructed
in the KS500 absolute file.
The /PROCESS and /CHANNEL options specify the name of a global symbol
to be used as the process or channel name. The symbol value is
resolved by reading it's definition from the ROB format absolute
file produced by the BSO link loader MLINK. The user should ensure
that the command "PASS GLOBALS" or "PASS ALL" is given to the link
loader before producing the ROB absolute file. If this is not done,
KSABS will not be able to define any process or channel addresses
and an error will be typed. (See section 5)
The technique is simple summarised:
(1) Make sure each process and/or channel has been made global
by an NTRY, MAIN or CHAN directive in the KS500 assembler
program.
(2) Submit the relocatable files to the link loader MLINK in
the normal way.
(3) Make sure that the global symbols are passed to the ROB
format absolute file by entering the command "PASS GLOBALS".
(4) Specify the process and/or channel names using the /PROCESS
and/or /CHANNEL options to the KSABS object conversion utility.
4 KS500 ABSOLUTE FILE FORMAT
==========================
The KS500 absolute file is written in standard KS500 absolute
format using variable length records. Each record contains one
of four types of data as follows:
Data Record Process Record
---------------- -----------------
| @377 | | @376 |
----------------- ----------------- __
| Start Address | | Char1 | Char2 | |
----------------- ----------------- |
| No of Words | | Char3 | Char4 | |> Process
----------------- ----------------- | Name
| Data Word 1 | | Char5 | Char6 | |
----------------- ----------------- --
| Data Word 2 | | Level Hd Addr |
----------------- -----------------
. . | Sum Check |
. . -----------------
. .
----------------- Sum Check = Sum of previous
| Data Word N | four words.
-----------------
| Sum Check |
----------------- Channel Record
Sum Check = Sum of data -----------------
words 1...N. | @375 |
----------------- __
| Char1 | Char2 | |
----------------- |
| Char3 | Char4 | |> Channel
Bank Switch Record ----------------- | Name
| Char5 | Char6 | |
----------------- ----------------- --
| @373 | | Channel Addr |
----------------- -----------------
| Bank Code | | Sum Check |
----------------- -----------------
Sum Check = Sum of previous
four words.
Unlike absolute files on the KS500, an end record of zero is not
used to terminate the file. This allows absolute files to be
concatenated using the standard DCL command COPY.
5 ERROR MESSAGES
==============
KSABS may issue a number of error messages. These are always of the
form "%KSABS - Description", any may also be followed by a standard
VAX error message further describing the cause of error. For example,
specifying an input file which does not exist will cause the following
messages to be output:
%KSABS - Error opening input file
%RMS-E-FNF, file not found
Normally, errors are reported during three phases of KSABS and
correspond to the following categories of errors:
(1) Command errors. e.g. entering an illegal option
(2) Input file errors. These indicate that the input file
was not of the correct type or has been tampered with.
(3) Output file errors. These indicate that a specified
process or channel could not be defined.
Command Errors
--------------
Error Message Description
Input file specification The input filespec was too long to be
too long a valid VMS file specification.
Missing input file An input file was not specified in
specification the command line.
Missing option after / No option was specified after /.
Retype the command with an option, or
leave out the extra /.
Option keyword too long An option after a / was too long.
Enter the option properly.
Unknown option keyword An unknown KSABS option was specified.
Enter the correct option.
Keyword is ambiguous, too An option entered in abbreviated form
few characters given is ambiguous. Enter more characters or
use the full option name.
Illegal character after An illegal character or delimiter was
option, / expected entered after an option. Retype
correctly using /.
File specification after The output file specification was too
/OUTPUT= is too long long to be a valid VMS filespec.
Missing file specification No file specification was typed after
after /OUTPUT= the /OUTPUT= option, or an illegal
character was typed.
File specification after The dump file specification was too
/DUMP= is too long long to be a valid VMS filespec.
Missing file specification No file specification was typed after
after /DUMP= the /DUMP= option, or an illegal
character was typed.
Missing = after /BANK option The /BANK option must be followed by
=.
Missing octal bank switch No octal number was entered after the
code after /BANK= /BANK= option.
Missing = after /CHANNEL The /CHANNEL option must be followed by
option =.
Channel name after /CHANNEL= The channel name specified using the
is too long /CHANNEL option is too long. Retype
it properly.
Missing process name or An illegal character was entered after
illegal character after the /CHANNEL= option, or no channel
/CHANNEL= name was given.
Too many channels defined Too many channel definitions were
using the /CHANNEL option entered. Currently up to 50 channels
may be defined.
Missing = after /PROCESS The /PROCESS option must be followed by
option by =. Retype correctly.
Missing process name or No process name was given after the
illegal character after /PROCESS= option, or an illegal
/PROCESS= character was typed. Retype correctly.
Too many processes defined Too many process definitions were
using the /PROCESS option entered. Currently up to 50 processes
may be defined.
Error in reading foreign An error occurred in trying to read
command line the KSABS command line. This is
usually because the command line
was too long. (More than 1000
characters)
Input File Errors
-----------------
Error Description
Error in opening input file The input absolute file could not be
opened. This should be followed by a
standard VAX RMS error message
the cause of error.
Error in closing input file The input file could not be closed.
This is highly unusual and should be
treated as a possible bug. Please
report this at your earliest
convenience.
Error whilst reading input An error occurred whilst reading the
file input file. A standard VAX RMS error
message should be typed.
Input file is not a KS500 The input file is not an absolute file
absolute file produced by the link loader from a
KS500 program.
Input file is not absolute, The input file is not an absolute file
section XXXX is relocatable produced by the link loader. The file
contains a relocatable program section
and must be submitted to the link
loader.
Warning, undefined external The input file contains an undefined
XXXXXX external symbol XXXXX. The output
KS500 absolute format file will be
generated assuming a symbol value of
zero.
Warning, data outside 64k The input file contained data at an
address space address outside the range 0 - 65535.
This should not happen unless the
input file has been tampered with.
Any such data is ignored.
Input file is a library The input file is a ROB format library
file, not an absolute file file not a ROB format absolute file.
Specify the correct file. If you wish
to convert a library into absolute
form, submit it to the link loader.
Warning, checksum error A checksum error was detected in the
input file. This may indicate that the
file has been tampered with, or that
a error occurred in transferring the
file from another medium.
Warning, checksum of The input file contained an error in
checksums error the checksum of the checksums. This may
indicate that the file has been
tampered with, or that an error
occurred in transferring the file from
another medium.
Input file format error, The input file is not in correct BSO
XXXXXXXXXXXXXXXXXXXXXXXX ROB format. This indicates that the
in line YYYYY file is not an absolute file produced
by the link loader, or that the file
has been tampered with. The message
part XXXXXXXX should describe what
type of format error was found:
unexpected end of file
missing checksum of checksums
missing checksum
too many operands in expression
missing operand in expression
illegal reverse polish expression
illegal block type
illegal block start character
missing block number
Output File(s) Errors
---------------------
Error Description
Error in opening output The output file could not be opened.
file This should be followed by a standard
VAX RMS error message.
Error in opening dump file The dump file could not be opened.
A standard VAX RMS error message should
follow this to describe the cause of
the error.
Error in closing output file The output KS500 absolute file could
not be closed. This is highly unusual
and should be reported as a bug at
your earliest convenience.
Error in closing dump file The dump file could not be closed.
See above.
Error in writing to file An error occurred whilst writing to
one of the output files. This may
be caused by running out of your
allocated disk quota. A standard VAX
RMS error message should follow.
Warning, undefined process The specified process could not be
XXXXX defined. This indicates a non existent
process or that the link loader was
not instructed to pass global symbols
to the ROB format absolute file.
Warning, undefined channel The channel XXXXX could not be defined
XXXXX from the input file. This indicates
a non existent channel, or that the
link loader was not instructed to
pass global symbols to the ROB format
absolute file.
Miscellaneous Errors
--------------------
The following errors are internal fault reports and should be
reported as bugs at your earliest convenience.
Fatal internal error, option number out of range
Illegal Logical Unit Number
Logical Unit Number in use
Logical Unit Number unused, file not open
File not opened before writing
File not opened before reading