overview

libmsgque was designed to act as a glue between different applications. For an overview about the basic concepts we are using the good old shell and using libmsgque to extend the usability of the well known pipe '|' syntax.

basic shell behaviour

A shell command-line is a collection of one or more commands linked together using the '|' symbol:

command1 | command2 | command3

command1, command2 and command3 are started by the shell and the stdout of command1 is the stdin of command2 and the stdout of command2 is the stdin of command3. The data send through the pipeline are strings and every command in the pipeline have to parse the string output of the previous command to extract the information's needed.

• advantage:
  • easy to use and human readable interface based on strings
• disadvantage:
  • every command has to re-parse the output of the previous command

additional shell behaviour using the libmsgque syntax

libmsgque is adding an additional link character '@' to the shell and the example from above looks like this:

alfacmd1 @ alfacmd2 @ alfacmd3

Only alfacmd1 is started by the shell and gets '@ alfacmd2 @ alfacmd3' as command-line arguments. libmsgque will start the both commands alfacmd2 and alfacmd3 and setup the message-queues:

1. alfacmd1 -> alfacmd2
2. alfacmd2 -> alfacmd3

Alfacmd2 receiving the output from alfacmd1 and alfacmd3 receiving the output from alfacmd2 without re-parsing the data again.

• advantage:
  • single parsing of output and direct access to columns and rows
  • the alfacmdX commands are independent processes and only connected by message queues
• disadvantage:
  • every command using the alfa syntax have to use the libmsgque library

interface between shell commands and alfa commands

For full integration of alfa commands into the shell syntax 2 additional interfaces are necessary

• advantage:
  • direct integration between shell and alfa commands
  • reusing of already available shell commands and adding new features by alfa commands

interface: shellcmd | alfacmd

To connect a shell with an alfa command the special alfa command asplit is used:

    shellcmd | asplit @...

The asplit tool expect input data from stdin and is sending output data as package to an alfa command. For every input data string an output package is created by splitting the input string into output objects using the the delimiter -d.

interface: alfacmd | shellcmd

To connect an alfa with a shell command the special alfa command ajoin is used:

    ...@ ajoin | shellcmd

The ajoin tool expect data from a msgque client as input and create for every input package an stdout output string by joining the objects of the input package together using the delimiter -d .

command pipelines using multiple hosts

starthost:     alfacmd1 --tcp --inetd --host endhost --port myport
endhost:       alfacmd2 --tcp --port myport

By default libmsgque is using unix-domain sockets (UDS) for communication but inet (TCP) sockets can be used as well. The data-flow is the same as above except that two hosts are involved using libmsgque over tcp sockets for connection. The tcp connection is buildup between alfacmd1 and alfacmd2.

• advantage:
  • multiple hosts can be used

a collection of examples should help to understand the software

exmaple: this is a list of commands allready available in the distribution

• usage: asplit
• usage: ajoin
• usage: acut
• usage: asort
• usage: aexec
• usage: astarter

example 1 : just the famous hello world example

echo 'hello world with text' | asplit -d " " @ acut -f 0,1 @ ajoin -D ":"

return: hello:world

example 2 : a little bit more features used

echo -e 'nobody 10 euro\nmanager 1000 dollar\nworker 100 pound' | \
    asplit -d " " @ asort -1 D @ ajoin -d " : " -0 "position -> %-8s" \
        -1 "amount = %7.2f" -2 "%s"

with the output:

position -> nobody   : amount =   10.00 : euro
position -> worker   : amount =  100.00 : pound
position -> manager  : amount = 1000.00 : dollar

example 3 : use tcl to create a smart filter

The following tcl code total.tcl does 2 things:

1. convert the currencies into dollar ($)
2. calculate the total amout

package require TclMsgque
set total 0
proc FTR {ctx} {
    foreach {position amount currency} [$ctx read] break
    switch -exact $currency {
	euro    {set exchange 1.3541}
	pound   {set exchange 1.9896}
	default {set exchange 1}
    }
    set amout [expr {$amount * $exchange}]
    set currency dollar
    set ::total [expr {$::total + $amout}]
    $ctx send -type _FTR -str $position -dbl $amout
}
proc EOF {ctx} {
    $ctx send -type _FTR -str total -dbl $::total
}
[msgque create [concat --server --filter --name total.tcl \
    --FTRproc FTR --EOFproc EOF $argv]] processEvent

using the following command pipeline:

echo -e 'nobody 10 euro\nmanager 1000 dollar\nworker 100 pound' | \
    asplit -d " " @ asort -1 D @ tclsh total.tcl @ \
	ajoin -d " : " -0 "%-8s" -1 "%5.2f$"

to create the following result:

nobody   : 13.54$
worker   : 198.96$
manager  : 1000.00$
total    : 1212.50$

example 4 : use the debug mode

echo -e 'nobody 10 euro\nmanager 1000 dollar\nworker 100 pound' | \
    asplit --debug 5 -d " " @ asort -1 D @ ajoin -d " : " -0 "position -> %-8s" \
        -1 "amount = %7.2f" -2 "%s"

to create the debug output

example 5 : build an aexec server

to setup s server to serve some configurations files use the following commands:

/path/to/astarter 7487 /path/to/aexec put @ HOST cat /etc/hosts @ SERV cat /etc/services

to call one of the services above use the following commands:

/path/to/aexec get --host serverHost --port 7487 @ HOST

---