View source for Plotting graphs from the nexus

= PAL Tutorial - Plotting graphs from the nexus =

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 works through an example PAL program that creates graphs of the nexus.  It requires the <code>dot</code> and <code>unflatten</code> tools from Graphviz, see http://www.graphviz.org.  The program creates SVG files which will need to be displayed in an image viewer, for example <code>eog</code> (Eye of GNOME).

== Objectives ==

The Graphviz PAL program provides a number of functions that can be used within other PAL programs to generate a <code>.gv</code> file from objects in the nexus that Graphviz can then render into a directed graph with <code>dot</code>.

The functions it provides are <code>gv_open()</code> which generates the necessary opening stanza, <code>gv_add_node()</code> which adds a node and its children to the graph and <code>gv_close()</code> that generates the required closing stanza.  The output is sent to <code>stdout</code> which is normally redirected to a file and then passed to <code>dot</code> (optionally via the <code>unflatten</code> tool) to produce a resulting <code>.svg</code> file.  This is a vector graphics format that can be viewed in various image rendering programs including Eye of Gnome (<code>eog</code>).

The <code>gv_open()</code> function takes a <code>data</code> argument that indicates if any data associated with each node should be included in the graph.  A value of 0 requests that just the node name is displayed, if 1 then the list of object classes associated with the node will be included, if 2 then additionally the list of attribute types and their values will also be displayed, while 3 is the same as 2 but also indicates that if any file objects are added then the <code>psStatUnix</code> class should be added to them and the <code>statMode</code> attribute must be displayed in octal.

== Getting graphs from branches in the nexus ==

http://prose.sourceforge.net/graphics/nxdump-with-graphviz.jpg

To produce a graph of every node in the nexus, you need to assemble <code>graphviz.pal</code>, <code>nxdump.pal</code> and <code>call_nxdump.pal</code>, e.g.

<pre>
$ prism -m graphviz nxdump call_nxdump
</pre>

The <code>gv_open()</code>, <code>gv_add_node()</code> and <code>gv_close()</code> functions are defined in <code>graphviz.pal</code> and called from <code>nxdump.pal</code> and <code>call_nxdump.pal</code>.

The <code>call_nxdump.pal</code> program has been set-up to dump all nodes from the top of the nexus and to display all classes and attributes, but this may be easily changed.  The code is run as follows:

<pre>
$ prose graphviz nxdump call_nxdump > nxdump.gv
</pre>

This produces the Graphviz input file which we have called <code>nxdump.gv</code>.  This can be converted straight into a <code>.svg</code> file with <code>dot</code>, although the resulting graph will be very wide due to the number of nodes in some of the branches.  I have therefore been running through the <code>unflatten</code> tool first as follows:

<pre>
$ unflatten -l10 nxdump.gv | dot -Tsvg -o nxdump.svg
</pre>

The resulting vector graphics file can be viewed in Eye of Gnome as follows:

<pre>
$ eog nxdump.svg
</pre>

or you may use any other image viewer that supports the format.

== Graphing a filesystem hierarchy ==

As described in the <code>ps_file(5)</code> man page, PROSE can map a filesystem to a virtual branch in the nexus simply by adding a <code>psFileHook</code> object and setting the <code>psFilePath</code> attribute.  Then when child nodes are enumerated, the files on the filesystem underneath the given path are represented by virtual nodes on the nexus that have the <code>psFile</code> class.  When we add the <code>psStatUnix</code> class to any of these file objects then all the file attributes available to the <code>stat()</code> system call are exposed as LDAP attributes associated with that object which may be read or written in the usual way, for example the owner and group, the file permissions, the modification time and the file size.

Coupled with the Graphviz program, we can then produce graphs like this:

http://prose.sourceforge.net/graphics/fslist-with-graphviz.jpg

As before we can change the parameter we send to the <code>gv_open()</code> function in order to change the level of detail, for example we could reduce the size of each node in the graph by excluding the object classes and attributes leaving just the node names.  You could also customise <code>graphviz.pal</code> to display just the filenames.

You will need to assemble <code>graphviz.pal</code>, <code>nxdump.pal</code>, <code>fslist.pal</code> and <code>call_fslist.pal</code>, e.g.

<pre>
$ prism -m graphviz nxdump fslist call_fslist
</pre>

You may modify <code>call_fslist.pal</code> to choose the path under which nodes will be enumerated, which is currently set to <code>/etc</code>.

The code is run as follows:

<pre>
$ prose graphviz nxdump fslist call_fslist > fslist.gv
</pre>

This produces the Graphviz input file which we have called <code>fslist.gv</code>.  This can be converted straight into a <code>.svg</code> file with <code>dot</code>, although as before you will probably want to <code>unflatten</code> the graph first as follows:

<pre>
$ unflatten -l10 fslist.gv | dot -Tsvg -o fslist.svg
</pre>

Display the <code>fslist.svg</code> vector graphics image as before.

== Resources from this tutorial ==

:* [[Graphviz code: graphviz.pal]]
:* [[Graphviz code: nxdump.pal]]
:* [[Graphviz code: call_nxdump.pal]]
:* [[Graphviz code: fslist.pal]]
:* [[Graphviz code: call_fslist.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.