Ophidia Terminal: basic usage¶

Ophidia terminal is a robust, comprehensive, effective and extremely usable command line client. We chose to develop a program without GUI with characteristics similar to the bash program present in almost all Unix-like environments. In fact, the client is a real terminal (or shell) full of useful features such as the management of the commands history, the management of specific environment variables, a manual with the description of commands and variables, the management of key combinations for the smart-editing of the command line and more. The terminal is able to interact with the Ophidia server, allowing proper authentication of the user in addition to the rendering of responses.

The terminal handles requests for execution of a particular Ophidia operator sending the server the sequence of the appropriate parameters; in case of local commands the corresponding functions of Oph-Terminal are directly called instead. In both situations, once obtained the required output, the program provides a mechanism for the proper display of the contents, and then returns back in the state of waiting for a new command.

This guide provides the essential knowledege necessary to execute Ophidia operations, however the terminal provides a lot of other features and functionalities which are depicted in the terminal advanced features section.

Starting the terminal¶

Oph-Terminal provides several options to be specified on the command line. It is possible to start the terminal simply by running the executable file with no special options; in this case the terminal looks for all its variables, such as OPH_USER or OPH_TERM_PS1, in the Linux environment, and for each defined and non-empty variable consequently sets its environment. The user can specify the values of these recurring variables directly at the start-up of the system shell, with the appropriate startup files like .bashrc in his home.

Another possibility is to specify the connection parameters directly at startup with certain options, similarly to what happens for example with the MySQL CLI:

with --username=oph-test or -u oph-test you can specify the value to assign to OPH_USER;
with --password=abcd or -p abcd you can specify the value of OPH_PASSWD;
with --hostname=server.hostname or -H server.hostname you can specify the value of OPH_SERVER_HOST;
with --port=11732 or -P 11732 you can specify the value of OPH_SERVER_PORT.

Using one or more of the above options, any corresponding value defined in the user Linux environment is not used, so as to ensure a higher priority to the parameters explicitly specified by the user at boot time. An example of command to start the terminal will look like the following:

/usr/local/ophidia/oph-terminal/bin/oph_term -H 127.0.0.1 -u oph-test -p abcd -P 11732

In case of options --help or -h and --version or -v Ophidia Terminal is not started but it returns information relating respectively to the different ways to start the application and the version of the program.

In addition to the synchronous mode, it is also possible to start the application and run a command in asynchronous mode with the -e option.

Immediately after the start, the user is able to use all the implemented commands, with the tranquility of always receiving a notice explaining an eventual error and with the possibility to continue the work session without restarting the program. At the end of the session the terminal can be closed simply typing quit or exit.

Submitting a request¶

Any operation involving one or more operators present in the Ophidia framework can be performed directly calling that operator, using a submission string characterized by the following syntax:

oph_operator param1=val1;...;paramN=valN;

Immediately after the operator name, you must enter the submission string to be sent to the server, which is responsible for interpreting it correctly. The above string consists of key-value pairs containing the equal sign and separated by semicolons. The values assigned to the terms param1,..., paramN can contain any spaces, unlike the names of these parameters, which must occur as single words, separated by ; and =.

There are five more special parameters (keywords), common to all operators:

sessionid: it indicates the identifier corresponding to the work session;
exec_mode: it indicates the type of request sent to the server;
ncores: it indicates the number of parallel processes to be allocated for a particular operator;
cwd: it indicates the current working directory related to the remote Ophidia virtual filesystem;
cube: it specifies the input datacube on which operations have to be performed.

The exec_mode parameter may be async, to start an operator in asynchronous mode and receive only the identifier of the running job, or sync, to start an operator in synchronous mode waiting for the response arriving from the server. The user has the option to explicitly specify the value of exec_mode or not: in the first case it is always used the value contained in the submission string, while, in case of absence, the terminal first tries to concatenate the value of the OPH_EXEC_MODE environment variable, if present, or lets the server assign the default value async.

The same procedure is performed for the other parameters. In case of ncores the corresponding variable is OPH_NCORES and the default value is equal to 1. Regarding sessionid the associated variable is OPH_SESSION_ID and the corresponding value, if present, is concatenated to the string, if the user does not specify it directly at the time of executing the command. However, in case of no usable value, the server does not use a default value but creates a completely new session with a new identifier that Oph-Terminal manages to automatically associate to OPH_SESSION_ID, so that it can be used in subsequent requests.

Once a request has been sent to the server the obtained response may be of two types:

in case of execution of an operator in asynchronous mode, we can see only a section called [JobID], containing the job identifier, useful for retrieving data at a later stage.
in case of execution of an operator in synchronous mode, the calling command is synchronous and blocking, and we have to wait until the end of the job in order to be able to see the results. These in turn are divided into a section [Response], containing the output of the operator, if available, and the above section [JobID].

In both situations, the command automatically extracts from the JobID the sessionid and sets the variable OPH_SESSION_ID to that value. The user may possibly perform a switch between one session and another by changing the environment variable OPH_SESSION_ID with the setenv command, or it can ask the server to create a new session using the command unsetenv OPH_SESSION_ID. The server will actually create the new working session upon reception of the first request with no session associated with it.

Some examples¶

Use of OPH_LIST operator: this operator is useful to navigate the Ophidia virtual filesystem, a POSIX-like hierarchical structure, organized in folders, containers and datacubes. Multidimensional data are located in datacubes, a set of related datacubes is grouped by a container and containers can be placed in different levels of directories and sub-directories. Moreover, a datacube can be distributed across multiple hosts, I/O servers and databases and can be splitted into one or more fragments. In order to see all this information the user can call the oph_list operator, with several levels of verbosity.

Use of OPH_REDUCE operator: this operator can be used to perform a data reduction on the specified datacube. For example, let http:/localhost/1/1 be the identifier of a datacube with latitude, longitude and time dimensions. With the following lines it is possible to compute the maximum value over the time dimension for each point of the space contained in the datacube:

[OPH_TERM] >> oph_reduce cube=http://localhost/1/1;operation=max;

Other examples can be found for each operator in the Operator Manual Operators Manual section.