,ll 6.6
,cs 10
,pl 66
,lm 0.2,0.5
,pn 1
,ju
,hd
,ce
OmegaSoft 6809 Cross Pascal for OS-9/68000 (V1.02)
,,
,ft

,ce 1
1-##
,,
,ce
OmegaSoft 6809 Cross Pascal for OS-9/68000 (V1.02)

,ce
SYSTEM INSTALLATION

The host system must run the OS-9/68000 operating system, have at least two disk drives, and have at least 512k of system RAM available to the user. The system should have at least one hard disk to be used as a system disk, use without one is possible, but hardly worth it. OS-9 version 2.0 or newer is required.

The following files are supplied with the PXK9 package for OS-9/68000 and should be copied from the distribution disk to your system disk or data disk. These files are split up into groups on the distribution disks, refer to the sheet marked "disk contents" for a listing of which files are on each disk.

,ce
In the commands directory :

File     Description                  Should be placed in      

xpc      Pascal Compiler              /dd/cmds/
xra      Assembler                    /dd/cmds/
xll      Linker                       /dd/cmds/
xlc      Linkage Creator              /dd/cmds/
se       Screen Editor                /dd/cmds/
con      Configuration Manager        /dd/cmds/
xlb      Librarian                    /dd/cmds/
patch    Patch utility                /dd/cmds/
xps      Pascal shell                 /dd/cmds/
vermod   Pascal shell support         /dd/cmds/
xtdb     Target Debugger              /dd/cmds/

,ce
In the root directory :

File        Description             Should be placed in    

xrl.ro      run-time library        /dd/
xos9io.ro   os-9/6809 I/O library   /dd/
tcon.dt     terminal config.        /dd/

,ce
In the runtime directory :

File        Description                        Should be placed in

xpasequ      "Equate" file for runtime routines      /dd/pdef/

The rest of the files provided with the package do not need to be placed on your system disk at this time. They are provided for your reference and customization if required. Please do make sure you backup up the master disks, for your own protection and also to allow you to return the master disks for update. Note that the pascal source files are designed to be compiled using package PCSK version 1.24.

,ce
In the root directory :

Source for XLC :  xlc   xlc.ps  xlc.sf

Source for XLB :  xlb   xlb.ps  xlb.sf

Source for SE :  os9se   se1   se2   se3   se4   se5   se6
                 seincl   os9se.ps   secomp    os9se.sf

OS-9 and OS-9/68000 are trademarks of Microware Systems Corp.
,ce
INSTALLATION

Source for CON : os9con   os9con.ps   os9con.sf

Source for PATCH : os9patch   os9patch.ps   os9patch.sf

Source for XPS : xps   getfile   os9crt   psincl   psdecl
                 xps.ps   xps.sf

Source for XTDB : xtdb   tdb1   tdb2   tdb3   tdb4   tdb5   tdb6
                  tasm   tdis   tasm1   tcvrt0   tcvrt1   tcvrt2
                  tcvrt3   tcvrtinc   tdbincl    xtdb.ps
                  xtdb.sf

,ce
In the target directory :

Source for target : target   target.ps   target.sf    target2
                    target6   target.vs    io2661   io6850   tio2
                    tse1   target1

,ce
In the runtime directory :

System independent runtime library source :

    su1 - su12 (utility)            so1 - so16 (operations)
    sf1 - sf26 (functions)          sp1 - sp19 (procedures)

System dependent runtime library source (for os9/6809) :

    sd1 (device drivers)     sd2 (error handler)
    se1 (end of runtime marker)

Other files : xrl.cf (chain file for merging runtime)
              xos9io.cf (chain file for merging device drivers)
              asu.cf  aso.cf  asf.cf  asp.cf (chain files to
                 assemble/compile runtime library groups)
              xos9sd.cf (chain file to assemble device drivers)

FILE SUFFIXES

Due to the nature of this implementation of pascal there are a number of files, each related to the pascal source file. To avoid having to come up with a bunch of names to describe these files it was decided that they should all use the same "root" name as the pascal source. Suffixes are used to distinguish between the different files. The following suffixes are currently used :

   source code                        -  no suffix
   compiler output                    -  .CO  {O option on}
   compiler output                    -  .DB  {D option on}
   compiler output                    -  .RO  {R option on}
   .co after assembly and general
   relocatable object files           -  .RO
   pre-setup source                   -  .PS
   .ps after assembly                 -  .PA
   loadable object files              -  .LO {if used}
   S record object files              -  .LX {if used}
   shell file                         -  .SF
