= This is the US3 Grid Control Trac Wiki =

This is a Wiki, source code browser, issue tracking system to document the !UltraScan 3 Grid Control Program. The purpose of the Grid Control program is to manage communications between an individual LIMS instance that submitted a job for analysis and the appropriate computer resource (through GFAC or local). 

The source code for the !UltraScan3 Grid Control project is licensed under the [http://www.gnu.org/copyleft/gpl.html GNU General Public License] and allows you to freely copy, modify, and re-distribute all source code, provided you maintain the GPL license with any derivative work.

You can view the source code in the section named "Browse Source", and with permissions, create a ticket to document issues, or update these Wiki pages.

As all Wiki pages, this page is editable, this means that you can (with permissions) modify the contents of this page simply by using your web-browser. Simply click on the "Edit this page" link at the bottom of the page (after you have logged into Trac and have permissions assigned).  WikiFormatting will give you a detailed description of available Wiki formatting commands. 

For questions, email demeler@biochem.uthscsa.edu

== Admin ==

 * [wiki:TracInformation Trac Information]
 * [wiki:Subversion Subversion Info For UltraScan3 Grid Control]

== Prerequisites ==

 * A working !UltraScan III system. Either download an installer appropriate for your system at [http://www.ultrascan3.uthscsa.edu/download.php] or download the [http://wiki.bcf.uthscsa.edu/ultrascan3/wiki/Subversion source code] and follow the [http://wiki.bcf.uthscsa.edu/ultrascan3/wiki/BuildInstructions build instructions].
 * A database/LIMS III system. Either request a new instance on our server for your institution at [http://uslims3.uthscsa.edu/uslims3_newlims/request_new_instance.php] or set up your own server using [http://wiki.bcf.uthscsa.edu/ultrascan3/wiki/US3DatabaseInstantiation these instructions].

== Setting up Grid Control ==

 * Check out the [wiki:Subversion grid control program]. Ideally one would set up a new non-root user for this purpose.
 * In the bin directory, copy the config template file to listen-config.php. Fill in all the appropriate information. Many of the variables contain the same information as in the LIMS config.php file, and these should match.
 * Open a port to listen for UDP messages.
 * Create the socket file and log file. UDP messages queue through the socket file before being picked up by grid control, and the log file is used to record anything out of the ordinary:

{{{
mkfifo /path/to/us3-pipe
touch  /path/to/udp.log
}}}

 * Start the listen system. This is what listens to the UDP port and dispatches any messages:

{{{
/usr/bin/php /home/username/bin/listen.php
}}}

 * If the listen system is running and you want to make changes, you need to stop two programs:

{{{
listen.php
manage-us3-pipe.php
}}}

 * You can send your own messages to the listen system for testing. The format of the message should be "db-requestID: message," where db is the name of the LIMS database, and requestID is the LIMS HPCAnalysisRequestID. Messages include "Starting," "Abort," and "Finished" to indicate changes in job status, but they can also include arbitrary text. Take care to include a colon (:) followed by a space. If your system is working messages should be placed in the queue_messages table and ultimately find their way into the appropriate LIMS database and the common data directory.

{{{
/usr/bin/php gram.php db-requestID: message
}}}

 * The Grid Control program itself is run as a cron script. It calls cleanup.php as needed.

{{{
cd /home/user/bin/; /usr/bin/php /home/user/bin/gridctl.php
}}}

 * Another program run as a cron script is the cluster status program. It updates the usage information on supported clusters so that the user can make a better decision about which cluster to select for the job:

{{{
cd /home/user/bin/; /usr/bin/php /home/user/bin/cluster_status.php
}}}

 * Finally, in production the common data directory will fill up with previously-run jobs. It is useful to keep this information for a period of time, but then to consider deleting directories more than a certain age. A cron script is useful for this too.