Index | PAL Intro | Commands | Registers | Indices | Stack | Macros | Classes | Attributes | Errors

pal_commands - Introduction to PAL commands

CONTENTS

Pre-requisite Reading
Description
Error Handling
Global Commands
Stack Commands
Object Commands
Class Commands
Attribute Commands
Variable Commands
Matrix Commands
Tree Commands
Maths Operations
Error Commands
List Sequence Commands
Function Commands
Local Commands
Register Commands
Debug Commands
Conditional Tags
See Also
Author

Please see pal_intro(5) for a general description of PAL.

PAL commands are loosely separated into functional areas, identified by a word followed by the slash / character. The word following the slash character identifies the command itself. This reference page provides a list of all commands, and the name of the reference page where a full description of the command is located.

Arguments to commands can be registers or indices. Registers are described in pal_registers(5), and indices in pal_indices(5). A list of available registers and indices are also reported by the ’prism -l’ command.

Arguments are described as read arguments and write arguments. A read argument is one from which data will be read, and can usually be any valid argument. A write argument is one into which data will be written, and is typically a register.

There is generally one manual page per PAL command, and each page provides the name, a brief synopsis, a description, often some example code and a list of other related commands. The synopsis lists the valid arguments that may be passed to the instruction. Where arguments can be repeated, they appear inside chevrons with an ellipsis, like this:

<, arg1, arg2 ... >

meaning that arg1 and arg2 may be provided multiple times.

Programmatical errors are reported at compile-time wherever possible. However, when errors cannot be caught at compile-time, on these occasions runtime errors may be generated.

A number of runtime errors can be triggered almost universally by any instruction. System errors such as device or memory allocation errors are examples of these.

Each command reference page describes additional conditions that cause a runtime error. A runtime error will cause the current program execution thread to terminate unless it has been caught by the error/jmp instruction. Registers will normally be preserved when an error occurs, and PERR will be set to point to the error type.

The following commands are not categorised by functional area:

noop	No operation. This command and any arguments, if given, are ignored at runtime. See pal_noop(5).

The following commands operate on the program stack:

stack/push
	Push data onto program stack. See stack_push(5).
stack/pull
	Pull data from program stack. See stack_pull(5).
stack/lock
	Lock program stack. See stack_lock(5).
stack/unlock
	Unlock program stack. See stack_unlock(5).
stack/flush
	Flush program stack up to last lock. See stack_flush(5).

The following commands operate on objects:

obj/def
	Define new object edit buffer. See obj_def(5).
obj/clone
	Define new object edit buffer and fill with edit commands that would make a clone of an existing nexus object or another edit buffer. See obj_clone(5).
obj/edit
	Define new object edit buffer and associate with an existing nexus object. See obj_edit(5).
obj/commit
	Commit changes described in an object edit buffer to a new or existing nexus object. See obj_commit(5).
obj/commitref
	Commit changes described in an object edit buffer to a new or existing nexus object, returning a pointer to the new or modified node. See obj_commitref(5).
obj/del
	Delete a nexus object. See obj_del(5).
obj/addr
	Lookup a nexus object by piecing together path components. See obj_addr(5).
obj/pa
	Lookup a parent object. See obj_pa(5).
obj/child
	Lookup a child object. See obj_child(5).
obj/dump
	Debug object. See obj_dump(5).
obj/cmp
	Compare attribute values assigned to a pair of objects. See obj_cmp(5).

The following commands operate on object classes:

class/add
	Add a class directly, or insert a class add instruction into an object edit buffer. See class_add(5).
class/del
	Delete a class directly, or insert a class delete instruction into an object edit buffer. See class_del(5).
class/load
	Load an object class definition from the schema into a register, or iterate class assignments. See class_load(5).
class/test
	Test an object for a list of classes. See class_test(5).

The following commands operate on object attributes:

attr/def
	Define encoded data value. See attr_def(5).
attr/add
	Add an attribute directly, or insert an attribute add instruction into an object edit buffer. See attr_add(5).
attr/del
	Delete an attribute directly, or insert an attribute delete instruction into an object edit buffer. See attr_del(5).
attr/mod
	Modify an attribute directly, or insert an attribute modify instruction into an object edit buffer. See attr_mod(5).
