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

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

SCREEN EDITOR COMMAND LINE

se [-terminal number] [old file to edit]

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 - terminal number (0 - 3), 0 is default if not specified, this method of specifying the terminal is only valid if this is the first option.

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

,si -0.3
Znnn - set total amount of data memory available to the editor. This affects the amount of buffer space and the maximum number of lines available. Note that in this release the maximum number of lines that can be edited is 8000 even if more memory than is necessary is provided.

,in 0
If the old file to edit is specified then that file will be read into the edit buffer, as if the Edit old file command had been entered with the specified file name.

COMMAND LINE EDITOR COMMAND - Additional information

Syntax : $<command line>                   Con key : command line

Will pass the command line string to the operating system "shell" for execution. After the shell returns you can hit any character to restore the screen and continue editing. If you enter a null command line you will stay in the shell until you enter the shell end of file character.

There are two sequences in the command line that will initiate special processing by the editor. The first is that the CHD command is handled by the screen editor, since it would do no good to pass it to a new invocation of the shell. The second is that a "@" will be considered a special option to the compiler or the assembler. The editor will append the address of a parameter block to the @ and pass this to the compiler or assembler. This informs the compiler and assembler to compile from the edit buffer, not from a file. For instance, just checking the file in the edit buffer for syntax :

E> $xpc -@

If an error is encountered, the error and the line will be displayed, you can enter a Q which will return you to the editor with the cursor located where the error is, or hit any other key to continue. The first 20 errors detected by the compiler or assembler will be stack, and you move to the next error (actually the previous error), using the "goto next error" key. This allows you to pick up a number of errors in one compiler pass and then move to the editor to correct them without having to write down the line numbers or waste time saving the file.
,pg
,ce
OPERATION - EDITOR

The @ option does not interfere with the operation of other command line options, it merely takes the place of specifying the input file name, for instance, to compile the program in the edit buffer, generating relocatable object code, and a listing to the printer :

E> $xpc -@rlp66ftw96 . /p

The defaults for various parameters 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 the data section, this address can be obtained from the release history of the current revision software.

Location    Meaning                    Default

0000        Default tab settings       3,'R 2'
0016        Default upper/lower case   1 (equivalent)
0020        Error message delay        100 (in ticks, 2 bytes)
0022        Directory of TCON file     4,'/dd/'

The error message delay is used to determine how long an error message is displayed on the screen before being erased. This value can be experimentally changed to suit your desires.

The default tab settings are in the same format as the Tab setting command in the editor. The string has the dynamic length (number of characters in string) and then the characters that make up the string.

The default upper/lower case flag determines whether or not upper and lower case letters are equivalent when searching. The default can be changed while in the editor using the appropriate command.

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

The minimum data area size can be changed at location $38 as described for the compiler.
,pg
,ce
OPERATION - LINKAGE CREATOR

LINKAGE CREATOR

In order to generate a stand-alone Pascal program it is necessary to set up the stacks and link it with the runtime library. The linkage creator may be used to generate the stack setup code and a "chain" file to link the output of the compiler and the assembled stack setup code with the runtime library and other relocatable files or libraries.

COMMAND LINE 

 xlc [-options] [summary path name] [pascal file name]

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
D - deletes files previously created, leaves the pascal source file and the final output file.

,si -0.3
L - enables summary. The summary contains information for documentation purposes, such as extra files loaded, stack addresses, etc.

,si -0.3
F - update only front end (.ps) file. If enabled will not update the shell file, only the stack setup file, and the vector file (if non auto setup).

,si -0.3
S - update only shell (.sf) file. If enabled will not update the front end or vector files.

,si -0.3
Pnnn - sets page size for summary, default is P0 (no pagination).

,si -0.45
The following special path names are valid for the summary :

,si -0.3
T - use system terminal (the one you are using)

,in 0
The summary path name is only specified if the L option is used. If the pascal file name is specified it will be used as the root file name for all of the files generated and as the Pascal program name. A suffix must not be specified for the pascal file name.

If neither the F or S options are specified, then both the shell file and the front end file will be updated.
,pg
,ce
OPERATION - LINKAGE CREATOR

SUFFIXES

