CCP4i Documentation for Programmers: Core Documentation
Contents
Interaction with Operating System & Local Packages(src/local.tcl)
Interaction with Operating System & Local Packages(src/local.tcl)
The following procedures might need local customisation. In practice the only procedure that I know to have been changed on and site is RunBatchJob which needs customising ot the local batch system.
Argument list: <subject> <tmp_file> <mail_address> subject Subject of mail message
tmp_file Temporary file containing the text of the message
mail_address Mail addressee
It is assumed that Netscape is used as a browser. CCP4i uses the browser to display documentation and uses commands normally invoked from the command line to send commands to Netscape to display the required file. See the Netscape documentation I (Liz) have found some of the commands documented here do not seem to work on SGIs or through the Tcl exec command.
Another major problem is that if Netscape is not already running it can be tricky to start it and then specify the name of the file to display as there is a significant wait as Netscape starts up and is not listening to input. The poll_netscape procedure was an attempt to tackle this problem.
Argument list: None Uses the Tcl exec command to run the command line defined in configure(START_NETSCAPE)
The use of this procedure is deprecated - use start_hypertext_viewer instead.
Argument list: <viewer> Uses the Tcl exec command to start the hypertext viewer defined in configure(HYPERTEXT_VIEWER).
This is a generic version of the start_netscape command, and should be used instead.
viewer (optional) Specify a viewer command to use in preference to that defined in configure(HYPERTEXT_VIEWER).
Argument list: <url> <args> Open a specified file in a currently open Netscape window
url full path name of file
target optional target within file
-remote
The url is not a local file
Argument list: <url> <message> This procedure is superceded by the generic warning_no_hypertext_viewer command.
url name of file which could not open
message the message returned by the opening mechanism
Argument list: <hypertext_viewer> <url> <message> When CCP4i fails to open a URL in the specified hypertext viewer then display a warning with the error message returned by the opening mechanism.
This is a generic version of the warning_no_netscape procedure and should be used instead.
url Name of the file which couldn't be opened
message The message text returned by the opening mechanism
Argument list: <mode> <delay> <netscape_npolls> <url> <message> After Netscape has been started there is a delay before it will respond to system commands to load a page. This procedure works by recursively calling itself and incrementing netscape_npolls until it equals some maximal value (currently hardcoded).
mode either remote (url is on a remote machine) or file (url is a local file)
delay the pause between each attempt ot load a page
netscape_npolls number of attempts that have been made to load page
url page to be loaded into Netscape
message Error message to be output to user
Most of the code for running scripts is in the runjob.tcl file. The procedures in this section are those which might possibly require some installation dependent modification.
Provided ccp4i is properly configured the user has the option to run program scripts on remote machines or in batch queues. The necessary configuring is described in
Configuring Running on Remote Machines RunRemote uses the unix system command rsh to run jobs on other machines on the same local network. The necessary commands to run in batch (RunBatchJob) may be installation dependent. For either of these modes ccp4i creates a com file (CreateBatchCom) which is a short *nix shell script to setup ccp4 and to start a ccp4i process with the appropriate command line arguments which will run it in 'run' mode for running the program scripts.
Argument list: <job_id> <com_file> <batch_queue> <batch_options> Uses a simple Tcl exec command to submit a job to a local batch queue. and handles failures cleanly.
job_id The job number (see database documentation)
com_file A command file which will be run on the batch machine (see CreateBatchCom)
batch_queue The name of the batch queue
batch_options Any additional arguments to the batch system
Argument list: <job_id> <com_file> <machine> <args> job_id job number
com_file Command script to run on the remote machine (see CreateBatchCom)
machine Name of remote machine
-time time
Use the Unix at command to run the job at time. This is a text string with an appropriate format for the at command
Argument list: <job_id> <script_file> <server_name> <server_host> <server_port> Argument list: <script_file> <com_fileVar> The command file will normally contain a command to setup CCP4 as defined by configure(CCP4_SETUP_COMMAND) and a command to run non-graphical ccp4i in script mode with the appropriate script file name as input.
script_file The name of the script file to be run. This is now, usually, a def file which is written to the project database directory.
com_fileVar the name of a command file is generated from the script file name by adding the extension .com and changing the directory to the the TEMPORARY directory. The command file name is returned as com_fileVar
Argument list: <script_pid> <nretry> <0> Kill the ccp4i script which is running the ccp4 program(s) by killing any child process (i.e. the ccp4 program). The script should then fail cleanly. If it can not find a child process then the KillScript process will call itself again recursively and try again. The limit on retries is currently set in the procedure to 3 and after this it will try to kill the ccp4i process.
Not currently implemented for the Windows operating system
A potential problem on *nix systems is the use of the system command ps -ef to find the ids of processes and the ids of their parents. The output from this can have variable format.
script_pid Process id for ccp4i proccess (this information is returned to the main graphical ccp4i process when the job start) #d_arg nretry Number of retries that have been made. This is optional argument which should not usually be set when the procedure is first called - it is used when KillScript recursively calls itself to keep track of the number of tries.
Argument list: None Determine the possible forms of the "ps" command for the current operating system, then execute using the get_process_list command to return the output as a list (with each line of output as an element of the list). Returns an empty string on error.
Argument list: <ps_command> Internal command called from GetProcessList. Executes the supplied "ps" command and returns the output as a list, with each line of output as an element of the list. Returns an empty string on error.
ps_command The ps ... command appropriate to this system (normally ps -ef)
Argument list: <pid> Kill a system process with the specified pid, by issuing the kill -9 command to it.
Returns 1 on success, 0 on failure.
pid The process id number for the process to be killed.
Argument list: <process_id> <delay> Kill all the child processes of the specified system process (if any, by calling KillChildProcesses recursively) and then try to kill the process itself (if it is still active).
Returns 1 on success, 0 on failure.
After killing the child processes KillChildProcesses pauses for the specified delay, to allow the system to update, before checking to see if the parent process is still active. If not then it is assumed that it has died due to the kill signals sent to its children, and success status is returned.
process_id pid of the system process to be killed
delay delay in milliseconds after killing child processes and before checking whether the parent process is still active
Argument list: <job_id> This uses a *nix system command, rsh, to start another ccp4i process on the remote machine. The new process has a -k(ill) argument and will just use the KillScript procedure to kill the target process before terminating itself.
job_id Job number of job to be killed.
Argument list: <job_id> <pidVar> All ccp4i scripts write an identifier to the top of the output log file. One item of information is the process id.
When ccp4i starts a job it usually saves the process id in the project database but this information is lost if the main ccp4i job is stopped and restarted. The best way to recover the process id is from the log file. The only current use for the information is to kill a job.
job_id Job number
pidVar Return the process id for the job
See the Tcl documentation on the socket command and also the client side procedures in In CCP4i the main graphical process acts as the server which has a permanently open port to which the non-graphical processes (which run the programs) can connect. The main use for the sockets is to return information on job status and output files to the main ccp4i process.
The server port is opened at CCP4i startup by OpenServerPort. There are then two processes ServerAcceptSocket which accepts new socket connections from a client and ServerAcceptInput which accepts input via a socket. The input to ServerAcceptInput is usually in the form of a command which is the name of a ccp4i procedure and some arguments. For obvious security reasons only a very limited number of commands are recognised and these are explicitly listed in ServerAcceptInput.
The activities of the socket handlers are reported in the session log
Session Log Argument list: None This procedure called as part of ccp4i initialisation. The port id is one in the range defined by configure(GUI_PORT). This should be a list of two elements - the first and last in the range of permissible port ids. The number of ports required may exceed the number available if there are a large number of ccp4i processes on one machine. This procedure reports to the user if it fails and warns that inter-process communication will fail.SendMail Send email using system Mail utility
Interaction with Netscape
Interaction with Netscape
start_netscape Start the Netscape program
start_hypertext_viewer Start the hypertext viewer program defined in configure
open_url Open a specified file in a Netscape window
warning_no_netscape Output warning message when fail to open page in Netscape
warning_no_hypertext_viewer Output warning message when there is a failure to open a URL
poll_netscape Make repeat attempts to load page into Netscape
Running Program Scripts
Running Program Scripts
RunBatchJob Submit a job to a local batch queue
RunRemote Start a job on a remote machine
RunServer Procedure not fully implemented. Start a job on a server
CreateBatchCom Create a command file to start a job on a remote machine or batch queue
KillScript Kill a non-graphical ccp4i process
GetProcessList Return the process information from the Unix ps command
get_process_list Execute and return the output of Unix command ps ...
KillProcess Kill a system process
KillChildProcesses Kill a system process id and all its child processes
KillRemoteScript Kill a ccp4i non-graphical script running on a remote machine
ReadLogPid Read log file header to get process id
Server-Side Socket Handling
Server Side Socket Handling
OpenServerPort Open a port in the CCP4i server i.e. the main graphical process