Ophidia terminal is a robust, comprehensive, effective and extremely usable command line client. Essential information of the software is described in the the terminal basic usage section. This guide describes the client-server interaction and the advanced features provided by the terminal, such as history management, auto-completion, output rendering functionality, variable substitution and much more.
Oph-Terminal contains a client function that is concerned to interact with the server through the SOAP protocol. SOAP may operate on different network protocols, among which the most commonly used is HTTP. In Ophidia we chose to use the HTTPS to secure communication with SSL or GSI/VOMS infrastructure.
SOAP is based also on XML metalanguage for defining parameters required for communication, and for containing the so-called payload, i.e. the content of the sent or received message, whose structure follows the Head-Body configuration, similar to HTML.
For each user request, the terminal sends a new message with the appropriate connection parameters and the string corresponding to the request for execution of a particular operator, which is then interpreted by the functions of the Ophidia framework.
Once the operator execution terminates, Oph-Terminal receives the corresponding response message with the output data of the operator, that are then interpreted and displayed appropriately to the user.
Oph-Terminal provides different environment variables and commands, that can be used for storing recurring values and performing “local” and “remote” operations.
A description of the environment variables follows:
The program environment also includes several commands among which:
Internally the commands resume and view are translated into sequences of calls for the operator OPH_RESUME.
For instance, in case the user wishes to switch from current session to session http://hostname/ophidia/sessions/8912794871982734981234/experiment, the command
resume http://hostname/ophidia/sessions/8912794871982734981234/experiment 3
is translated into several commands for Ophidia Server. One is used to retrieve the number of commands/workflows already submitted in the new session:
oph_resume session=http://hostname/ophidia/sessions/8912794871982734981234/experiment;
Then, there are the requests to retrieve the last three commands submitted in the new session and the related exit status (provided that at least three commands were actually submitted). Assuming that the number of commands already submmited is 15, the requests for the last three commands are
oph_resume session=http://hostname/ophidia/sessions/8912794871982734981234/experiment;document_type=request;id=13;
oph_resume session=http://hostname/ophidia/sessions/8912794871982734981234/experiment;document_type=request;id=14;
oph_resume session=http://hostname/ophidia/sessions/8912794871982734981234/experiment;document_type=request;id=15;
Finally, there are the commands to change the session
oph_resume session=http://hostname/ophidia/sessions/8912794871982734981234/experiment;save=yes;
and retrieve the configuration parameters of the new session (last working directory and idenfier of the last created cube)
oph_get_config key=OPH_CWD;
oph_get_config key=OPH_DATACUBE;
The following command
view 10
corresponds to the following pair of submission strings
oph_resume id=20;document_type=request;
oph_resume id=20;
where the former is used to retrieve the submission string associated with the workflow, the latter returns the workflow task list (or directly the task output in case of single-task workflows).
Similarly, the command
view 10#20;
is translated into the following calls
oph_resume id=20;id_type=marker;document_type=request;
oph_resume id=20;id_type=marker;
The Readline library and particularly the History library allow convenient management of commands history in Oph-Terminal. Immediately after starting the terminal, the file .oph_term_history is loaded in memory as a list of all the commands called earlier with precise information about the date and time of execution.
You can then navigate in the history simply using the arrow keys up and down on your keyboard to display respectively the previous command and the next one, or you can make use of the character ! for history expansion. For example, you can use, along with the exclamation mark, the number corresponding to a particular command, or you can write a command, in whole or in part, to recall the last entry in history for that command.
In addition to different shortcuts for editing the command line, such as the combinations Ctrl + a and Ctrl + e to move to the beginning or end of the line, Oph-Terminal also provides the keystrokes Esc + < and Esc + > to move to the beginning or end of the commands history. Note that all realized combinations faithfully reproduce what is already present in a system shell like bash, such as the recursive search of a command within history with Ctrl + r.
When closing the terminal, the memory containing the commands list is deallocated. Then the user can log back into Oph-Terminal with automatic recovery of the commands related to the previous session. During normal program execution, finally, the user can view the history as a whole or possibly erase it with the history command previously described.
Oph-Terminal provides a number of features to help the user and make it easier to enter commands. The help command is a good starting point if you’re interfacing with the terminal for the first time, it gives a description of all commands and variables in the program.
In addition, anything written in the command line undergoes an intelligent parsing: for example extra spaces positioned at the beginning or end of the line are identified and not considered, and care is taken for the presence of quotation marks (”), quotes (‘) or special characters. However, since each command requires distinct arguments and/or options, you should refer to the manual to avoid making mistakes.
Another interesting feature of Oph-Terminal is the auto-completion. Using, as a normal shell, the TAB key, we can make the terminal complete the word in question on the basis of the characters already written.
Different levels of auto-completion have been implemented, making use of all the XMLs describing the Ophidia operators made available by the server and downloaded by Oph-Terminal at startup:
And if you find yourself with more options to complete a particular word, just re-use the tab key to get a list of all the relative terms or use the Shift key together with the tab key to perform an inline completion.
With the OPH_TERM_VIEWER variable the user is able to appropriately configure the visualization component, implemented with the aim of managing in the best way the rendering of the responses received from the Ophidia server after the submission of a command. Each response will be structured in a JSON file, which may include objects of different types:
The viewer is able to recognize this type of objects and thus represent them in the most appropriate manner on the screen. The user can choose between different modes:
The component has been developed so as to adapt also to the actual dimensions of the terminal from which the user submits the various commands. The viewer is in fact able to recognize the height and width of the shell in use, and print tables dynamically adapting to the space available on the screen. The terminal interprets the JSON file received in response to a request to the Ophidia server and, in the case of an object in a table format, is concerned to adjust the rows height to the content displayed and adjust the columns width in proportion to the maximum size of text placed in them.
Another environment variable, OPH_TERM_IMGS, instead allows you to create images from a JSON response containing objects such as trees or graphs. In particular, one can use the operator oph_cubeio to have a report of all the transformations performed on a set of data, with the detail of the produced datacubes at each step and the description of the particular operation performed.
In most cases, these are linear sequences of operations, starting from the insertion of new data into the system (import), passing through a series of operations of subsetting and data reduction, ending with the storing on disk of new files containing the analyzed data (export).
In other cases, however, the operations can create real strongly interlinked graphs. In these situations, the ability to view the entire session with an image is undoubtedly a better solution to the reading of numerous lines of plain text.
In the event that the terminal runs in a Desktop environment, then with a GUI and an image viewer, we can set the above variable to one of these three values:
Furthermore, in case of a command producing an image file representing a graph, OPH_GRAPH_LAYOUT allows you to setup the graph layout chosing among the following:
The terminal has also the ability to define new environment variables, so that users can possibly store values of interest that have not been provided with the default variables and to use these values into submission strings with a variable substitution very similar to that which is implemented, for example, in bash. Using $varname or ${varname}, Oph-Terminal will try to replace the value of the variable varname if present, or the empty string within the submission string. Without the parentheses, the first character other than a letter, number or underscore is treated as the end of the variable name. Variable substitution is recursive and runs until all $s have been replaced, so for example if the value of a variable is another $varname Oph-Terminal will recursively replace the last value found.
In addition to the default commands, the terminal offers the user the ability to define new commands using aliases. Oph-Terminal incorporates the concept of aliases already present in bash as wrappers of other commands and extends it with the ability to set parametric aliases.
Here’s an example of use in which we define a new alias and then it is used with a parameter:
[OPH_TERM] >> setalias my_alias = "command param1=val1;param2=$1;"
[OPH_TERM] >> my_alias val2
We can specify only one alias per submission string. Oph-Terminal will find the first word of the submission string and in case this is an alias it would pass to the replacement of the arguments in the alias definition string in correspondence of $1, $2, etc.
Pre-loaded aliases are listed below.
cc=oph_createcontainer container=$1;dim=lat|lon|time;dim_type=double|double|double;hierarchy=oph_base|oph_base|oph_time;
cd=oph_folder command=cd;path=$1;
cdd=oph_fs command=cd;path=$1;
del=oph_delete cube=$1;
drop=del [*]
getprogress=oph_resume level=0;id=$1;
jobs=oph_loggingbk job_level=1;mask=010;session_filter=@OPH_SESSION_ID;parent_job_filter=%;
kill=oph_cancel id=$1
ll=oph_list path=$1;level=2;
lr=oph_list path=$1;level=2;recursive=yes;
ls=oph_list path=$1;
lsd=oph_fs command=ls;path=$1;
man=oph_man function=$1;
mkdir=oph_folder command=mkdir;path=$1;
mv=oph_movecontainer container=$1|$2;
mvdir=oph_folder command=mv;path=$1|$2;
ncdump=oph_explorenc src_path=$1;
new=oph_manage_session action=new;
pdd=getenv OPH_CDD
pwd=getenv OPH_CWD
rc=oph_randcube container=$1;dim=lat|lon|time;dim_size=$2|$3|$4;exp_ndim=2;host_partition=test;measure=example_measure;measure_type=double;nfrag=$2;ntuple=$3;compressed=no;concept_level=c|c|d;filesystem=local;ndb=1;ndbms=1;nhost=1;
rm=oph_deletecontainer container=$1;hidden=no;delete_type=physical;
rmdir=oph_folder command=rm;path=$1;
show=oph_explorecube show_time=yes;