View source for Objects, classes and attributes

= PAL Tutorial - Objects, classes and attributes =

In the current release, only the PROSE Assembly Language (PAL) is available. So be aware, it's very low-level programming at this time. To learn more about the PROSE Programming Language, visit http://prose.sourceforge.net.

It is suggested you begin with the following articles before attempting this tutorial.

:* [[Main Page|Introduction to PROSE]]
:* [[Quick start guide]]
:* [[Running your first program]]
:* [[Short tour of PAL]]

A full list of available tutorials for the PROSE Assembly Language can be found on the [[PAL tutorials|tutorials index page]].

This tutorial discusses objects, classes and attributes.

== Objects, schemas and modules ==

PROSE represents objects in the nexus using an LDAP-type schema. Objects can be given ''classes'', which describe the capabilities of each object (esp. which attributes can be assigned to them). For example, the <code>psContainer</code> class is used to mark an object that is used chiefly for structural purposes, like a directory in a filesystem. When the <code>psContainer</code> class is assigned to an object, the object must also be assigned a <code>pn</code> attribute and may optionally be given a <code>description</code> attribute too. The available classes are listed in the <code>ps_classes(5)</code> man page.

Objects also possess ''attributes''. An attribute has both a type and a value, so for example the <code>description</code> attribute is used for descriptive information and may have one or more values which contain the actual text of the description. The available attributes are listed in the <code>ps_attributes(5)</code> man page.

A set of strict rules are defined that describe which attributes may be used by which object classes. These attribute types will only then be available to objects in the nexus that have been assigned the appropriate classes. These rules are defined in a schema. However, at this time the PROSE engine ignores most schema rules, although does enforce the <code>SINGLE-VALUE</code> flag which indicates that an attribute may not be given multiple values. Also, read-only attributes are also enforced, as is the restriction that an object must have one and only one <code>STRUCTURAL</code> class assigned to it. Other schema rules will be enforced in a later release of the PROSE engine.

The PROSE schema is described in files that are the same format as an LDAP schema file. It is an extensible schema, and is currently read once at start-up. Any changes to the schema files will be picked up the next time you execute <code>prose</code>. The default location of the schema files is /usr/local/share/prose/schema, although a different location for the schema directory may be supplied via the <code>prose -s</code> option or the <code>PROSE_SCHEMADIR</code> environment variable.

Here are some example attribute and class definitions from the PROSE core schema file <code>00core.schema</code>:

<pre>
    attributetype ( 1.3.6.1.4.1.23780.1.2.1 NAME ( 'pn' 'psName' )
            DESC 'Name of PROSE node'
            SYNTAX 1.3.6.1.4.1.23780.1.3.1 )

    attributetype ( 2.5.4.13 NAME 'description'
            DESC 'RFC2256: descriptive information'
            EQUALITY caseIgnoreMatch
            SUBSTR caseIgnoreSubstringsMatch
            SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{1024} )

    objectclass ( 2.5.6.1 NAME 'top'
            DESC 'RFC2256: top'
            STRUCTURAL )

    objectclass ( 1.3.6.1.4.1.23780.1.1.1 NAME 'psContainer'
            DESC 'PROSE node metadata'
            SUP top STRUCTURAL
            MUST pn
            MAY description )
</pre>

The <code>pn</code> attribute is actually a ''virtual attribute''. All nodes in the nexus have this attribute, and it contains the name of the object. So, for example, the top-level node <code>.prose</code> will have a <code>pn</code> attribute of <code>prose</code>, while the <code>.prose.sys.io</code> object will have a <code>pn</code> attribute of <code>io</code>.

The <code>top</code> class is an ''implied class''. All nodes in the nexus have this class.

Attributes are given a ''syntax'', which identifies the module and code entry-point that handles requests to read or modify the attribute value. By default, modules are located in /usr/local/share/prose/modules and described in a collection of <code>.conf</code> files. A different location for the module directory may be supplied via the <code>prose -m</code> option or the <code>PROSE_MODULEDIR</code> environment variable.

The core module is described in the <code>ps_core.conf</code> file, and it is in this file that syntaxes and module entry points are described. Here are some example definitions in the core module configuration file:

<pre>
    name="ps_core" rev=1 desc="PROSE core support routines" cltrig="top";

    rule="caseIgnoreMatch" oid="2.5.13.2" type="equality";
    rule="caseExactMatch" oid="2.5.13.5" type="equality";
    rule="caseIgnoreOrderingMatch" oid="2.5.13.3" type="ordering";
    rule="caseIgnoreSubstringsMatch" oid="2.5.13.4" type="substr";

    syntax="1.3.6.1.4.1.1466.115.121.1.15"
            entrypoint="dirstring" desc="Directory String"
            attach_rule="caseIgnoreMatch"
            attach_rule="caseExactMatch"
            attach_rule="caseIgnoreSubstringsMatch"
            attach_rule="caseIgnoreOrderingMatch";