attr/mvadd
	Add multiple attribute values directly, or insert a multi-value attribute add instruction into an object edit buffer. See attr_mvadd(5).
attr/mvdel
	Delete multiple attribute values directly, or insert a multi-value attribute delete instruction into an object edit buffer. See attr_mvdel(5).
attr/mvmod
	Modify multiple attribute values directly, or insert a multi-value attribute modify instruction into an object edit buffer. See attr_mvmod(5).
attr/copy
	Copies attribute values into registers. See attr_copy(5).
attr/xcopy
	Copies encoded attribute values into registers. See attr_xcopy(5).
attr/export
	Exports attribute value in binary form. See attr_export(5).
attr/import
	Imports attribute value from binary form into encoded data value. See attr_import(5).
attr/xconv
	Convert between register type and encoded data. See attr_xconv(5).
attr/direct
	Copies attribute values directly from one object to another. See attr_direct(5).
attr/index
	Copy attribute value as a raw index. See attr_index(5).
attr/addr
	Copy attribute value as a node pointer. See attr_addr(5).
attr/load
	Load an object attribute definition from the schema into a register, or iterate attribute assignments. See attr_load(5).
attr/test
	Test an object for a list of attributes or values. See attr_test(5).
attr/mvtest
	Test an object for a list of multiple attribute values. See attr_mvtest(5).
attr/cmp
	Compare two attribute values. See attr_cmp(5).

The following commands operate on variable objects:

var/def
	Define a new variable at a given position in the nexus. See var_def(5).
var/local
	Define a new variable with local scope. See var_local(5).
var/static
	Define a new static variable at the function level. See var_static(5).
var/global
	Define a new global variable at the module level. See var_global(5).
var/addr
	Lookup a variable object given its name. See var_addr(5).

The following commands operate on matrix arrays:

mtx/def
	Define a new matrix array at a given position in the nexus. See mtx_def(5).
mtx/local
	Define a new matrix array with local scope. See mtx_local(5).
mtx/static
	Define a new static matrix array at the function level. See mtx_static(5).
mtx/global
	Define a new global matrix array at the module level. See mtx_global(5).
mtx/size
	Return matrix array dimensions. See mtx_size(5).
mtx/bsize
	Return matrix base array dimensions. See mtx_bsize(5).
mtx/dim
	Return matrix array and base dimensions in two list sequences. See mtx_dim(5).
mtx/resize
	Resize matrix array dimensions. See mtx_resize(5).
mtx/bresize
	Resize matrix array base dimensions. See mtx_bresize(5).
mtx/set
	Set element value inside a matrix array. See mtx_set(5).
mtx/get
	Get element value from a matrix array. See mtx_get(5).

The following commands operate on tree arrays:

tree/clone
	Clone child objects to a new location. See tree_clone(5).
tree/bclone
	Clone base object and its children to a new location. See tree_bclone(5).
tree/del
	Delete nodes and all of their child objects. See tree_del(5).
itree/def
	Define a new imploded tree array at a given position in the nexus. See itree_def(5).
itree/local
	Define a new imploded tree array with local scope. See itree_local(5).
itree/static
	Define a new imploded tree array at the function level. See itree_static(5).
itree/global
	Define a new imploded tree array at the module level. See itree_global(5).
itree/bdef
	Define a new imploded tree array at a given position in the nexus and also set the psTreeRoot attribute to TRUE. See itree_bdef(5).
itree/blocal
	Define a new imploded tree array with local scope and also set the psTreeRoot attribute to TRUE. See itree_blocal(5).
itree/bstatic
	Define a new imploded tree array at the function level and also set the psTreeRoot attribute to TRUE. See itree_bstatic(5).
itree/bglobal
	Define a new imploded tree array at the module level and also set the psTreeRoot attribute to TRUE. See itree_bglobal(5).
itree/addr
	Lookup the address of a given path within an imploded tree array. See itree_addr(5).
itree/set
	Set a variable within a given path within an imploded tree array. See itree_set(5).
itree/xconv
	Convert an exploded tree array to an imploded tree array. See itree_xconv(5).
xtree/def
	Define a new exploded tree array at a given position in the nexus. See xtree_def(5).
