,ll 6.6
,cs 10
,pl 66
,lm 0.2,0.5
,pn 29
,ju
,hd
,ce
OmegaSoft 6809 Cross Pascal Language Handbook (V1.0)
,,
,ft

,ce 1
6-##
,,
,ce
OmegaSoft 6809 Cross Pascal Language Handbook (V1.0)
,ce
I/O PROCEDURES

For non-text devices write is equivalent to :

device^ := expression ;
put (device)

If the device is of type text then internal conversions are done using the string function for boolean and numeric values. If the first parameter is not a device variable then the standard output device will be used.

Following each expression may be an optional colon and fieldwidth parameter whose functions depends on the data type to be written. If the fieldwidth is positive it will pad spaces on the left, if it is negative then it will pad spaces on the right. Only the least significant 8 bits of the parameter are used. We will present the formatting used on a type by type basis :

Boolean

If the fieldwidth is not specified then a value of 6 will be used. If the specified fieldwidth is not sufficient to hold the string then it will be truncated on the right. 

Fieldwidth = 6  "  TRUE"   " FALSE"
Fieldwidth = 4  "TRUE"     "FALS"
Fieldwidth = 1  "T"        "F"
Fieldwidth = 0  ""         ""
Fieldwidth = -6 "TRUE  "   "FALSE "

Character

If the fieldwidth is not specified then a value of 1 will be used. If the specified fieldwidth is not sufficient (0) to hold the character then it will be truncated to zero length.

Fieldwidth = 6  "     A"
Fieldwidth = 1  "A"
Fieldwidth = 0  ""
Fieldwidth = -6 "A     "

Integer

If the fieldwidth is not specified then a value of 10 will be used. If the specified fieldwidth is not sufficient to hold the string then it will be expanded.

Fieldwidth = 6  "  1234"
Fieldwidth = 4  "1234"
Fieldwidth = 1  "1234"
Fieldwidth = -6 "1234  "

Hex

If the fieldwidth is not specified then a value of 6 will be used. If the specified fieldwidth is not sufficient to hold the string then it will be truncated on the right.
,pg
,ce
I/O PROCEDURES

Fieldwidth = 6  "  F3A7"
Fieldwidth = 4  "F3A7"
Fieldwidth = 1  "F"
Fieldwidth = 0  ""
Fieldwidth = -6 "F3A7  "

Longhex

If the fieldwidth is not specified then a value of 10 will be used. If the specified fieldwidth is not sufficient to hold the string then it will be truncated on the right.

Fieldwidth = 10  "  F3A70481"
Fieldwidth =  4  "F3A7"
Fieldwidth =  1  "F"
Fieldwidth =  0  ""
Fieldwidth = -10 "F3A70481  "

Longinteger

If the fieldwidth is not specified then a value of 16 will be used. If the specified fieldwidth is not sufficient to hold the string then it will be expanded.

Fieldwidth = 10  "    431874"
Fieldwidth = 6   "431874"
Fieldwidth = 4   "431874"
Fieldwidth = -10 "431874    "

Real

If the fieldwidth is not specified then a value of 16 will be used. If the specified fieldwidth is not sufficient to hold the string then it will be expanded. There is another optional parameter than can follow the fieldwidth. If a colon and a parameter follows the fieldwidth it is the precision. If the precision is positive the format will be in fixed point notation and the parameter is the number of digits past the decimal point. If the precision is negative then the format will be floating point with exponent. In this floating point format there will always be 6 digits to the right of the decimal point and a 2 digit exponent. The default for the precision is negative.

Fieldwidth = 14 , Precision = -    "  3.141593E+00"
Fieldwidth = 14 , Precision = 3    "         3.141"
Fieldwidth = 14 , Precision = 6    "      3.141593"
Fieldwidth = 14 , Precision = 10   "  3.1415925000"
Fieldwidth = 5  , Precision = 3    "3.141"
Fieldwidth = 5  , Precision = 6    "3.141593"

In the floating point format there is always one position used in front of the number to be used as a sign, space for plus, "-" for negative. In the fixed point format there is only a position used if the number is negative (for the - character). The same number (plus or minus) is used in the following examples.