</pre>

A syntax may be associated with a number of rules. At this time PROSE ignores the rules, but in the future they will be used to modify the behaviour of the given syntax.

The schema, the modules, syntaxes and rules are mentioned here only as an overview. You do not need to understand these concepts for day-to-day use of PROSE or PAL. Schema files and modules should not need modification for normal use of PROSE. It only becomes necessary to supply modified schemas or new modules when extending the functionality of PROSE beyond that designed in the core product - an option open to the advanced programmer, and a feature that is beyond the scope of this tutorial.

== Examining some basic objects ==

Using the <code>obj/dump</code> command, one can examine some basic objects in the nexus. The topmost node is called <code>.prose</code> and can be displayed with the following code:

<pre>
    ._init
    func/def     [main], &[.main]
    local/rtn

    .main
    obj/dump     ![.prose]
    func/rtn
</pre>

The output will look much like this:

<pre>
    .prose:objectClass=psContainer
    .prose:objectClass=top
    .prose:objectClass=psRoot
    .prose:pn=[prose]
    .prose:psVersion=[0.11.0]
    .prose:psEnableExtraDebug=[FALSE]
    .prose:psWithMemWatch=[FALSE]
</pre>

From this you will see that the root of the nexus is an object that contains both the <code>psContainer</code> and <code>psRoot</code> classes as well as the <code>psVersion</code> attribute. It is therefore possible to determine the version of the running PROSE engine by looking for the <code>psVersion</code> attribute in the topmost node, like this:

<pre>
    attr/test ![.prose], [psVersion], [0.11.0]
</pre>

This instruction will set the <code>SCMP</code> register to 1 if the version is 0.11.0, otherwise the <code>SCMP</code> register will be set to 0.

Running <code>obj/dump ![-]</code> dumps the module root (this is the root of the current executing module). If your bytecode file was called <code>example.pro</code> the output would look like this:

<pre>
    .prose.code.default:objectClass=psContainer
    .prose.code.default:objectClass=top
    .prose.code.default:objectClass=psModule
    .prose.code.default:pn=[default]
    .prose.code.default:psObjectFileId=[example.pro]
</pre>

From this you will see that the module root uses the <code>psModule</code> class as well as the <code>psObjectFileId</code> attribute to identify that a) it is the root of a module and b) the name of the bytecode files which supplied the code for the module. There might be more than one file installing different functions within the module, as in the following example:

<pre>
    .prose.code.default:objectClass=psContainer
    .prose.code.default:objectClass=top
    .prose.code.default:objectClass=psModule
    .prose.code.default:pn=[default]
    .prose.code.default:psObjectFileId=[example1.pro]
    .prose.code.default:psObjectFileId=[example2.pro]
    .prose.code.default:psObjectFileId=[example3.pro]
</pre>

Here you will see that the <code>psObjectFileId</code> attribute is a multi-value attribute, i.e. it is permitted to have more than one value if necessary. Attributes that can only ever have one value are called single-value attributes.

Now run <code>reg/dump PCTX</code> at the top of a function. This displays the context root which is used to determine relative paths, i.e. when your path does not start with a dot. By default this register is set to point to the executing function when the function is first called, but the <code>PCTX</code> register can be changed to point to anything, as in the following example:

<pre>
    ._init
    func/def     [main], &[.main]
    func/def     [main.sub], &[.sub]
    local/rtn

    .main
    reg/dump     PCTX
    reg/load     PCTX, ![sub]
    reg/dump     PCTX
    func/rtn

    .sub
    func/rtn
</pre>

In the above example, two functions are defined. One will be set-up at <code>.prose.code.default.main</code> and the other in <code>.prose.code.default.main.sub</code>. When the <code>main</code> function is called, the <code>reg/dump</code> instruction will show you where it is pointing. Then it is changed to point to <code>sub</code> underneath the current position and dumped again. The output from this example is:

<pre>
    register: PCTX
    type: PSUNIT_TYPE_NODE (0x81)
    root: 0x839170 (global) nrefs: 4
    .prose.code.default.main

    register: PCTX
    type: PSUNIT_TYPE_NODE (0x81)
    root: 0x839170 (global) nrefs: 2
    .prose.code.default.main.sub
</pre>

Notice the difference between using <code>reg/dump</code> and <code>obj/dump</code> when debugging registers. The <code>reg/dump</code> instruction will display the type and value of a register. The <code>obj/dump</code> instruction displays information about the underlying object that the register is pointing to.

Add the following to the top of the previous example. This defines a data segment called <code>Module</code>, which is a reserved keyword used for redefining the name of the module:

<pre>
    ~Module
    EQUS {[loft.utils]}
