Ext

A small library for organizing interprocess communication (IPC) between software components implemented in different programming languages.

1. Quick review
2. Client program How-to
3. Client side functions
4. Server side functions
5. Links

Quick review

The idea, which was born from my other project, Guiserver, is to divide the functionality of the application into several executables/processes.

The main purpose of Ext is to provide the ability to call functions implemented in individual executable processes with minimal infrastructure requirements and without the need for network protocols or complex IPC mechanisms.

The solution is based on the concept of dividing the application functionality into client and server processes, where the client initiates the execution of operations, and the server processes requests and returns results. Communication between processes is carried out through two text files used as channels for transmitting commands and responses. Messages are transmitted in JSON format.

The main process (we will call it the client process) starts, when necessary, another process (the server process) and establishes a connection with it, which is carried out through two text files. The client can call functions in the server process and get the results.

• The client process is the main application that runs and manages the server process.
• A server process is an autonomous executable module that implements certain functionality (for example, data processing, integration with external libraries, etc.).
• If necessary, the client starts the server (if it is not active) and establishes a communication channel with it.

This concept may be useful in following cases:

• if you want to place some functionality to separate process for to not overcharge main program;
• if you want to use some functionality in few applications - the separated process may be used with any of them;
• if it is difficult or impossible to implement some functionality in Harbour.

Client program How-to

Client is your main program, which can run external programs (servers) to get additional functionality.

To run external program, ecli_Run() function is used, which returns a hash array with connection parameters if the server program launched successfully and the connection is established. This hash (you may consider it as a handle) will be used in calls of all Ext function as a first parameter.

To close the connection and terminate the server program the ecli_Close() is used.

And there is a small set of functions to communicate with the server program: ecli_RunProc(), ecli_RunFunc(), ecli_CheckAnswer(), ecli_SetVar() and ecli_getVar(), a full syntax is described in a section below.

ecli_RunProc() cause a passed function, to execute in a server program. It may be used, if this function doesn’t return a value or the return value isn’t needed. ecli_RunFunc() does the same, but it is used, when we need the return value. If lNoWait parameter is omitted, or it is .F., the code execution is suspended till the function on server side return the result. In this case, ecli_RunFunc() returns this result. If we know that the execution of the function in server program may take some time and we don’t want to suspend code execution in client program, we may launch ecli_RunFunc() with lNoWait parameter set to .T.. In this case we need to use ecli_CheckAnswer() from time to time to check, if the return value is ready.

Client side functions

ecli_Run( cExe, [nLog], [cDir], [cFile] ) –> hExt

Runs external program and set connection with it.

• cExe - a full path to executable;
• nLog - 1 if logging is required, 0 - if not;
• cDir - path to directory for temporary files, system temp directory is used by default;
• cFile - a prefix to temporary files, ‘gs’ is used by default.

Returns a hash array for created connection (hExt), if success, or Nil - in case of error. hExt will be used for further ecli_… functions calls.

ecli_Close( hExt )

Closes connection, terminates the external process.

ecli_RunProc( hExt, cFunc, aParams )

Sends a procedure name and parameters to be executed by connected process. Returns immedeately, don’t wat for a result. In fact, it waits for confirmation of receiving this command.

• cFunc - a procedure name;
• aParams - an array of parameters.

ecli_RunFunc( hExt, cFunc, aParams, lNoWait ) –> cResult

Sends a function name and parameters to be executed by connected process. Returns the result, if lNoWait isn’t set.

• cFunc - a function name;
• aParams - an array of parameters.
• lNoWait - if set to .T., the function doesn’t wait for a result and returns when gets a confirmation of receiving this command. The result should be received later by ecli_CheckAnswer() function.

ecli_CheckAnswer( hExt ) –> cResult

Checks, if the result of function execution is ready. Should be used after calling ecli_RunFunc() with lNoWait = .T.

Returns the result or Nil, if the result isn’t ready yet.

ecli_SetVar( hExt, cVarName, cValue )

Sets a public variable value in connected process.

• cVarName - variable name;
• cValue - variable value.

ecli_GetVar( hExt, cVarName ) –> cResult

Returns a public variable value from connected process.

• cVarName - variable name;

gWritelog( hExt, cText )

Writes a text to a log file “extclient.log”, if nLog was set to 1 in ecli_Run() call.

• cText - a text string to be written.

Server side functions

esrv_Init( … ) –> hExt

Initializes the process being launched (server process). The parameters are passed from a process, which launches it (client process).

• dir=
• log=
• file=<file_prefix>

Returns a hash array for created connection (hExt).

esrv_Wait( hExt )

Waits for a command from client process.

esrv_RunProc( hExt, cFunc, aParams )

Sends a procedure name and parameters to be executed by connected process. Returns immedeately, don’t wat for a result. In fact, it waits for confirmation of receiving this command.

• cFunc - a procedure name;
• aParams - an array of parameters.

esrv_LogLevel( hExt[, nLogLevel] ) –> nLogLevel

Returns nLog value (0 or 1) and sets a new, if passed.

gWritelog( hExt, cText )

Writes a text to a log file “extserver.log”, if nLog was set to 1 in ecli_Run() call.

• cText - a text string to be written.

Links

Guiserver

External - Go

External - Java