Charm Runtime Library (rtl) 


The Charm runtime library is required for the running of a Charm program.

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

.file
.dir
.heap
.parse

file handling
directory handling
heap information
command line parsing

which are described further below, as well as root level procedures for program execution control, command line parsing etc:

 Set jump label
export proc set_label ()

  1. Sets a global label that can be jumped directly to.

 Jump to label
export proc jump_label ()

  1. Jumps directly to a global label.
  2. A global label must have been previously set.
  3. The activation frame of the procedure setting the global label must still be on the stack.
  4. Use this call with caution; if the label is not valid then the results are undefined.

Hash string
export proc hash (ref array char zn, int len) int
  • passed zn - string
  •             len - returned value must lie within range 0 to len-1 inclusive
  • returns string hash value
  1. Useful for map implementations keyed by strings.
Check for 32 bit ARM processor
export proc check_ARM32 () boolean
  • returns true if running on a 32 bit ARM processor and false otherwise
  1. Useful for checking if 32 bit operations are available.

.file

These procedures allow applications to access and manage files.

Get file type


ref proc (ref array char |filename|) int get_type;

  • passed filename - filename
  • returns file type of file (CI_NOT_FOUND not found, CI_FILE file, CI_DIRECTORY directory, CI_APPLICATION application)

Set file type

ref proc (ref array char |file|, int |type|) set_type;
  • passed file - filename
  •            type - file type

Delete file

ref proc (ref array char |filename|) delete_file;
  • passed filename - filename of file to be deleted

Get catalogue info

ref proc (ref array char |filename|) int get_catalogue_info;

  • passed filename - filename
  • returns catalogue information for file (C_CI_NOT_FOUND not found, C_CI_FILE file, C_CI_DIRECTORY directory, C_CI_IMAGE application directory)

.dir

These procedures allow applications to access and manage files directories.

Set current directory

ref proc (ref array char |dir|) set;
  • passed dir - directory name
  1. this is equivalent to issuing a RISC OS dir command

Get entry

ref proc (ref array char |dir|, ref array char |file|, ref int |entry|) ref String get_entry;

  • passed dir - directory name
  •             file - filename
  •             entry - current entry
  • returns file entry or nil if none
  1. Ensure the first value of entry is 0.
  2. In order to obtain all entries, iterate until entry is -1.

Create directory

ref proc (ref array char |dir|) ref ErrMsg create;
  • passed dir - directory name
  • returns nil if successful or an error descriptor if not
.heap


These procedures allow applications to obtain information about the heap.

Get heap space

ref proc () int get_space;

  • returns the amount of space remaining in the heap in bytes
  1. It is still possible that a heap allocation will fail even if there appears to be sufficient space returned by this call since heap block allocations must return contiguous bytes, and the heap may have become fragmented.

Get heap start

ref proc () int get_start;

  • returns the start address of the heap
  1. This call is only really useful for debugging purposes, and is used by the debug module when performing a heap dump.

Get heap size

ref proc () int get_size;

  • returns the size of the heap in bytes
  1. This is dependent on the next WimpSlot size. It cannot be changed once a program has started.

.parse


These procedures allow applications to parse their command line arguments.

Parse command line arguments

ref proc (ref array ref array char argv, ref array Switch switches, int count)
              ref array ref array char 
arguments;

  • passed argv - array of command line arguments terminated with a nil last entry
  •             switches - array of command line switch descriptors
  •             count - number of entries in switch descriptors array
  • returns  array of command line arguments with switches removed (i.e. positional only)
  1. See the section on program startup and termination under the main runtime page for details of the Switch record and how to use it

Make a Free Website with Yola.