Fieldwidth = -14, Precision = -   " 3.141593E+00  "
Fieldwidth = -14, Precision = -   "-3.141593E+00  "
Fieldwidth = -10, Precision = 5   "3.14159   "
Fieldwidth = -10, Precision = 5   "-3.14159  "
,pg
,ce
I/O PROCEDURES

String

If the fieldwidth is not specified then a value equal to the dynamic length of the string will be used. If the specified fieldwidth is not sufficient to hold the string then it will be truncated on the right.

Fieldwidth = default "OmegaSoft"
Fieldwidth = 10      "OmegaSoft "
Fieldwidth = 5       "Omega"
Fieldwidth = 0       ""
Fieldwidth = -10     " OmegaSoft"

The sequence :

writeln (device, expr1, expr2, expr3)  is equivalent to :

write (device, expr1) ;
write (device, expr2) ;
writeln (device, expr3)

write-procedure = write [( (device-variable
                  [{,write-expression}] |
                  write-expression {,write-expression}) )]
writeln-procedure = writeln [( (device-variable 
                    [{, write-expression }] |
                    write-expression {, write-expression  }) )]
write-expression = expression [: field [: precision ]]
field = precision = (integer-expression | character-expression)


 write
             (     d      ,     e1     :     e2    :    e3     )
writeln
 

        where :
          d = device variable
         e1 = data expression
         e2 = fieldwidth
         e3 = precision

,ce
DYNAMIC VARIABLE MANAGEMENT PROCEDURES


These procedures are used to handle allocation of variables on the heap.

DISPOSE

This procedure will "disconnect" the pointer parameter from an the area of the heap it was pointing to. The pointer will have the value of nil after execution of this procedure. In the standard implementation of the heap this procedure does not actually give back any memory to the system.

If a more-advanced heap manager is used then the amount of memory to give back must be the same as the amount gotten using the new call. See the description of the new procedure on the use of the tag values and the size parameter.
,pg
,ce
DYNAMIC VARIABLE MANAGEMENT PROCEDURES

dispose-procedure = dispose ( pointer-variable {, tag-values}
                              [: size ] )

MARK

This procedure will store the current position of the heap pointer into its parameter. This is the start of free storage in the heap. Further calls to new will cause the heap pointer to increase in magnitude. To effectively restore all of this memory used by the new procedure from the time the mark procedure was called, the release procedure would be used.

Example :  mark (heapstart) ;
              .
           new (ptr1) ;
              .
           new (ptr2) ;
              .
           release (heapstart) ; {heap now same as before the new
                                  calls}

mark-procedure = mark ( (integer-variable | pointer-variable |
                         hex-variable) )

NEW

This procedure allocates storage on the heap and places the start of that storage in its pointer-parameter. The base type of the pointer variable will determine how much storage is allocated on the heap. 

The optional tag values are field identifiers of records and in ISO Pascal are used to determine how much space to allocate based on which case variants are active in the record that the pointer points to. These tag values are ignored in OmegaSoft Pascal and the size of the largest variant is used.

An extension in OmegaSoft Pascal is the size parameter which allows you to override the default size with a specific value. This is especially useful when putting strings on the heap by using something like :

type
  lines = string [80] ;
var
  ptr : ^lines ;
  line : lines ;
begin
  new (ptr : length (line) + 1) ;
  ptr^ := line 

new-procedure = new ( pointer-variable {, tag-field }
                      [ : size ] )   
tag-field = identifier
size = (integer-expression | hex-expression)
,pg
,ce
DYNAMIC VARIABLE MANAGEMENT PROCEDURES


       new      (      pointer           ,    tag value
                       variable          


 
            :      integer/hex       )
                   expression


RELEASE

Will store the value in its parameter into the heap pointer. This has the affect of de-allocating all dynamic variables allocated between the previous mark using the same parameter and this release.

release-procedure = release ( (pointer-variable | hex-variable |
                               integer-variable) )

ALTERNATE HEAP MANAGERS