</pre>

Replace the <code>reg/dump</code> instructions with <code>obj/dump</code>, assemble and re-execute. The result should be:

<pre>
    .prose.code.loft.utils.main:objectClass=psContainer
    .prose.code.loft.utils.main:objectClass=top
    .prose.code.loft.utils.main:objectClass=psFunction
    .prose.code.loft.utils.main:pn=[main]
    .prose.code.loft.utils.main:psObjectFileRd=[example.pro]
    .prose.code.loft.utils.main:psObjectCodeRef=[0x000b]
    .prose.code.loft.utils.main:psModuleRoot=[.prose.code.loft.utils]
    .prose.code.loft.utils.main.sub:objectClass=psContainer
    .prose.code.loft.utils.main.sub:objectClass=top
    .prose.code.loft.utils.main.sub:objectClass=psFunction
    .prose.code.loft.utils.main.sub:pn=[sub]
    .prose.code.loft.utils.main.sub:psObjectFileRd=[example.pro]
    .prose.code.loft.utils.main.sub:psObjectCodeRef=[0x0014]
    .prose.code.loft.utils.main.sub:psModuleRoot=[.prose.code.loft.utils]
</pre>

Here you see two objects, both functions. Function objects are identified by the <code>psFunction</code> class. They contain the <code>psObjectFileRd</code>, <code>psObjectCodeRef</code> and <code>psModuleRoot</code> attributes, which identify the binary file in which the function is defined, the code address within that bytecode where the function code begins and the module root for the function.

If you were to disassemble the bytecode using <code>prism -D30 -d example</code> you will see how the code addresses used by the <code>psObjectCodeRef</code> attributes tally with the assembly instructions:

<pre>
    $ prism -D30 -d example
    << Instruction code: 0x00001c >>
    << Code labels: 0x000035 >>
    << Code addresses: 0x00004a >>
    << Text segment: 0x000051 >>
    << Data labels: 0x000075 >>
    << Data addresses: 0x000080 >>
    << Data segment: 0x000085 >>
    ~Module
    EQUS { [loft.utils] }

    0x0000 : ._init
    0x0000 :   func/def      [main], &[.main]
    0x0005 :   func/def      [main.sub], &[.sub]
    0x000a :   local/rtn
    0x000b : .main
    0x000b :   obj/dump      PCTX
    0x000d :   reg/load      PCTX, ![sub]
    0x0011 :   obj/dump      PCTX
    0x0013 :   func/rtn
    0x0014 : .sub
    0x0014 :   func/rtn
</pre>

Running <code>obj/dump ![+]</code> dumps the instance container. This is where objects relating to a particular instance of a function reside. As functions may be called multiple times (recursively), each time it is called a new instance container is automatically created. Walkers are an example type of structure that are stored in the instance container. So let's create a couple of walkers before doing the dump:

<pre>
    ._init
    func/def     [main], &[.main]
    local/rtn

    .main
    reg/load     P0, (![.prose])
    reg/load     P1, (![.prose.code])
    obj/dump     ![+]
    func/rtn
</pre>

The output of the above program will be:

<pre>
    .prose.code.default.main._i0#0:objectClass=psContainer
    .prose.code.default.main._i0#0:objectClass=top
    .prose.code.default.main._i0#0:objectClass=psInstance
    .prose.code.default.main._i0#0:pn=[_i0#0]
    .prose.code.default.main._i0#0:psWalker=[.prose]
    .prose.code.default.main._i0#0:psWalker=[.prose.code]
</pre>

The name of the instance container is <code>_i0#0</code> where the first 0 is the thread ID (always 0 at this time as the PROSE engine is not yet multi-threaded), and the second 0 is the instance ID which will be incremented for each recursive call to the same function.

== Creating, modifying and deleting objects ==

Objects may be created and modified either by direct edits or by means of an edit buffer. Edit buffers are used when more than one operation is to be performed on an object. Commands are inserted into the buffer that will add, modify or delete classes and attributes. The edit buffer is then committed against an existing object, or a request is made to create a new object with the edit buffer. It is at the time the edit buffer is committed that the commands in the edit buffer are processed.

Edit buffers may be created from scratch or created based upon an existing object. Edit buffers themselves may also be cloned if multiple objects are to be created with similar properties.

Use the <code>obj/def</code> instruction to create a new edit buffer. This would be used when defining a new object. Then use <code>class/add</code> to add new object classes to the buffer. Use <code>attr/add</code> to add attributes with single values or <code>attr/mvadd</code> to add multi-value attributes. At this time you may then optionally use the <code>obj/clone</code> instruction to create a cloned edit buffer. Finally you will use <code>obj/commit</code> to create your new object. This is demonstrated in the following example:

