drms_run - Run a DRMS module and connect it to a running DRMS server application (drms_server)
[Section 1. Programs, DRMS Modules, Shell Scripts]

This program executes all the commands in the provided script in a single DRMS session. More...

Collaboration diagram for drms_run - Run a DRMS module and connect it to a running DRMS server application (drms_server):

Synopsis:

drms_run <drms_run script> [ <unnamed argument2> [ <unnamed argument3> [ ... ] ] ]
           [ to=<time out> ] [ DRMS_RETENTION=<days> ] [ drmslog=<drms_server log path> ] [ drmsrunlog=<output log>]
           [ server=<path to server> ]
           [ -d ] [ -L ] [ -V | -v | --verbose ]

This program takes as input a script and script arguments and executes the script with its arguments inside a DRMS session. As a result, when the state of the DRMS database is changed by a script command, the command that follows will 'see' the changes in the DRMS database. This is not true for programs running outside the DRMS session (in a separate DRMS session). They cannot 'see' any changes until the first DRMS session terminates. In this way, the commands of the input script can make database changes in concert without making those changes available to programs running outside the DRMS session. After the last script command is run, drms_run ends the DRMS session. At that time all database changes are committed and made available to programs running in all subsequent DRMS sessions.

As a consequence of this design, drms_run is most useful for implementing DRMS pipelines. All the commands necessary to convert the pipeline input to the pipeline output are placed into a drms_run script. Should an error occur anywhere in the pipeline, the drms_run script can trap that error and exit with a non-zero value. This will cause the DRMS session to abort, and no changes will be propagated to the database. Also, if an individual script command is a DRMS module, it can return a non-zero value, and this will also cause the DRMS session to abort and terminate.

drms_run starts a drms_server application, which in turn opens a connection to the DRMS database and starts a DRMS session. Commands that interact with the database (generally DRMS modules) do so by sending requests over a socket connection to drms_server, which then communicates directly with the database. In order for a module to run inside the DRMS session started by drms_run, it must be a 'sock' module (a sockect-connect module), and not a direct-connect module. Socket-connect-module names all contain the "_sock" suffix (e.g., show_info_sock). Such modules scan the environment for special environment variables that tell the module how to locate a specific drms_server instance. Therefore, in order for a sock module to connect to a particular drms_server instance, these special environment variables must be set with parameters specific to the drms_server of interest. drms_run achieves this by capturing the parameters which are generated by drms_server. drms_run obtains the parameters by starting drms_server with the 'shenvfile' argument. This argument provides a file path to which drms_server will write a bash-style source file that will set all the relevant environment variables necessary for the sock modules to locate and connect to the drms_server instance. drms_run sources this file before running the drms_run script, which ensures the sock modules contained within the drms_run script will use the drms_server, and hence DRMS session, started by drms_run.

Direct-connect modules do not have the "_sock" suffix (e.g., show_info). Should a drms_run script contain a direct-connect module command, that module will connect to the DRMS database via a new DRMS session and it will not be part of the DRMS session created by drms_run. This is perfectly legitimate and appropriate for certain types of pipeline processing.

PARAMETERS:

Parameters:

	@c	UNNAMED1 The first unnamed argument is the path to the drms_run script
	@c	UNNAMED2 The second unnamed argument is the first argument to the drms_run script
	@c	UNNAMEDN The Nth unnamed argument is the (N-1)st argument to the drms_run script
	@c	to The timeout, in seconds, relevant when this program is waiting for drms_server to produce the environment file
	@c	DRMS_RETENTION As the drms_run script executes, it might access SUMS Storage Units - for each such Storage Unit, this program will set the retention time to the value of this argument (in days) if the current retention time of the SU is less than the value of this argument.
	@c	drmslog The DIRECTORY to which a file named drmsserver_<pid>.log will be written. The file will contain the stdout and stderr from the instantiated drms_server (<pid> is the pid of the drms_server process). This log will also be copied to the drms_server log directory if the -L flag is set.
	@c	drmsrunlog The DIRECTORY to which a file named drmsrun_<pid>.log will be written. The file will contain the stdout and stderr from the drms_run program. (<pid> is the pid of the drms_server process).

FLAGS:

-d The drms_run script will be deleted immediately prior to termination. -L drms_server will be started with the -L flag, and the drms_server output will be copied to the DRMS session log directory. -V Run verbosely -v Run verbosely --verbose Run verbosely

GEN_FLAGS:

Ubiquitous flags present in every module. DRMS common main program

Exit_Status:

-2 invalid arguments
-1 user requested the help screen
0 drms_server committed upon exiting
1 drms_server aborted upon exiting (there was an error)
2 failed to run script with DRMS commands
3 failed to send kill signal to drms_server
4 drms_server failed to shut down properly
5 couldn't find drms_server env file (perhaps not written)

Example:

drms_run drmslog=/tmp/arta drmsrunlog=/tmp/arta -L poke_missing.csh ds=mdi.fd_V_lev18test key=T_REC start=10 count=100