xtree/local
	Define a new exploded tree array with local scope. See xtree_local(5).
xtree/static
	Define a new exploded tree array at the function level. See xtree_static(5).
xtree/global
	Define a new exploded tree array at the module level. See xtree_global(5).
xtree/bdef
	Define a new exploded tree array at a given position in the nexus and also set the psTreeRoot attribute to TRUE. See xtree_bdef(5).
xtree/blocal
	Define a new exploded tree array with local scope and also set the psTreeRoot attribute to TRUE. See xtree_blocal(5).
xtree/bstatic
	Define a new exploded tree array at the function level and also set the psTreeRoot attribute to TRUE. See xtree_bstatic(5).
xtree/bglobal
	Define a new exploded tree array at the module level and also set the psTreeRoot attribute to TRUE. See xtree_bglobal(5).
xtree/addr
	Lookup the address of a given path within an exploded tree array. See xtree_addr(5).
xtree/set
	Set a variable within a given path within an exploded tree array. See xtree_set(5).
xtree/iconv
	Convert an imploded tree array to an exploded tree array. See xtree_iconv(5).

The following commands perform increment/decrement operations and are described in the op_incr(5) manual page.

op/incr	Increment numeric components by a value of 1.
op/decr	Decrement numeric components by a value of 1.
The following commands perform basic maths operations and store their result as a raw index. They are described in the op_maths(5) manual page.
op/add	Add numeric components.
op/sub	Subtract numeric components.
op/mult	Multiply numeric components.
op/div	Divide numeric components.
op/mod	Calculate the remainder.
op/not	Bitwise NOT.
op/and	Bitwise AND.
op/or	Bitwise OR.
op/xor	Bitwise exclusive OR.
op/shl	Bitwise shift left.
op/shr	Bitwise shift right.
op/rol	Bitwise rotate left.
op/ror	Bitwise rotate right.
The following commands perform basic maths operations on the Accumulator. They are described in the opa_maths(5) manual page.
opa/add	Add numeric values to Accumulator.
opa/sub	Subtract numeric values from Accumulator.
opa/mult	Multiply Accumulator by numeric values.
opa/div	Divide Accumulator by numeric values.
opa/mod	Calculate the remainder with Accumulator.
opa/not	Bitwise NOT with Accumulator.
opa/and	Bitwise AND with Accumulator.
opa/or	Bitwise OR with Accumulator.
opa/xor	Bitwise exclusive OR with Accumulator.
opa/shl	Bitwise shift left with Accumulator.
opa/shr	Bitwise shift right with Accumulator.
opa/rol	Bitwise rotate left with Accumulator.
opa/ror	Bitwise rotate right with Accumulator.
The following commands perform basic maths operations and store their result in an existing variable object. They are described in the opo_maths(5) manual page.
opo/add	Add numeric components.
opo/sub	Subtract numeric components.
opo/mult	Multiply numeric components.
opo/div	Divide numeric components.
opo/mod	Calculate the remainder.
opo/not	Bitwise NOT.
opo/and	Bitwise AND.
opo/or	Bitwise OR.
opo/xor	Bitwise exclusive OR.
opo/shl	Bitwise shift left.
opo/shr	Bitwise shift right.
opo/rol	Bitwise rotate left.
opo/ror	Bitwise rotate right.
The following commands perform basic maths operations and store their result as an encoded attribute value. They are described in the opx_maths(5) manual page.
opx/add	Add numeric components.
opx/sub	Subtract numeric components.
opx/mult	Multiply numeric components.
opx/div	Divide numeric components.
opx/mod	Calculate the remainder.
opx/not	Bitwise NOT.
opx/and	Bitwise AND.
opx/or	Bitwise OR.
opx/xor	Bitwise exclusive OR.
opx/shl	Bitwise shift left.
opx/shr	Bitwise shift right.
opx/rol	Bitwise rotate left.
opx/ror	Bitwise rotate right.

The remaining instructions in this group perform other miscellaneous maths operations:

op/mask
	Generate a 32-bit mask. See op_mask(5).
op/swap
	Swap bytes. See op_swap(5).

The following commands operate on error objects:

error/def
	Define a new error type. See error_def(5).
