Charm Program Library (program) 


The Charm program library provides essential support to the running of a Charm program. 

The program library is written in a mixture of Charm and assembly language for speed and compactness. It contains the following records:

.err
.convert
 

error handling
conversions

which are described further below, as well as root level procedures:

Exit current program

export proc exit (int code)

  • passed code - return code

  1. Call this method to call static destructors (gracefully closing any open streams) and exit.
  2. The return code should be 0 for success and is placed in variable Sys$ReturnCode where it can be interrogated from the caller.
  3. Simply returning from the Charm ~start procedure has the same effect as calling this method with a success return code.

Allocate block

export proc allocate (int length) int

  • passed length - length of block to be allocated
  • returns block address
  1. This method is invoked by the Charm new operator.
  2. The block is allocated from the currently active allocator (pool or heap).
  3. Use this for smaller block allocations and heap_get_pages for larger allocations.
  4. If there is insufficient heap space to honour the request a runtime error will be generated. Re-run the program with a larger task memory allocation to avoid a recurrence of the problem.

Release block

export proc release (int block)

  • passed block - block to release
  1. This method is invoked by the Charm delete operator.
  2. The block must be released by the same allocator that created it (heap or pool).

Get pages

export proc get_pages (int pages, ref int za) ref Error

  • passed pages - number of 1Kb pages to be allocated
  •           za - set to pointer to allocated block
  • returns nil if successful
  1. The block is allocated from the heap.
  2. Use this for larger  for larger allocations and where the program wishes to retain control if an allocation error occurs.
  3. If there is insufficient heap space to honour the request an error will be returned. Re-run the program with a larger task memory allocation to avoid a recurrence of the problem.

Release pages

export proc rel_pages (int za) ref Error

  • passed za - allocated block pointer
  • returns nil if successful
  1. Use this to release pages allocated by get heap pages.

Memory copy

export proc copy (ref char zf, ref char zt, int length)

  • passed zf - start address
  •           zt - destination address
  •           length - length to copy
  1. Be sure there is sufficient space allocated at the to address to receive the required length.

Memory fill

export proc fill (ref char zf, char value, int length)

  • passed zf - start address
  •           value - fill value
  •           length - length to fill
  1. Usually the fill character will be 0 to zero memory. Be careful not to write beyond the size of the block being filled.

Memory compare

export proc compare (ref char zf, ref char zt, int length) boolean

  • passed zf - start address
  •           zt - destination address
  •           length - length to compare
  • returns true if all bytes match

.err


These procedures allow applications to create errors. See the Error module for further information.

OS

ref proc (ref Error.RiscOs |error|) ref Error os;

  • passed error - RISC OS error
  • returns error

User

ref proc (ref array char |zs|, int |code|) ref Error user;

  • passed zs - error message
  •           code - error code
  • returns error

Charm

ref proc (ref array char |zs|) ref Error charm;

  • passed zs - error message
  • returns error

  1. The error code is set to Error.CHARM.

Check return status

ref proc (ref Error.RiscOs |error|, ref array char |message|) check;

  • passed  error  -  RISC OS error
  •             message - error message

  1. If error is nil this call does nothing.
  2. If error is not nil then message is combined with it to produce an error which is generated with sufficient context to indicate the source of the problem. In this case the procedure does not return.

.convert


These procedures support type conversions between packed and real number representations.

Packed to Real

ref proc (ref array int |packed|) real pack_to_real;

  • passed packed - packed array (three integers)
  • returns floating point value of packed value

Real to Packed

ref proc (real |value|, ref array int |packed|) real_to_pack;

  • passed value - floating point value
  •           packed - packed array to receive packed value (three integers)

Real to Extended

ref proc (real |value|, ref array int |packed|) real_to_extended;

  • passed value - floating point value
  •             packed - array to receive extended (native) value (three integers)

Make a Free Website with Yola.