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

,ce 1
2-##
,,
,ce
OmegaSoft 6809 Cross Pascal for OS-9/68000 (V1.00)
,ce
OPERATION - PASCAL SHELL

PASCAL SHELL 

This program provides an easy to use and efficient method of maintaining the files associated with a project. The program is menu driven to avoid having to refer to documentation when using it. It requires that the TCON file be setup, as it uses screen control sequences and cursor movement keys.

COMMAND LINE

 xps [-options] shell_file

If any options are specified there must be no characters between options (such as spaces or commas). The following options are valid :

,in 0.45
,si -0.3
n - set terminal number. If this format is used it must be the first option. Default is auto-search.

,si -0.3
Tn - set terminal number, same as above, but may appear anywhere in option list.

,si -0.3
Znnn - set total data size in K. Should not need to be used.

,in 0
The shell file is the file produced by the linkage creator (.sf suffix).

SHELL FILE FORMAT

Example, comments in braces.

*mn:disp                    {module name}
*cl:xtdb                    (debugger command line options, none}
*cl:xpc -r                  {compiler options}
*cl:xpc -d
*cl:xpc -lp62ftw96 /p
*cl:xpc -dlp62ftw96 /p
*cl:xra -o                  {assembler options}
*cl:xra -lp62ftw96 /p
*cl:xll disp.mp             {linker command line option}
*cl:se                      {editor option, none}
*ll:start E000              {linker commands}
*ll:init ff
*ll:vect
*ll:v.start 10
*ll:load disp.pa
*ll:loadp disp              {loadp for pascal files}
*ll:lib  /h/xrl sbslib
*ll:align 1FF0
*ll:loada disp.va           {loada for assembly files}
*ll:object disp
*ll:mapf
*ll:exit
*db:i disp                  {debugger commands, i = pascal file}
*db:t                                          {a = assembly}
*db:l
*db:sv v4 irqhandl
                            {*in:include files}
,pg
,ce
OPERATION - PASCAL SHELL

The shell file can be edited to suit your needs. If you have special files that are used for the debugger, but not the linker, or vice versa, then you can edit the file to add those files only for the debugger or linker commands. All files will appear in the file selection menu as both debugger and linker file lists are scanned.

If you want to run the linker without using the pascal shell, you can use the same shell file :

$ xll <test.sf

OPERATION

Main menu :         Edit module
                    Compile module
                    Assemble module
                    Link
                    Run chain
                    Background chain
                    Exit Pascal Shell
                    Target Debug
                    Beep on termination
                    Restart
                    Review
                    Abort Background
                    Pass command line to shell

Use the keys for up and down cursor to select the option you desire and then hit carriage return. The cursor control keys for half page up and down are also functional.

Edit module

You will be shown a list of files that include the pascal source, assembly source, and include files as specified by the shell file.
The stack setup file (.ps) and shell file (.sf) are also included. You can use the up, down, left, right, and alternate cursor keys to move between files. Half up will move to the top line, half down will move to the bottom line. 

Pascal files are shown with P- in front of them, Assembly with A-, and include with I-. Hitting carriage return will return you to the main menu, hitting "S" will edit the selected file. When you exit the editor you will be back in this file selection menu. Hitting 'F' will flag the file as being changed by changing the "-" to a "*". You can turn this back to a "-" by hitting F again. Flagging a file will move you to the next file in the menu, so flag a file after you have edited it.

Hitting "T" will give you another set of choices to use for the reference time. Each file will be compared to the reference time, if it is newer it will be flagged, or else it will have its flag turned off. The choices are :
"O" - Use time of object file.
"L" - Use the time that the last chain was sucessfully completed. If no chain has been completed yet, it will use the time that you started the Pascal Shell.
"S" - Use time of last update of the selected file, you will be prompted for the file name to use as the reference.
,pg
,ce
OPERATION - PASCAL SHELL

Compile modules

You will be shown a list of possible options, use the cursor keys to select the appropriate one. Selecting "none of the above" will allow to enter a special set of options if desired. These options will be used for any files you select next. You will then be shown a list of pascal source files. 

Entering a "S" will cause the "P-" to change to "S-" which indicates that when you run the chain this file will be compiled with the options selected above. Entering a "R" will cause the prefix to change to "P-" indicating not to compile this file. You can re-select a previously selected file, it will just use the latest option list.

Entering a "A" will cause a scan of the files and will set all files that were flagged in the edit mode to "Set" to compile.

Assemble modules

This is essentially identical to Compile modules except that it operates on assembly language source files instead of pascal source files.

Link

You will be shown the default options for the linker, if these are OK, then enter a carriage return. If they are not OK, enter an "N" and then you will be prompted for new command line options. If you want to cancel queuing of the link command, enter a "C".

Run Chain

This is a multiple step operation. First all of the modules that were marked for compilation are compiled. Next all modules that were marked for assembly are assembled. Next, if you wanted to link, this will be done. Last, if you wanted to target debug, this will be done. Normally you will only have selected one of the two (link or target debug).

As each step is successfully completed, it will be removed from the queue of actions to take. For example, if the third compilation generates an error, the chain will stop. You can then edit the third module and then run the chain again. It will start again with the third compilation.

You cannot run a chain if there is currently a background chain in progress.

