GTXclient C API  GTXserver-15.0.3

text_list.c example

See text_list.c source code.

This example is the simpliest way to understand the communication between GTXserver and a client. The program scrolls through the Isatis file system to get information on all files and variables.

This example does not read any Isatis variable and you should refer to next examples to know more about that point.

Here is a list of the options available when running text_list:

-helpPrints help on command usage
-debugPrints client/server messages. Interesting to follow the dialog between the server and its client.
-host hostnameServer's hostname. If not specified, the default host is "localhost"..
-port port_numberPort used to communicate with the client. The default is the same for the server and the client. If for any reason the default port number is not correct on your machine, you can change it (you must use the same port number in the server and the client).
-path data_pathAsks the server to use this data path to access to the Isatis file system. The default is set to the $GTX_DATA environment variable if defined.
The default is to run a new server on a random port.
If -host or -port is specified, a server must have been started first on the given host/port

You can try to run the client to see what happens. If you examine the source code, you will find the main calls used to write a client application. This source code is only composed of two functions: st_usage and main. The first one only gives the usage of the program.

During the arguments parsing, if an error occurs, the program uses the function GTX_ERROR_FUNCTION(). The default behaviour of this function is to simply call fprintf on stderr. This function will be overriden in the motif_client example

The first thing is to initialize the library calling: GTXClientInitialize(GTX_CLIENT_VERSION).

With the option -debug, the program calls GTXClientDebug() with 1. Then all the functions will print extra messages about the dialog between server and client. This can be useful in a debug phase.

The default is then to run a new GTXserver on a random port. The function will look for the server executable in the following places:

  • the contents of GTX_SERVER environment variable
  • the GTX_HOME environment variable (mostly used under UNIX to indicate where Isatis is installed) or a registry key under Windows.
  • through the PATH.

To connect to the server, the client calls GTXClientConnect(). The server must already be running and waiting for connection. If no -port or -host option has been used, it has been started just above, so it should be OK. Otherwise, the server must already be running on the given host/port. If not, the function will return 1 and send a message with: GTX_ERROR_FUNCTION().

If the server has been started with the -multisession parameter, the server will still be available for other sessions during this session lifetime. Moreover, when GTXClientDisconnect will be called, the server will still be there...

As we are connected we can get the list of studies using GTXClientGetStudyList(). This function returns the number of studies. Like all other functions, if a problem occured, an error code is returned and a message is sent using GTX_ERROR_FUNCTION().

We then set the name of the current study using GTXClientSetStudy() For each study we can obtain the directory list with GTXClientGetDirectoryList(). and we set the current directory using GTXClientSetDirectory() for each directory of the list.

After getting the file list of each directory using GTXClientGetFileList(), we must set as current each file with GTXClientSetFile().

At this point, we try to obtain file information using GTXClientGetFileInfo(). We then dump the contents of the GTXFileInfo structure returned by this function.

After that, we get the variable list with a call to GTXClientGetVariableList() and define each variable as the current one with GTXClientSetVariable().

After getting variable information through GTXClientGetVariableInfo(). We then dump the contents of the GTXVariableInfo structure returned by this function.

If the current variable is a macro variable, we get macro indices using GTXClientGetMacroIndicesWithAlpha() and dump them. Note: Macro variables appears in Isatis 3.2 and can have alphanumerical indices since Isatis 5.0.

The end of the program mainly consists in freeing memory allocated by GTXserver functions.

Just before exiting, we must disconnect from the server using GTXClientDisconnect(). If the server is mono session, it exits. If the server is multi session, only the current session terminates and GTXserver is still available for a further session.