When the Helper program is launched, the Server sends commands to the Helper process via the process standard input. The Server reads the program responses from the process standard output.
Commands and responses are text lines, ending with the EOL symbol(s) used in the Server OS.
Each command starts with a sequence number, and the response produced with the Helper program starts with the same number. This method allows the Helper program to process several requests simultaneously, and it can return responses in any order.
The Helper program can send information responses at any time. An information response starts with the asterisk (*) symbol. The Server ignores information responses, but they can be seen in the Server Log.
The response lines generated with a Helper program should not be larger than 4096 bytes.
Note: communication between the Server and an Helper program takes place via OS pipes, and many programming libraries buffer output data sent to pipes. Check that your Helper program uses some form of the flush command after it sends a response to its standard output, otherwise the response will not reach the Server.
Helper programs are started with the CommuniGate Pro base directory as their current directory.
Helper programs should not write anything to their standard error streams, unless they want to report a reason for the failure before quitting. CommuniGate Pro reads the program standard error stream only after the program has terminated, and if the program writes into that stream while processing Server commands, the program will be suspended by the OS when the standard error pipe buffer is full.
The Interface Version command is used to provide compatibility between different versions of Helper programs and different versions of the CommuniGate Pro Server. The Server sends this command specifying the protocol version it implements: nnnnnn INTF serverInterfaceVersion
The Helper program should return the INTF response and the supported protocol version. nnnnnn INTF programInterfaceVersion If the returned number is smaller than the Server protocol version, the Server will use this (older) protocol version.
When the Server shuts down or when it needs to stop the Helper program, it sends the QUIT command, and then closes the process standard input. The Helper program should send the OK response and it should quit within 5 seconds.
Sample session (I: - server commands sent to the program standard input, O: - responses the program writes to its standard output, COMMAND - a Helper-specific command):
O: * My Helper program started I: 00001 INTF 1 O: 00001 INTF 1 I: 00002 COMMAND parameters O: 00002 OK I: 00003 COMMAND parameters I: 00004 COMMAND parameters O: * processing 00003 will take some time O: 00004 ERROR description O: 00003 OK I: 00005 QUIT O: * processed: 5 requests. Quitting. O: 00005 OK I: stdin closed
The sample above shows that the Server does not wait for a response before it sends the next command, and that it can accept responses for several pending commands in any order - as long as each command receives a response within the specified time limit.