Background Chain

Starts a background chain which will compile all modules selected for compilation and assemble all modules selected for assembly. The current status will be displayed anytime you are in the main menu. If it completes with no errors then it will change it's status to "done". If there is an error, it will display "error". Like running the normal chain, you can correct the problem and it will re-try the last step that caused the error and continue on.
,pg
,ce
OPERATION - PASCAL SHELL

Note that while the chain is running you can select new files to be compiled or assembled and they will be acted on. The compilation and assembly sign-ons and status lines will be written to a file that has the format "back_00xx" where xx is the task id. This file name will be added to the edit file menu as an include file. This allows you to inspect this file in case an error should occur in background.

While the background chain is in progress you cannot run a normal (foreground) chain, or exit the pascal shell.

Exit Pascal Shell

Returns back to OS-9. Cannot be done if background chain still in progress.

Target Debug

You will be shown the default command line options for the target debugger, if this is ok, enter a carriage return. If this is not suitable then enter a "N" and you will be prompted for new options. This information will then be stored to be used when the chain is run. Enter a "C" if you wish to cancel queuing of the target debug command.

Beep on Termination

This allows you to turn on or off the beep flag. If the beep flag is on then it will send a "bell" character to the terminal when the "Run chain" command has terminated, either normally, or with an error. The "beep" occurs once per second and can be terminated by hitting control E, which will return you to the main menu. This feature is intended to be used when you have started the chain running and leave the room or are busy with other work and want to know when the chain is finished.

Restart

This command will reset all the queues and re-read the pascal shell file. This allows you to edit the shell file from the pascal shell and then use this new version of the shell file without having to leave the pascal shell.

Review

This command will show you what commands are currently in the queue.

Abort background

This command sets a flag that tells the background chain to stop after it is finished with the current compilation/assembly. Any compilations/assemblies that still need to be done will stay in the queue.

Pass command line to the shell

This allows you to run a command from inside the Pascal shell. You are prompted with a "$" prompt, enter the command line as is normally done when working with OS-9.
,pg
,ce
OPERATION - PASCAL SHELL

The defaults for the command line options are located near the beginning of the program's data section and can be patched if desired. The location given is an offset from the start of data section, this address can be obtained from locations 6-9 of the current revision software.
,ce
OPERATION - PASCAL SHELL

Location   Flag                           Default

0008       directory of TCON file         4,'/dd/'
001E       directory for background file  4,'/r0/'

The directory of TCON file was discussed in the installation section of this manual.

The directory for background file is where the file that has the status of each compilation/assembly will go. The file name is made of "back_" followed by a four digit hexadecimal representation of the task id of that user's pascal shell.

,pg
,ce
OPERATION - PATCH

PATCH

This utility is useful for a variety of operations. For instance, you can change values in device descriptors located in the boot file without rebuilding the boot file, change data area size of programs, or any case where you want to change a few bytes without re-assembling.

COMMAND LINE

   patch <filename>

BASE COMMAND

   B <address>

Sets the base address to the value specified. Normally the base address is set to 0. If working in a file that has a number of modules you may want to set the base address to the start of the module you are currently working on so that addresses entered will be relative to the start of the module.

DISPLAY COMMAND

   D <from> [<to>]

Displays file from offset <from> to offset <to>. If <to> is not specified then <to> will be set to <from> + $FF (displays one page).

FIND COMMAND

   F <value> {<value>} or
   F '<string>

In the first form up to 16 byte values may be entered (hex) separated by spaces and all occurrence of that pattern of consecutive bytes will have their address printed. In the second form a string of up to 16 characters is entered. All occurrence of that string (disregarding the most significant bit and upper/lower case) will have their address printed.

HELP COMMAND

   H

Displays a list of commands available

INITIALIZE COMMAND

   I <from> <to> <value>

Value is written into bytes starting at <from> and ending at <to>. If <to> is past the current end of file the file will be extended.
,pg
,ce
OPERATION - PATCH 

MEMORY EXAMINE/CHANGE COMMAND 

   M <address>

   <value>
   '<char>
   "<char> 
   <carriage return>
   ^ 
   / 

This command allows you to examine the contents of the file at any address (not past eof) and to change the contents if desired.

If a hex value is entered then that value will replace the contents shown. If a single quote is followed by a character that will replace the contents. If a double quote is followed by a character then the value of that character with its most significant bit set will be used. If only a carriage return is entered then the next location will be shown. If a caret (or up arrow on some terminals) is entered then the previous location will be shown. Entering a slash will exit this command.

NAME COMMAND

   N [<module name>]

If no name is specified then all modules, and their offsets from the start of the file, will be listed. If a name is specified then the command will search for the module within the file. If the module is found, its offset is displayed and the base address will be set to that offset. This is very useful when patching the OS-9 boot file. This command automatically adjusts for 68000 and 6809 module formats.

QUIT COMMAND

   Q

Exits patch routine - the file opened on the command line is closed.

RELATIVE COMMAND

   R <value> <+ or -> <value> 

Calculates the sum or difference of the two values. Useful for determining the argument for relative branches.

VALIDATE COMMAND

   V <cr>

Will restore the header checksum and module CRC on all of the modules in the file. This command automatically adjusts for 68000 and 6809 module formats.