A number of files are generated each with the same directory (if used) and name as the Pascal compiler output file but each with a different suffix. 

   Output of compiler                   - .RO
   Setup source                         - .PS
   Setup after assembly                 - .PA
   Other relocatable files              - .RO
   Loadable object module               - .LO {if used}
   S record object                      - .LX {if used}
   Vector source                        - .VS {if used}
   Vector after assembly                - .VA {if used}
   Shell file                           - .SF

,ce
OPERATION

GENERAL :

The linkage creator will prompt for the required information needed for basic operation.

The first two questions will not be asked if the pascal file name was specified in the command line. The first question is the "Pascal compiler output file name" which is the file name (and directory if required) but with no suffix. If the delete command line option was specified this will be the only question asked.

IF UPDATING FRONT END FILE :

The next question is "Pascal program name" which is the identifier used after the Pascal reserved word "program". In many cases this will be the same as the file name (less directory) and if so this question can be answered with a carriage return. 

If you have already compiled the program (and if it has the standard suffix of .ro) then the linkage creator will open this file and read it until it determines the global variable size. It will then display this size. If it could not find the file, then it will display that it could not determine the size. This value is the absolute minimum amount of stack space required. You must also take into account procedure calls (10 bytes for local stack frame, plus room for parameters and function return, room for variables in varib section, plus room for local variables). Note that stack space is also used for expression evaluation and that the use of strings can use up quite a bit. In other words, be generous.

AUTO SETUP :

There are two methods available with the linkage creator to set up the stacks. The first one is "Auto setup" which is normally used for programs that run under the OS-9/6809 operating system. You will first be asked if you want "Auto memory sizing". 
,pg
,ce
OPERATION - LINKAGE CREATOR

If you answer yes, then it allows the program to request as much memory from the operating system as it can get, or to a fixed limit. You will be prompted for the "Minimum stack, heap, and Varib size : ", this is the minimum amount for the program to run.
You will next be prompted for the "maximum memory to use : ", this is the limit amount. You will then be prompted for the "Amount to give back : ". This is used to leave the operating system some memory (for I/O buffers, etc.) You should always give back at least 512 bytes (200 hex).

If you answer no, you will be prompted for the "Stack, heap, and Varib size : ". This is the amount of memory that will be used.

You will next be prompted for "system stack size : ", this is the amount of the above amount that will be reserved for the system stack. 256 should be considered minimum. 512 bytes is the most you should need, unless you have deeply nested recursive calling.

NON-AUTO SETUP :

The second stack setup method is non-auto setup. This mode is used when generating stand-alone code not meant to run under OS-9. 

You must provide the addresses for the start and end of the heap/stack area. The end of the heap/stack area is normally the end of RAM - 1. You will then be prompted for "System stack size : ", this is the amount of memory taken out of the top of the RAM area for the system stack. 256 bytes is normally the maximum you should need unless you have deeply nested recursive calling.

The next question is : "Parameter list address" and is used for the CLINE function and automatic redirection (if used). The address must be of the first character of the program parameter list (command line) and it must terminate with a carriage return. In most cases there will be no command line facility for a stand-alone program and you can just answer with zero.

You will also need to allocate two bytes of RAM for the program to store it's global stack mark, this is used by interrupt and firq procedures. Normally you set it to end of RAM - 1.

Example : Ram from 0 to 3FFF. Set beginning of RAM to 1 (to avoid a pointer value of 0 if the heap is used). Set end of RAM to 3FFE. Set global stack mark save address to 3FFE.

The next set of questions deal with interrupt vectors. You will be prompted for the routine name (max 8 characters) that is to be used for each interrupt vector. Answering with just a carriage return will use the default vector. As the default, any vectors not specified will reload the stack pointer and re-start your program. This is also the action should your program ever terminate normally, since stand-alone programs normally continue on forever (or at least until the warranty expires).

IF UPDATING SHELL FILE :

If you specified non-auto setup mode then the next question is "Starting load location" which will be passed along to the linker.
,pg
,ce
OPERATION - LINKAGE CREATOR

The next question is "Library directory name". This is the library that contains both the XRL and XOS9IO libraries. If they are in the current working directory then you would answer with a carriage return. If they are in the root directory (normally /dd) answer with that directory.