,pg
,ce
INSTALLATION

TERMINAL CONFIGURATION

The screen editor and pascal shell require a file to exist that contains parameters unique to the terminal you are using. Up to four types of terminals may be supported in this file, these four terminals are numbered 0 through 3. If no terminal number is specified on the pascal shell or screen editor command line, they will try to match the terminal device descriptor name that you are using to the entries in the terminal file, if no match is found, terminal number zero will be used

This terminal configuration file (TCON.DT) is normally located in the root directory of the system disk. As shipped the directory where the file is located is "/dd/". If this is not acceptable then the first thing to do is to patch the configuration manager (CON), the editor (SE), the pascal shell (XPS) and the target debugger (XTDB). The offset from the start of data section where this string is located is $8 for the configuration manager, the offsets for the editor, pascal shell, and debugger are documented in chapter 2. This offset is to be added to the start of data section, which is available at locations $48-4B in the module header.

For example, you could change "/dd/" to "/hd00/" by typing (your entries in bold type, followed by carriage return) :

$ patch con
->d 48 4b                      {find data section start}
00000048  0048  00 00 39 38
->b 3938                       {set offset to data section start}
->m 8
000038C0 0008 04 06
00003941 0009 2F '/
00003942 000A 64 'h
00003943 000B 64 'd
00003944 000C 2F '0
00003945 000D 00 '0
00003946 000E 00 '/
00003947 000F 00 /
->v
->q
$

The first byte is the number of characters that are valid (it is a Pascal string). The V command re-validates the module header checksum and module CRC, for more information on the Patch utility, see chapter 2.

This process must be repeated for the screen editor, pascal shell, and target debugger using the offset from data section in chapter 2 and the start of data section from their locations 48-4B.

The terminal must support the following control sequences : Home screen, Position cursor, backspace, clear to end of screen (or clear screen), and clear to end of line (or clear line).
,pg
,ce
INSTALLATION

The terminal configuration file also contains a table of the special keys used for commands and general editing. This allows utilization of cursor movement keys found on some terminals. No special keys are actually required for use, as if you are a touch typist it is better to keep you hands near the main part of the keyboard rather than moving them off to the side or top to get at cursor movement keys.

The Terminal configuration file provided on the distribution disk contains the entries for a VISUAL-200 (normal, non-ANSII) terminal as terminal number 3, a Televideo 970 (ANSII) terminal as terminal number 2, with terminal numbers 0 and 1 blank. You can use the VISUAL or Televideo entries as a guide, as most of the entries (especially keyboard entries) will be the same for most terminals. The VISUAL control sequences are also the same as a LSI ADM3A and all but the position cursor command is the same as an ADDS 520+. The Televideo sequences should be the same as most any ANSII terminal.

Note that if you already have the PCSK package (version 1.1 or newer), then you already have a valid TCON.DT file on your system, in fact, the editor and configuraiton manager are identical between the PXK9 and PCSK packages.

The configuration manager is run by typing :

$ con

This is an interactive and menu driven program, with two menus shown depending on mode.

You will be prompted for the terminal number to update (0 - 3). Terminal zero should be the most commonly used terminal in the system, as it is the default on the editor and debugger command lines.

Enter a number from 0 to 3, if you would like to look at the VISUAL entries then enter 3, look at the entries, determine what ones you would like to copy (if any), exit the program, and restart the program specifying the actual terminal you would like to configure. If you have no interest in the VISUAL entries, just enter the number of the terminal you want to configure (probably 0). The same applies for the Televideo entries in terminal number 2.

The main menu will now be displayed as :

0 = clear entries       1 = update config file
2 = display entries     3 = change entries
4 = copy of terminal    5 = test control sequences
6 = exit

(0) will clear selected entries for the terminal number currently being modified (a range of entries will be requested). (1) will write the new information for the current terminal to the configuration file. (2) will display the contents of each entry (a range of entries will be requested). (3) will allow you to change each entry (a range of entries will be requested). (4) will allow you to copy entries from another terminal to the current terminal (a range of entries will be requested).
,pg
,ce
INSTALLATION

(5) will allow you to test out the display control sequences. (6) will exit the configuration program. NOTE : exiting the program will not automatically update the configuration file!