The supplied heap management routines are very fast and very simple. If your requirements are more complicated it is possible to replace the supplied heap management routines with your own, either written in assembly language or pascal. To write your own handlers in assembly language, refer to runtime file sp13 as a guide. If you are going to write a complicated driver, then you might be better off writing it in pascal. 

There is a file called "longheap" supplied which works as an interface between the runtime library and a pascal module. Longheap must be linked in before the standard runtime library so it will replace the entry points in sp13, or loaded using the filer A command in the target debugger. To use this module, you must provide 5 entry procedures, these must have the format of :

procedure new_long (var pointer, heap_ptr : hex ; size : hex ;
                    var heap_limit : hex ; stack : hex) ; entry ;

procedure mark_long (var pointer, heap_ptr : hex) ; entry ;

procedure rel_long (var pointer, heap_ptr : hex) ; entry ;

procedure disp_long (var pointer, heap_ptr : hex ; size : hex ;
                    var heap_limit : hex ; stack : hex) ; entry ;

procedure mema_long (var heap_ptr, heap_limit : hex ; 
                     stack : hex) : hex ; entry ;

The parameters have the following meanings :

stack - this is the current value of the user stack pointer (U). In the new and memavail procedures this is normally compared with the current heap_limit, and if lower, heap_limit is set to this amount. This is designed to set the heap_limit to it's worst case low value in order to avoid the stack crashing into the heap.
,pg

heap_ptr - is the current heap pointer. At initialization it is set to the start of the heap/data stack area. The first four bytes of this area are cleared to zero, this can be used for custom heap handlers, with 2 bytes indicating the block size (in this case zero, meaning the block size is determined by subtracting it from the heap_limit), and the other 2 bytes used as a link to the next free heap block (in this case zero, meaning no other blocks).

heap_limit - this is the highest location that the heap can go to. It starts out as the stack value before allocating any global variables, but is set in the memavail and new procedures before allocating any memory.

pointer - this is the pointer variable used for the heap management call.

size - used in the new and dispose procedures, this is the size requested to be allocated or de-allocated.

memavail function return - set to the amount of heap left.

The following example module shows the pascal equivalent of the default heap management in file sp13 :

module def_heap {$v3,0 default heap handler} ;

procedure new_long (var pointer, heap_ptr : hex ; size : hex ;
                    var heap_limit : hex ; stack : hex) ; entry ;
  var
    temp : hex ;
  begin
    if stack < heap_limit
      then
        heap_limit := stack ;
    pointer := heap_ptr ;
    temp := heap_ptr + size ;
    if temp >= heap_limit
      then
        halt (19)
      else
        heap_ptr := temp
  end ;

procedure mark_long (var pointer, heap_ptr : hex) ; entry ;
  begin
    pointer := heap_ptr
  end ;

procedure rel_long (var pointer, heap_ptr : hex) ; entry ;
  begin
    heap_ptr := pointer
  end ;

procedure disp_long (var pointer, heap_ptr : hex ; size : hex ;
                    var heap_limit : hex ; stack : hex) ; entry ;
  begin
    pointer := nil
  end ;
,pg

procedure mema_long (var heap_ptr, heap_limit : hex ; 
                     stack : hex) : hex ; entry ;
  begin
    if stack < heap_limit
      then
        heap_limit := stack ;
    mema_long := heap_limit - heap_ptr
  end ;
modend.
  
,ce
MISCELLANEOUS PROCEDURES

HALT

Will pass the least significant byte of its parameter to the error handling software as an error. If the parameter is zero then it will return with no action. If the parameter is 255 ($FF) then it will stop the program with no error. Any other value for the parameter will signal a runtime error and stop the program.

halt-procedure = halt ( (character-expression |
                         integer-expression | hex-expression) )

APPEND

This procedure will append up to 15 string or character constants or variables onto the end of a string variable. Note that character or string expressions are not allowed, only variables and constants. No error checking is done is by this procedure.

append-procedure = append ( string-variable { , (string-variable |
    string-constant | character-variable | character-constant) } )
