Latest revision as of 09:48, 22 June 2018

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.

• 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 tutorials index page.

This tutorial works through an example PAL program that creates graphs of the nexus. It requires the dot and unflatten 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 eog (Eye of GNOME).

Objectives

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

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

The gv_open() function takes a data 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 psStatUnix class should be added to them and the statMode 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 graphviz.pal, nxdump.pal and call_nxdump.pal, e.g.

$ prism -m graphviz nxdump call_nxdump

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

The call_nxdump.pal 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:

$ prose graphviz nxdump call_nxdump > nxdump.gv

This produces the Graphviz input file which we have called nxdump.gv. This can be converted straight into a .svg file with dot, 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 unflatten tool first as follows:

$ unflatten -l10 nxdump.gv | dot -Tsvg -o nxdump.svg

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

$ eog nxdump.svg

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

Graphing a filesystem hierarchy

As described in the ps_file(5) man page, PROSE can map a filesystem to a virtual branch in the nexus simply by adding a psFileHook object and setting the psFilePath 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 psFile class. When we add the psStatUnix class to any of these file objects then all the file attributes available to the stat() 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 gv_open() 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 graphviz.pal to display just the filenames.

You will need to assemble graphviz.pal, nxdump.pal, fslist.pal and call_fslist.pal, e.g.

$ prism -m graphviz nxdump fslist call_fslist

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

The code is run as follows:

$ prose graphviz nxdump fslist call_fslist > fslist.gv

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

$ unflatten -l10 fslist.gv | dot -Tsvg -o fslist.svg

Display the fslist.svg 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 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 man command, for example man pal_intro or man pal_commands, or from the Reference Manual Pages online.