Ext
A small library, which allows to launch external process and keep connection with it, sending jobs and receiving answers.
Quick review
The idea, which was born from the Guiserver project, is to divide application functionality to few executables/processes. The main process (we will call it client process) launches, when it needed, another process (server process) and set connection with it via two text files. Client is possible to call functions on server process and get results.
Client is a program, written on Harbour, it needs extcli.prg and fconnect.prg to be linked with it.
Server may be a program, written on Harbour with extsrv.prg and fconnect.prg linked, or on Go, Java with External project imported.
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
Описание
A small library, which allows to launch external process and keep connection with it, sending jobs and receiving answers.