<pre>
    ._init
    func/def     [main], &[.main]
    local/rtn

    .main
    obj/def      P0
    class/add    P0, [psContainer]
    attr/mvadd   P0, [description], [Description value 1], [Description value 2]
    obj/commit   [myobject], P0
    obj/dump     ![myobject]
    func/rtn
</pre>

The output of the above example is:

    .prose.code.default.main.myobject:objectClass=top
    .prose.code.default.main.myobject:objectClass=psContainer
    .prose.code.default.main.myobject:pn=[myobject]
    .prose.code.default.main.myobject:description=[Description value 1]
    .prose.code.default.main.myobject:description=[Description value 2]

Use the <code>obj/edit</code> instruction to create a new edit buffer intended to be used for editing a specific object. Then use the <code>class</code> and <code>attr</code> instructions to add, modify or delete classes or attributes in the buffer. At this time you may then optionally use the <code>obj/clone</code> instruction to create a cloned edit buffer. Finally you will use <code>obj/commit</code> to create your new object. Add the following code to the previous example, immediately before <code>obj/dump</code>:

<pre>
    obj/edit     P0, ![myobject]
    attr/mvadd   P0, [description], [Description value 3]
    obj/commit   P0
</pre>

When using <code>obj/edit</code> as above, the <code>obj/commit</code> instruction requires only one argument because a record of which object was being edited is kept in the edit buffer. The output should now be:

<pre>
    .prose.code.default.main.myobject:objectClass=top
    .prose.code.default.main.myobject:objectClass=psContainer
    .prose.code.default.main.myobject:pn=[myobject]
    .prose.code.default.main.myobject:description=[Description value 1]
    .prose.code.default.main.myobject:description=[Description value 2]
    .prose.code.default.main.myobject:description=[Description value 3]
</pre>

The <code>obj/clone</code> instruction may also be used to create an edit buffer that will be pre-populated with the commands needed to create another identical object. This edit buffer may then be committed over an existing or new object using <code>obj/commit</code>, which will replay a list of ''class add'' and ''attribute add'' commands. Add the following code to the previous example, immediately before <code>func/rtn</code>:

<pre>
    obj/clone    P0, ![myobject]
    obj/commit   [myobject2], P0
    obj/dump     ![myobject2]
</pre>

The output should now be:

<pre>
    .prose.code.default.main.myobject:objectClass=top
    .prose.code.default.main.myobject:objectClass=psContainer
    .prose.code.default.main.myobject:pn=[myobject]
    .prose.code.default.main.myobject:description=[Description value 1]
    .prose.code.default.main.myobject:description=[Description value 2]
    .prose.code.default.main.myobject:description=[Description value 3]
    .prose.code.default.main.myobject2:objectClass=top
    .prose.code.default.main.myobject2:objectClass=psContainer
    .prose.code.default.main.myobject2:pn=[myobject2]
    .prose.code.default.main.myobject2:description=[Description value 1]
    .prose.code.default.main.myobject2:description=[Description value 2]
    .prose.code.default.main.myobject2:description=[Description value 3]
</pre>

Finally, objects are deleted using <code>obj/del</code>. Add the following to the end of the previous example, immediately before <code>func/rtn</code>:

<pre>
    obj/del      ![myobject], ![myobject2]
    obj/dump     ![myobject], ![myobject2]
</pre>

You should now receive an error that the object referenced by the final <code>obj/dump</code> cannot be found:

<pre>
    .prose.code.default.main.myobject:objectClass=top
    .prose.code.default.main.myobject:objectClass=psContainer
    .prose.code.default.main.myobject:pn=[myobject]
    .prose.code.default.main.myobject:description=[Description value 1]
    .prose.code.default.main.myobject:description=[Description value 2]
    .prose.code.default.main.myobject:description=[Description value 3]
    .prose.code.default.main.myobject2:objectClass=top
    .prose.code.default.main.myobject2:objectClass=psContainer
    .prose.code.default.main.myobject2:pn=[myobject2]
    .prose.code.default.main.myobject2:description=[Description value 1]
    .prose.code.default.main.myobject2:description=[Description value 2]
    .prose.code.default.main.myobject2:description=[Description value 3]
    * prose.error.sys.NoEntry: No such entry or object
    * Can't lookup object reference: myobject
    *    at default.main()                      [testobj.pro, addr 0x0039]
    *    in prose.code._tid.0
</pre>

== Resources from this tutorial ==

:* [[Source code: testobj.pal]]

== Further reading ==

See the other tutorials available for the PROSE Assembly Language on the [[PAL tutorials|tutorials index page]].

PROSE is released with detailed manual pages that describe how PAL operates, and how each instruction is used. These manual pages can be read using the <code>man</code> command, for example <code>man pal_intro</code> or <code>man pal_commands</code>, or from the [http://prose.sourceforge.net/man Reference Manual Pages] online.