The next question is "Use default I/O library (/dd/xos9io) : ", answer "Y" if yes, else answer "N". If you answered "N" then you will be prompted for the I/O library to use instead, including directory if not in the current directory. Remember that any custom I/O library must have as the last file an equivalent of SE1 so the program knows actual section sizes.

In a modular program you will have more than just the main program. These pascal modules must be listed to the question : "Additional pascal files to load : ". You may have multiple files per line and you are allowed up to 40 lines, terminate this mode by entering only a carriage return.

If you have any assembly language modules then these must be listed to the question : "Additional assembly language files to load : '. You may have multiple files per line and you are allowed up to 10 lines, terminate this mode by entering only a carriage return.

If you have other libraries (either assembly language or Pascal) these can be specified as the answer to "Additional library files". Since it is assumed that some of these may override the normal runtime routines (custom error handlers, new floating point routines, etc.) this string is put before the normal runtime library in the linkers "lib" command. Multiple files may be listed on the line, but only one line is allowed.

The next question is "Linker command line info : " and the entered string will be added to the linker command line. This is usually answered with a carriage return. If you wanted S records out of the linker instead of a memory object file, you would specify -S as the answer to this question. If you wanted the map to go to a file or other device (besides the terminal) then you would specify this here also (see command line for linker). DO NOT SPECIFY THE COMMAND FILE FOR THE LINKER, THIS WILL BE DONE AUTOMATICALLY BY THE PASCAL SHELL.

The next question, "Map options", allows you to specify the format of the load map by appending the answer to the "map" linker command. If answered with a carriage return, "maps" will be used. 

If you use any include files you may specify those when prompted for "Other files, such as include files : '. You may have multiple files per line and up to 10 lines. These files are made available to the editor from the pascal shell, but otherwise have no other purpose.

If you plan on testing this program using the target debugger then you may want some default command line options for the debugger. You can specify these when prompted : "Target Debugger options : ". DO NOT SPECIFY THE COMMAND FILE FOR THE DEBUGGER, THIS WILL BE DONE AUTOMATICALLY BY THE PASCAL SHELL.

,pg
,ce
OPERATION - LINKAGE CREATOR

"Compiler options : " allows up to 10 defaults (instead of the one for the debugger). I normally use a standard set, such as :

-r         -lp62ftw96 /p       -rlp62ftw96 /p      -d    -i

Note that each one must be by itself on a line, you can not have multiple sets of options on a single line. Note that in options sets such as "-rlp62ftw96 /p" that the pascal shell notes that the R option is on and inserts the "." indicating the output file name before the list file specifier "/p". Enter just a carriage return to exit this mode.

"Assembler options : " is similar to compiler options.

The last question is "Editor options" which is normally only used if you want to reserve more than the default amount of memory for large files.

If you are updating the stack setup file then it will also be assembled to produce a file with a suffix of ".PA". Please note that you can edit both the stack setup file and the shell file to suit your special needs. For more details, see the section covering the Pascal Shell. If you used non auto setup mode, it will also assemble the vector source file to produce a file with a suffix of ".VA".

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.

Location     Flag                        Default

0000         top of form margin          0 (1 byte)

,pg
,ce
OPERATION - LIBRARIAN

LIBRARIAN

The Librarian provides a convenient method of merging relocatable object files together to form a library.

COMMAND LINE 

 xlb [-s] output filename {input file specifications}

If the S option is not specified then the input file specifications are simply file names to be appended into the output file. The input file names will be printed as they are opened. If the S option is specified then the input file specifications must be in the form of two letters followed by one or two integer digits. This option is used for building the runtime library to save a lot of typing. The one or two digit number is the maximum file number for the series. Since higher numbered runtime routines make use of entries in lower numbered runtime routines it is necessary to append the files in reverse order, thereby guaranteeing that the linker can determine the modules to be loaded in one pass of the library. To append the files XX4,XX3,XX2,XX1 and YY3,YY2,YY1 the command line could be : 

XLB XXYY XX4 XX3 XX2 XX1 YY3 YY2 YY1

or more compactly :

XLB -S XXYY XX4 YY3

A directory may be specified for the output filename, but not for the input file specifications.
