Section 16.11: Other GUI clients Up Chapter 16: New Display Clients Chapter 17: PDF Reports  

16.12 Protocol

The New Graphical UIs are based on an XML protocol. The protocol is optimised so that it should run well even on high latency lines because data is only sent when required.
This does mean that there is very limited error checking (eg. for displaying to fields which dont exist on the form etc.) as many DISPLAY statements may be sent in a single envelope, which may well be sent some significant time after the DISPLAY command is executed.
Normally - this output is flushed when user input is required (eg - when doing a MENU or INPUT), or when an internal buffer becomes full.
If you are doing some processing which does not require user input - but does require the output to be displayed quickly then you can flush this internal buffer using aclfgl_flush_ui. e.g.
CALL aclfgl_flush_ui()
The protocol is open – in so far as the on the wire protocol is well defined and it should be easy to add your own custom front ends. You will just need to react to the datapackets defining the current UI statements and return the appropriate TRIGGERED package.
(See below for the DTD for the XML protocols used in both directions. XSD definitions are available from the aubit.com website)

16.12.1 Testing

The communications are normally conducted on STDIN/STDOUT – so you can try the protocol just by starting the program from the command line with the correct environment variables set :
E.g. For a simple ’hello world’ program :
main
    display "Hello World"
end main
$ export A4GL_UI=XML
$ unset AFGLSERVER
$ ./myprog
<ENVELOPE ID="1">
<COMMANDS>
<PROGRAMSTARTUP PROGRAMNAME="./x1" ID="0">
<ENV NAME="DBPATH" 
  VALUE=":/home/aubit4gl/aubit4glsrc/tools/”>
<ENV NAME="DBDATE" VALUE="dmy4/"/>
</PROGRAMSTARTUP>
</COMMANDS>
</ENVELOPE>
<ENVELOPE ID="1">
<COMMANDS>
<DISPLAY>Hello World</DISPLAY>
<PROGRAMSTOP EXITCODE="0" ID="0">
</PROGRAMSTOP>
</COMMANDS>
</ENVELOPE>
Here is another example – this one uses a PROMPT to get some input from a user (reply from the client is in indentded and in bold):
<ENVELOPE ID="3">
<COMMANDS>
<PROGRAMSTARTUP PROGRAMNAME="./x1" ID="3">
<ENV NAME="DBPATH" 
  VALUE=":/home/aubit4gl/aubit4glsrc/tools"/>
<ENV NAME="DBDATE" VALUE="dmy4/"/>
</PROGRAMSTARTUP>
</COMMANDS>
</ENVELOPE>
<ENVELOPE ID="3">
<COMMANDS>
<PROMPT CONTEXT="0" PROMPTATTRIBUTE="-1" FIELDATTRIBUTE="-1"
  TEXT="Please enter your name" CHARMODE="0" HELPNO="0" 
  ATTRIB_STYLE="" ATTRIB_TEXT="">
<EVENTS>
</EVENTS>
</PROMPT>
<WAITFOREVENT CONTEXT="0" />
</COMMANDS>
</ENVELOPE>
<TRIGGERED ID="ACCEPT" LASTKEY="ACCEPT">
<SYNCVALUES><SYNCVALUE>Mike Aubury</SYNCVALUE></SYNCVALUES>
</TRIGGERED>
<ENVELOPE ID="3">
<COMMANDS>
<FREE TYPE="PROMPT" CONTEXT="0"/>
<DISPLAY>Mike Aubury </DISPLAY>
<PROGRAMSTOP EXITCODE="0" ID="3">
</PROGRAMSTOP>
</COMMANDS>
</ENVELOPE>
The front end simply replies with the TRIGGERED packet to send data back to the 4GL program.
All interactions are handled within a UI Context. Each UI statement which requires user input establishes a Context which is used by a subsequent WAITFOREVENT. When that Context is no longer required – the context is FREEd.

16.12.2 DTDs

For those developing other front ends for Aubit4GL there are DTDs and the equivalent XSD files available in a separate document and on the Aubit website. These define the formats for the packets which go from Client to Program, Program to Client, and the XML version of .per forms.
The XML DTDs and XSDs are too voluminous to include in this manual.
 Section 16.11: Other GUI clients Up Chapter 16: New Display Clients Chapter 17: PDF Reports