As the examples in the introcuction show, the "xmlmod" suite comes in two flavours. The first is as the "xmlproc" command that can be used to manipulate an XML command, the second is the trio "xmlopen", "xmlcmd" and "xmlclose" that is used for closer interaction with shell scripts.
To start with the "xmlproc" command. The syntax of this is..
xmlproc [file_name] xmlcommand args... [{xmlcommand args...}...]
This creates an XML "session", processes some commands then discards the "session" all in one command.
The file name is optional, but usually included. It is the file that is initially loaded. The xmlcommand(s) and their respective "args" examine and manipulate the XML data and is covered in it.s own section. Their can be as many xmlcommands in the command as necessary.
If all the individual XML commands execute successfully (return 0) then xmlproc will return 0. If any fail it will return the number of XML commands that fail (or return non zero).
The trio of "xmlopen", "xmlcmd" and "xmlclose" works as follows:
HANDLE=`xmlopen [file_name]`
xmlcmd $HANDLE xmlcommand args... [{xmlcommand args...}...]
xmlcmd $HANDLE xmlcommand args... [{xmlcommand args...}...]
...
xmlclose $HANDLE
The "xmlopen" program creates a background process with a persistent "session" and exits. It is this background process that reads and manipulates the XML file(s).
In detail, "xmlopen" sets up a LINUX message queue, creates the background process, initialises it with the XML file if supplied and outputs the message "HANDLE" (or "key") for the other commands to use to communicate with it.
On successful completion of "xmlopen" it printd the handle on the standard output and returns 0 (SUCCESS), otherwise it outputs nothing and returns 1 (FAIL)
"xmlcmd" returns 0 if all the XML commands are successful, otherwise it returns the number of XML commands that "fail".
The "xmlcmd" command is a means to transmit "xmlcommand"(s) to the session in this background process, and to return the output to the "front end". It required the "HANDLE" to be the first parameter with the "xmlcommand"(s) and associated arguments making up the rest of the line.
The "xmlclose" command terminates the background process freeing resources and removes the "queue" and session. It takes the queue "HANDLE" as it.s only parameter.
There is a one hour timeout on the background process, that if it is inactive for one hour it frees the resources itself and dies.