If you wish to copy entries from the VISUAL terminal, enter command (4) and then enter 3 when prompted for terminal number, and then enter the range of entries you want copied. If you want multiple ranges of entries, you must use the (4) command for each range.

Enter command (3) to change entries. You will be prompted for the first entry, enter the first one you would like to change (if you copied no entries from terminal 3, then enter 0). You will be prompted for the last entry, enter the number (if you copied no entries from terminal 3, then enter 84).

If the starting entry number is less than 19 then you will now be prompted for a number of sequences for screen control. Entering a carriage return only will indicate that your terminal does not support that feature. Those features that must be supported will be indicated. There are a number of ways to specify a byte value, they are :

 A printable letter (except ^ or $) - enter the letter.
 A control character - enter ^ followed by the letter.
 Escape - enter ESC
 Space - enter SPACE
 Any 8 bit value - enter $ followed by the hex value.

 Examples, sequence is escape, letter Y  - ESC Y
 sequence is control Q, hex D7 - ^Q $D7
 sequence is control H, space, control H - ^h space ^h

There must be no spaces between the ^ or $ and the following characters. There must be a space between each byte value in the sequence. You are allowed up to 7 byte values per sequence. After you enter the carriage return for the sequence it will be displayed and you will be asked for confirmation. Answering with a N will indicate that it is not correct and you will be re-prompted for the same sequence. Entering an X will exit the change mode and return you back to the main menu. Entering anything else will indicate that the sequence is correct.

0) Sequence for clear to end of line : THE TERMINAL MUST SUPPORT THIS! You may also use clear line as this sequence is only used when the cursor is at the far left of the line.

1) Sequence for clear to end of screen : THE TERMINAL MUST SUPPORT THIS! You may also use clear screen as this sequence is only used when the cursor is at the upper left hand corner of the screen.

2) Sequence for home screen : THE TERMINAL MUST SUPPORT THIS! You may also use the cursor positioning sequence plus the bytes that would tell it to move to the upper left hand corner of the screen.

3) Sequence for half brightness : On fast systems it improves the appearance of the editor if the line numbers are at half brightness. Use this only if your terminal can accept a command to go into half brightness, accept a few characters, and then accept a command to return to full brightness. The terminal must not use any display positions to store the brightness change.
,ce
INSTALLATION

4) Sequence for full brightness : Same as above.

5) Sequence for position cursor : THE TERMINAL MUST SUPPORT THIS! Most non-ANSII terminals accept a position cursor sequence of the form : Lead-ins, line value, column value. The line and column may be reversed on some terminals. Most terminals bias these line and column values so that they are printable using an offset of a space (integer 32). ANSII terminals normally use a sequence of the form : Lead-ins, line value, separator, column value, terminator. In this case, enter the full sequence with a backslash in place of the values, as an example : ESC [ \ ; \ H.

6) Sequence for backspace : THE TERMINAL MUST SUPPORT THIS! This must be a destructive backspace, with the back-spaced over character replaced by a space. The most common sequence for this is : control H, space, control H.

7) Sequence for reverse scroll : Some terminal allow you to reverse scroll, this makes moving backwards through the file much easier and faster. The cursor will be at the upper left hand corner of the screen when this sequence is sent out. Many terminals that do not have a reverse scroll command will work if they have an insert line command, since inserting a line before the first line should do a reverse scroll and clear the top line.

8) Sequence for line insert : The cursor will be at the far left of the line, the line insert command must insert a blank line before the line where the cursor is located.

9) Sequence for line delete : The cursor will be at the far left of the line, the line delete command must delete the line where the cursor is located. Since this will remove one line, the command must also add a blank line at the bottom of the screen.

10) Sequence for character delete : The cursor will be at the character to be deleted. Note that this must work on the current line only, data must not move up from following lines.

11) Sequence for tab marker : This must only be one character. The "|" character is recommended. Another suitable character would be the "!".

12) Sequence for insert character : This is not currently used and you can leave this sequence blank.

13) Sequence for initialization 1 : Sent when entering the screen editor or debugger, user defined.

14) Sequence for initialization 2 : Sent when entering the screen editor or debugger, user defined.

15) Sequence for initialization 3 : Sent when exiting the screen editor or debugger, user defined.

16) Sequence for initialization 4 : Sent when exiting the screen editor or debugger, user defined.

17) Sequence for auxiliary number 1 : Not currently used.

18) Sequence for auxiliary number 2 : Not currently used.