error/now
	Generate a new error condition. See error_now(5).
error/jmp
	Adds/removes error handlers. See error_jmp(5).
error/clr
	Clear existing error condition. See error_clr(5).

The following commands operate on list sequences:

list/def
	Define a list sequence. See list_def(5).

The following commands operate on program functions:

func/def
	Define a function. See func_def(5).
func/call
	Execute a function, zeroing registers. See func_call(5).
func/bcall
	Execute a function, saving and restoring registers. See func_bcall(5).
func/rtn
	Return from a function. See func_rtn(5).
func/addr
	Lookup a function object given its name. See func_addr(5).

The following commands operate on the local program pointer:

local/jmp
	Jump to code. See local_jmp(5).
local/jsr
	Branch to code. See local_jsr(5).
local/rtn
	Return from code branch. See local_rtn(5).

The following commands operate on registers:

reg/load
	Loads data into registers. See reg_load(5).
reg/xload
	Read length of text string. See reg_xload(5).
reg/save
	Modify sections of text or byte strings. See reg_save(5).
reg/copy
	Copy or concatenate text arguments. See reg_copy(5).
reg/conv
	Convert between raw indices and strings. See reg_conv(5).
reg/move
	Move data between registers. See reg_move(5).
reg/type
	Load the register type. See reg_type(5).
reg/jmpeq
	Jump to code if comparison is equal. See reg_jmpeq(5).
reg/jmpne
	Jump to code if comparison is not equal. See reg_jmpne(5).
reg/jmpge
	Jump to code if comparison is greater than or equal to. See reg_jmpge(5).
reg/jmpgt
	Jump to code if comparison is greater than. See reg_jmpgt(5).
reg/jmple
	Jump to code if comparison is less than or equal to. See reg_jmple(5).
reg/jmplt
	Jump to code if comparison is less than. See reg_jmplt(5).
reg/jsreq
	Branch to code if comparison is equal. See reg_jsreq(5).
reg/jsrne
	Branch to code if comparison is not equal. See reg_jsrne(5).
reg/jsrge
	Branch to code if comparison is greater than or equal to. See reg_jsrge(5).
reg/jsrgt
	Branch to code if comparison is greater than. See reg_jsrgt(5).
reg/jsrle
	Branch to code if comparison is less than or equal to. See reg_jsrle(5).
reg/jsrlt
	Branch to code if comparison is less than. See reg_jsrlt(5).
reg/dump
	Debug register. See reg_dump(5).
reg/clr
	Safely clear the contents of a list of registers. See reg_clr(5).
reg/index
	Read internal data table index number. reg_index(5).
reg/cmp
	Compare registers. See reg_cmp(5).
reg/lcmp
	Rolling left comparison. See reg_lcmp(5).
reg/rcmp
	Rolling right comparison. See reg_rcmp(5).
reg/roll
	Roll groups of registers left or right. See reg_roll(5).
reg/xscan
	Search text or byte strings. See reg_xscan(5).

The following commands are used for debugging:

debug/source
	Define source file and source line data for stack traces and debuggers. See debug_source(5).
debug/level
	Set debug level. See debug_level(5).

An instruction may have one or more conditional tags prepended to it. If one of the conditions are met, the instruction is executed as normal. If none of the conditions are met, the instruction will be bypassed and the program pointer will move onto the next instruction.

The conditions are determined in the same way as the reg/jmpeq instruction in its single argument form, by evaluating the current value of the SCMP register.

The conditional tags are:

eq:	Execute instruction if last test was equal.
ne:	Execute instruction if last test was not equal.
lt:	Execute instruction if last test was less than.
le:	Execute instruction if last test was less than or equal to.
gt:	Execute instruction if last test was greater than.
ge:	Execute instruction if last test was greater than or equal to.

pal_intro(5), pal_registers(5), pal_indices(5), pal_stack(5), ps_matrix(5), ps_tree(5), ps_file(5), ps_stream(5), ps_time(5), prism(1),
PROSE Assembly Language at prose.sourceforge.net.

Copyright (c) 2002-2018 Mark R. Bannister <cambridge@users.sourceforge.net>.

This is free software and can be downloaded from prose.sourceforge.net; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.