Initialisation and Utilities

The system.tcl and utils.tcl files contains many basic commands which are used throughout ccp4i. These two files are sourced immediately by bin/ccp4i.tcl and all other 'main' scripts to provide the basic functionality for boot strapping up the ccp4i system.#d_intro Some of the procedures interact with the operating system and are therefore platform dependent. NOTE Some of these are no more than wrappers to Tcl commands - as a matter of policy any function which might conceivably be problematic on porting has been wrapped. In practice Tcl seems to handle porting very well.

Def Files

Def Files

The def file has identifier data at the top of the file written by WriteIdentifier. Def files may have two items per line, the parameter name and the parameter value or they may have three items: parameter name, parameter type and parameter value. The def files in $CCP4I_TOP/tasks include the parameter type which is needed to define the widget type when drawing a task window. Other def files do not need to contain \this information. When initialising an array CCP4i normally reads the distributed def file which contains the parameter types and the parameters consistent with the distributed graphical interface; this ensures that the the graphical window can be drawn safely. These parameters may be overlaid and customised by reading another def file.

The preferences files are special cases of def files which might be considered to go with the tasks: preferences, configure and directories. All of these preferences have global arrays which may be accessed from any procedure within CCP4i which needs information from them. The task windows to edit the preferences and configure data are tasks/pref.tcl and tasks/config.tcl - note that these windows set up another temporary array for the data and do not directly access the preferences and configure arrays. The directories task window is defined in src/directories.tcl and does directly edit the directories array - this is probably not a good thing.

The command InitialiseArray will read data from an def file to an array and SaveArray will save data from an array to a def file. The InitialisePreferences and SavePreferences commands are used for the preferences files to access files in the appropriate directory.

Argument list: <filn> <arrayname> <taskname> <args>

filn Def file name

arrayname Name of array to be loaded with data

taskname The name of a task which should correspond to the identifier in the def file

-nocheck

Do not check that def file has correct task identifier

-reportlabel

If def file does not have correct identifier then ask user if they still want to read it.

Argument list: <name> <>

Given a parameter name this command returns 1 if the name has a prefix matching the list of prefixes used to denote internal administrative variables in CCP4i.

If no name is given then the procedure returns the list of reserved prefixes.

name (optional) Parameter name to check

Argument list: <f> <script> <args>

The standard header parameters are written automatically : VERSION, SCRIPT, DATE & USER. All other parameters should be entered as name-value pairs and will be output in the usual format of

#CCP4I NAME value

f If this is input as an empty string then the header text is returned in this argument. Otherwise f is interpreted as an io channel id and the header text is written to that channel.

script The script type (e.g. DEF for a def file)

name value There can be any number of additional arguments each of which is a list of two items: the name of a parameter and its value.

Argument list: <taskname> <filn> <arrayname> <args>

The array should contain an element PARAM_LIST which contains a list of the elements of the array to be written out. The parameter name in the def file will be the same as the element name in the array. The PARAM_LIST is usually created by InitialiseArray when it reads in the def file to define the contents of the array. Additional elements may be added to the array to be used as control parameters when the array is represented in a task window. The def file has identifier data at the top of the file written by WriteIdentifier. Def files may have two items per line, the parameter name and the parameter value or they may have three items: parameter name, parameter type and parameter value.

-save_types

Save the parameter types in addition to their values

-no_ident

Do not write identifier text in the file header

-notype

Indicates there is no parameter typing information in the array

-query_overwrite

Prompt user before overwriting an existing file

-append

Append output to existing file (default is to overwrite)

-job job_id

Write specified job_id number to the identifier text

Argument list: <fVar> <var> <value> <>

fVar Returned. Text string to which the new line is appended

var The name of the parameter

value The value of the parameter. Optional. Default empty.

Argument list: <fVar> <var> <type> <value> <>

fVar Returned. Text string to which the new line is appended

var The name of the parameter

type Data type of the parameter

value The value of the parameter. Optional. Default empty.

Preferences Files

Preferences Files

There are utilities in system.tcl to handle the 'preferences' files, which are:

configure.def with configuration options for the local installation (e.g. printers, remote machines)

directories.def which defines the user's project and directory aliases

preferences.def which defines some user preferences for graphical CCP4i

loggraph.def Preferences for the loggraph program

Each of these sets of preferences are treated as a task with a task interface for the user to edit parameters and parameters are saved as a def file. The utilities in system.tcl are concerned with loading the preferences at CCP4i startup to be saved in global arrays: configure, preferences and directories. These arrays can be accessed from anywhere in the ccp4i code but the parameters should NOT be changed - the arrays should be regarded as 'read only'.

There are distribution versions of the def files called $CCP4I_TOP/etc/foo.def.dist When a user runs CCP4i for the first time the distribution file is read, possible amended by an autoconfigure procedure and then written to either $CCP4I_TOP/etc/$PLATFORM/foo.def or $HOME/.CCP4/$PLATFORM/foo.def. Subsequently when a user runs CCP4i the first configure file found in the order: $HOME/.CCP4/$PLATFORM/foo.def, $CCP4I_TOP/etc/$PLATFORM/foo.def, $CCP4I_TOP/etc/$PLATFORM/foo.def.dist will be used.

Argument list: <taskname> <arrayname> <args>

This task first reads default parameters from the ccp4i installation area and then reads any user preferences in .CCP4/domain directory. This procedure uses InitialiseArray to load the def file into the array.

taskname Name of task (preferences, configure or directories)

arrayname Name of array to be loaded with data

-nouser

Do not read the user's def files.

Argument list: <filename>

Currently required to handle potential conflict between ccp4i and MG accessing directories.def

filename Name of file to lock (lockfile will be filename.LOCK)

Argument list: <lockfile> <userVar> <timeVar> <pidVar> <>

Return 0 is lock file exists and 1 (i.e. OK to open database file) if it does not.

project Alias of project

db Corresponding database directory

userVar Return name of user who created lock file

timeVar Return time of creation of lock file

pidVar (Optional) Return id of process which owns the lock file

Argument list: <lockfile> <args>

-force

Force deletion of the lock even if not owned by the current process

Argument list: <lockfile>

Returns 1 if lock was created, 0 otherwise

project Alias of project

db Corresponding database directory

Argument list: <taskname> <arrayname> <args>

Presently these are saved to directory $HOME/.CCP4/$domain where domain is unix or windows

taskname Name of the task (i.e. directories preferences configure or status).

arrayname name of array containing data

Argument list: <taskname> <arrayname>

taskname Name of the task (i.e. directories preferences configure or status).

arrayname name of array containing data

Argument list: <arrayname>

When the user changes the projects or aliases in the 'Directories and ProjectDir' window this command will update the menus in all currently drawn task windows and file selection windows.

This command called from InitialisePreferences so needs to be in system.tcl to ensure it is defined when called - but it more naturally belongs in windows.tcl.

system(DEFDIR_WIDGET_LIST) contains a list of all widgets for parameters of type _default_dir. This list is updated by CreateLine whenever it draws such a widget. The list is not updated when widgets are destroyed.

arrayname Name of directories array

CCP4i Startup Utilities

ElementExists Test if a given element name exists in an array

Argument list: <arrayname> <element>

Return 1 if array element exists, otherwise return 0 #d_arg arrayname Name of array

element Name of element

Argument list: <arrayname> <args>

Invoked if there is no configure.def file defined for the UNIX system. Initial parameters are taken from CCP4I_TOP/etc/configure.def.init

arrayname Name of configure array

Argument list: <arrayname> <args>

arrayname Name of the configure array

Argument list: <arrayname> <args>

arrayname Name of the system array

Argument list: <arrayname> <paramlistVar>

This is used to set up menus for options such as remote machines.

This procedure defines some data types whose actual allowed values are dependent on user input to the configure interface. Each data type is a menu with the menu items (i.e. the allowed values for data of that type) been taken from the configure.def file via the configure array.

The relationship between the configure file data and the derived menus is defined in configure(TYPEDEF_LIST). This is a list and each element in that list defines one menu. Each menu definition is itself a list with the items: name of the menu type, the name of the element acting as counter, the root element name for the items, and the root element name for alias for each item (this is optional).

arrayname name of array containing parameters

paramlistVar name of array element containing the menu definitions (usually TYPEDEF_LIST)

Argument list: <arrayname> <defVar> <nitemsVar> <menuVar> <aliasVar> <>

arrayname Name of data array

defVar Name of the menu type

nitemsVar Number of menu items (i.e. maximum index for the input array elements)

menuVar Array element containing the text for the menu items

aliasVar optional. Array element containing the aliases for the menu items

Argument list: <arrayname>

Sets the default map viewer command in typedef to that specified in preferences.

arrayname name of array containing parameters

Argument list: <arrayname>

Sets the default map viewer command in typedef to that specified in preferences.

arrayname name of array containing parameters

Argument list: <arrayname>

Sets the default mtz viewer command in typedef to that specified in preferences.

arrayname name of array containing parameters

Argument list: <filetype> <viewercmd>

Reorders the lists of viewer commands in typedef so that the user specified default (set in preferences) is first in the list, and hence is used by default to view the specified file type in the gui.

filetype Name of the type for the file in types.def

viewercmd The new default viewer command (must be one of those already defined in types.def for this file type)

Argument list: <arrayname> <map_format> <args>

This procedure called by tasks which present user with the option to output maps. Beware FFT/Patterson will not output Xtalview maps because Xtalview just takes the hkl data & generates own map

Argument list: <menuname> <_map_format>

For each format already defined in the type, check whether the conversion can be performed in the current setup and regenerate the menu to only include those formats that are actually available.

menuname (optional) The parameter type as defined for example in types.def. This defaults to _map_format.

Argument list: None

Part of CCP4i startup. Report unset variables to user with option to continue or exit.

Argument list: None

On startup check that .CCP4 directory exists, and that the necessary subdirectories (including the shadow area) are also present. Create any missing directories.

Argument list: None

CreateSessionLog Open a session log file which is written to by the Report

Argument list: None

This file can seen by user with 'Review Session Log' utility. It logs running jobs, file handling, sockets and should be used for any other important actions for which some diagnostic reporting might be useful.

The file name is $HOME/.CCP4/CCP4_session.log

Argument list: <level> <text> <args>

The report level cutoff is not currently implemented - there is no cutoff value in the preferences.

Report level - 0,1,2 in order of decreasing importance. Currently unused.

text Text to appear in session log

-notime

Do not output the time to the session log

Argument list: <message> <args>

Draw a dialog box with a warning message.

There is another version of this proc in util_windows.tcl which will override this version after util_windows.tcl has been sourced. NB util_windows.tcl is NOT sourced by ccp4ish so run scripts will always default to this version if the programmer wants to output graphical messages from run scripts which might be necessary debugging under windows.

Saving Global Parameters

Save global parameters in an array called system_save this just helps keep things tidy.

Argument list: <symbol>

symbol Name of parameter

Argument list: <symbol> <name>

symbol Name of parameter

value Value of parameter

Querying the Operating System

Querying the Operating System

GetHostname Return the name of the machine running the process

Argument list: None

Wrapper for 'info hostname'

Argument list: None

GetVersion Return the CCP4i version.

Argument list: None

GetPid Return the process id of the current process

Argument list: None

Wrapper for Tcl pid command

Argument list: None

Is wrapper for Tcl pwd command

Argument list: <args>

Uses Tcl clock command. Return the current time if the -clock argument is not used. See Tcl clock command for explanation of formats.

-clock time

Input a time as a machine clock time in seconds

-format format

Output format can be: full (%d %b %Y %H:%M:%S), time (%H:%M:%S) date (%d %b %Y), or brief (%H:%M:%S for today or %d %b %y)

Argument list: <program>

CCP4i usually calls programs without giving the full path name and relies on the PATH environment variable being correctly set to find the required programs. The user can define full path names for some programs in the configure interface and their specifications are interpreted in the BinPath procedure. All program calls in CCP4i scripts should pass the program name through this procedure which will expand the name to the full path name for those defined in the configure interface. By default BinPath will just return the program name as input.

program Name of a program.

Argument list: <program>

This command searches the directories on the user's PATH and looks for the specified program name in each directory. It returns the full path for the first match it finds, or else an empty string if no match is found.

This should work on both Unix and Windows platforms.

program Name of the program executable to search for

Argument list: <command> <script> <statusout> <reportout> <args>

This is a cut-down version of the Execute in execute.tcl which is used to run program in the ccp4i run script. This version runs programs from within the ccp4i graphical interface.

Execute returns a true (1) if the program completes successfully, or a false (0) otherwise.

command The command line to run the program

script The script input to the program - should be null string if there is no script input.

statusout Output the termination status from the program

reportout Output the termination standardout output from the program #d_opt0 -success success_flag

The 'successful' termination status from the program. Default is 0 as appropriate from most CCP4 programs.

-log logfile Set the name of the file for the log output. If this is not set then Execute will not handle log file output.

Handling File Names

GetEnvPath Get operating system environment variable

Argument list: <var> <report> <1>

Return a path name associated with an environment variable - in a Windows system the separators are converted to forward slash. Return an empty string if no environment variable found.

var Environment variable

report Optional - default 1. If true (1) then output warning message if environment variable not found.

Argument list: <dir>

Given a directory (either alias or full path) returns the full path appropriately formatted for the platform.

dir Directory alias or path

Argument list: <file> <dir> <args>

Path name will be appropriately formatted for the platform.

Will return the file name as input if directory alias is undefined or if directory alias is FULL_PATH or CURRENT.

file File name (not usually including path)

dir Directory or project alias. Optional - default is blank string which is interpreted as undefined project alias.

Argument list: <file> <dir> <args>

Handles the case when the input file name has a directory separator

This procedure could be merged with with GetFullFileName but it is a bug fix late in development cycle so separate procedure.

Argument list: <arrayname> <fileVar> <args>

This command is similar to GetFullFileName but the input is in the form of the name of an array and the element containing the file name. Note that the default directory alias for the directory containing the file will be in the element DIR_$fileVar. This command should be used in the context of callback functions.

arrayname Name of data array

fileVar name of array element containing file name

-dir dirVar

Name of array element containing the directory alias.

-machine machine

Not implemented. Would derive path name as seen from an alternative machine

Argument list: <project_alias>

Dependent on the RUN_MODE this sets either the CURRENT_PROJECT or the MG_CURRENT_PROJECT entry in ccp4i_status to the specified value.

project_alias Name of the new current project.

Argument list: None

Dependent on the RUN_MODE this returns the values of either the CURRENT_PROJECT or the MG_CURRENT_PROJECT entry in ccp4i_status.

Argument list: <project_alias>

Returns the directory for the project returned by GetCurrentProject, or the directory for a particular project alias (if one is specified).

project_alias (optional) Return directory for this project.

Argument list: <dirIn>

dir Input project/directory alias. If this argument is missing then the current project directory is assumed.

Argument list: <project>

Return the full path name for the database directory of an input project alias - typically this is a subdirectory called CCP4_DATABASE in the project directory.

Given a project alias this command looks up the path of the corresponding database directory using a call to GetProjectDBPath. If the project alias isn't found then an empty string is returned.

If no project alias is supplied then the database directory of the current project is returned.

project (optional) Project alias

Argument list: <topname> <args>

The procedure will search in order of priority: 1) the user's 'dot' directory ($HOME/.CCP4/CCP4I_TOP on unix) 2) the ccp4i installation area.

topname Should be TOP (to find ccp4i source files) or HELP (to find html files). The default place for help files is $CCP4I_TOP/help

Argument list: <filename> <args>

The user's configure files are usually in $HOME/.CCP4/platform where platform is UNIX or WINDOWS (eg used when several students in a class have same login) #d_arg filename The name of the configure file

-user

Use a file in the directory $HOME/.CCP4/username/platform where username is taken from $system(USERNAME). This parameter is set if the user start ccp4i with the argument 'ccp4i -u[ser] username'. This is intended \to be used when there is more than one person using one login id - e.g. in a teaching situation.

-domain

This is part of the machine domain functionality - not fully implemented.

-create

If the directory structure in .CCP4 does not exist then create the directories.

Argument list: <args>

If called in graphical ccp4i the root of the file name is pid_n where pid is the ccp4i process id and n is a counter of the number of temporary files. If called in a run script then the root of the file name is project_jobid_n where project is the user's project name, jobid is the job number and n is a counter of the number of temporary files. The file name has the extension .tmp but it is usual to specify the file type using the -ext argument to GetTmpFileName and giving the usual file extension of the file type.

The temporary file is given a path to put it in the CCP4i TEMPORARY directory (NB this is not necessarily the same a $CCP4_SCR).

The use of this procedure to provide a consistent naming mechanism for temporary files is essential for the CCP4i file cleanup mechanism to be able to identify temporary files created by a particular job. It is possible that in future this procedure could keep some more definite record of temporary files created if ccp4i needs to track files more closely.

-ext extension

Add the extra text extension to the root file name. This option is usually used to enter the file type for the file.

-defdir directory_alias

Give file name with directory for directory alias directory_alias

-dir directory

Give file name with directory directory

-map

Give file name with directory as the default output directory for maps. This is usually the TEMPORARY directory or the project directory.

Argument list: <file> <default>

The file formats are defined in etc/types.def

Argument list: <args>

If the first argument begins with a dollar sign it will be interpreted as a environment variable. Otherwise this procedure is just wrapper to Tcl 'file join' command.

Beware file join not available for tcl <7.6

name(s) List of file/directory names of any length

Argument list: <filename>

This is wrapper for 'file rootname' and 'file tail' commands.

filename Input file name

Manipulating Files

OpenFile Open a file

Argument list: <filename> <channel> <mode> <a+>

Wrapper with error trapping for Tcl 'open'

filename File name

channel Returned channel id

mode Optional (default a+) file open mode - see Tcl documentation for 'open'

Argument list: <f> <filename> <>

f Channel that file is open on

filename Optional argument used in error message to user if fails.

Argument list: <filename> <textVar> <args>

filename Name of file to read

textVar Returned text read from file

-split

Return the file as a list with each line from the file as a list element

-noblank

Do not return blank lines

-nocomment comment_char

Do not return 'comment' lines which begin with the character comment_char

Argument list: <filename> <nlines> <textVar> <args>

filename Name of file to read

nlines Number of lines to read

textVar Returned text read from file

-split

Return the text as a list with each line from the file as a list element

Argument list: <filename> <text> <args>

filename Name of file to write

text The text to write to the file

-overwrite

If file of name filename already exists then overwrite it - otherwise if file exists the procedure will fail

Argument list: <file>

Wrapper for 'file delete' with some error trapping.

DeleteFile can also be used to delete directories, if the 'file' is actually a directory name. Since the deletion command for directories is extremely powerful, the following mechanism has been implemented in an attempt to avoid accidental deletion of valuable directories:

1. The directory must be a subdirectory of a registered project, or a subdirectory in TEMPORARY. If neither of these criteria are met then a warning is displayed and the directory will not be deleted.

2. The user is prompted to confirm deletion of the directory before the operation is performed.

file Name of file or directory to delete

Argument list: <args>

FileWritable Return flag to say if file is writable

Argument list: <file>

Wrapper for 'file writable'

file Name of file to test

Argument list: <filein> <fileout> <args>

Wrapper for 'file rename' command

filein Name of source file

fileout Name of target file

Argument list: <filein> <fileout> <args>

Wrapper for 'file copy' command

filein Name of source file

fileout Name of target file

-overwrite

Force overwrite of existing file

Argument list: <filein> <fileout>

filein Source file name

fileout Target file name

Argument list: <filein> <args>

filein Name of uncompressed file

-uncompress

Uncompress the '.gz' file to recreate uncompressed file

-overwrite

Overwrite any existing file

Argument list: <filein>

filein Name of file (with or without the .gz extension)

Argument list: <file>

file Name of tar file

Argument list: None

Handling Directories

CreateDir Create a directory

Argument list: <dir>

the parent directory of the new directory must already exist

dir Full path name of directory

Argument list: <filein> <fileout>

Wrapper for 'file copy' command

filein Name of source directory

fileout Name of target directory

Argument list: <dir>

This is a wrapper for the Tcl cd command

dir Full path or appropriate relative path name

Parsing Files

Parsing Files

The following commands do some of the things that you might do with grep or awk

Argument list: <fileid> <search_string> <lineinc> <word_index>

Searches for a line matching search_string - the string match function is used and the wild cards * and ? may be used. Words from the matching text line or from a following line are returned.

filename input file name

search_string search string

lineinc extract from the lineinc'th line after the hit line

word_index List of indices of the required words. If word_index=0 return whole line.

Argument list: <line> <word_index>

line A text string

word_index A list of indices i - return the i'th word in the line - beware first word is index 0.

Argument list: <tt> <search_string> <lineinc> <word_index> <dataVar> <args>

Similar to ExtractTextFromFile. Find the line in text which a search string and then return some selected words from that line or from a specified number of lines ahead in the text.

tt Input text string - if this is '-' then search from the last hit line in text input to a previous call to ExtractTextLine

search_string String to search for in text - if input is blank text string the apply lineinc from the current position in the text and return the words as specified

line_inc Advance line_inc lines from finding search string before returning words

word_index Either a list of indices for words to return (first word in line has index 0) or 'all' to return entire line or 'last' to return last word.

Argument list: <tt> <search_string> <lineinc> <word_index> <args>

tt The input text to be searched. If is '-' then search from current place in previously input text

search_string Search for this text string. If input is empty string then return from the current line.

lineinc From 'hit' line step on {$lineinc} lines

word_index Tcl list of fields in the line to be returned. If ='all' return the whole line, if ='last' then return the last word.

Argument list: <args>

Return true (1) if the first argument is the same as any subsequent argument.

test Test string

compare Any number of text strings for comparison.

Socket Handling

Socket Handling

The following procedures are used by ccp4i processes which are acting clients to the main graphical ccp4i. For example loggraph acting as client to the sfanal task. This setup assumes that the process is a client of only one server. Most of the procedures are simple wrappers to Tcl fconfigure and puts/gets commands - see the Tcl documentation. Each CCP4i process stores information on sockets in the system array and OpenClientSocket saves this information which other procedures might use.

The server side sockets in the main ccp4i process is handled by procedures in src/local.tcl

Argument list: <server_host> <server_port> <args>

server_host Connect to a server side socket on the machine server_host This should be 'local' if the server is one the local machine.

server_port The server port number

-listen listen_handler

Listen for input from the server socket and when received call a procedure listen_handler and input to it the input from server.

Argument list: <sockid> <delay> <command>

This procedure is called by OpenClientSocket if the -listen option is used. ListenClientSocket does a gets to get any input from the socket and calls the specified command if there is input. ListenClientSocket then calls itself after a short time delay.

Argument list: <args>

-server

Test the server side socket

-client

Test the client side socket

-socket socket_id

Test the socket with id socket_id

Argument list: <message> <args>

message The text string to be written to the socket.

-server

Write to the server side socket

-client

Write to the client side socket

-socket socket_id

Write to the socket with id socket_id

Handling Data Types

Handling Data Types

toggle button: logical

menu: menu varmenu

Create*putLine widget: default_dir & file

CreateLabin widget: mtz_label

Not represented graphically: list datalist

Each data type has properties which are dependent on its class and the properties of each class are defined at the top of the types.def file.

Argument list: <arrayname> <element>

Returns a zero length string if does not find a datatype definition.

The data type is stored in the array element with the name _$element. For the 'indexed' elements (eg root,4 or root,4_2) which correspond to extending frames the data type is only stored once as _root,0 where root is the root of the element name.

Name of data array

element Name of element of array.

Argument list: <name> <c1> <c2>

Return string of form name,c1 or name,c1_c2

name The element name

c1 The first index number for the element

c2 Optional. The second index number for the element

Argument list: <element> <rootVar> <c1Var> <c2Var>

element Input element name

rootVar Return the root of the element name

c1Var Return the first index number

c2Var Return the second index number

Argument list: <name>

For 'indexed' elements (which are used in extending frames) the data type is stored only once as array(_root,0).

Argument list: <name>

GetTypeInfo Return some information which is a property of the data type of an element

Argument list: <arrayname> <element> <type> <warning> <warning>

The valid properties of any given data type are defined as a list in the typedef($class) parameter where class is the class of the data type

arrayname Name of data array

element The name of an array element for which a property value is required

type The property whose value is required. Or 'type' to return the data type class (yes it should be called class)

warning Optionally the argument is the word 'warning' to indicate that a warning message should be output is the property is not found

Argument list: <arrayname> <element> <typelistin>

arrayname Name of data array

element The name of an array element for which the property values are required

typelistin Returned. The full list of properties of the data type

Argument list: <arrayname> <element>

The problems are almost always due to not having the element defined in the def file or the data type defined in types.def (or elssewhere). And this is almost always due to a typo.

Argument list: <arrayname> <element>

arrayname Name of data array

element The name of an array element for which information not available.

Argument list: <arrayname> <arrayindex>

This information is stored as array(WIDGET_$element)

arrayname Name of data array

arrayindex The name of an array element

Argument list: <arrayname> <var> <type> <init>

This does what reading the def files usually does - is usually done in task_setup procedure

arrayname Name of array

var Name of element in array

type Data type for array element

init Initial value for array element

Argument list: <name> <menulist> <aliaslist> <>

Menu item aliases are the text which is written to a def file and passed to the run script. They are usually the keyword required by the program rather than the text presented to the user

name Name of the data type

menulist A list of the menu items. A Tcl list.

aliaslist Optional. A list of the aliases for the menu items. A Tcl list.

Return the value of an array element

This is most useful when the array element may be of a menu type, when it returns the menu alias rather than the actual value of the element.

arrayname Name of array

element Name of array element

Argument list: <arrayname> <element>

arrayname Name of array

element Name of array element

Argument list: <arrayname> <element> <value>

The array element must be associated with a menu widget this procedure returns the menu text associated with a given value of the element.

arrayname Array name

element The element of the array - must have a menu type

value The one-word value of the array element

Set a menu array element to the value for a specified alias value

arrayname Array name

element The element of the array - must have a menu type

value The one-word value of the array element

Handling Arrays

GetIndexedElements Return all the indexed elements in an array with a given root

Argument list: <arrayname> <element> <c1> <>

Or optionally all the elements with a given root and first index. The returned list does NOT include the 'zero' element which is root,0 or root,n for elements with two indices.

arrayname Name of array

element The root of an element name

c1 Optional. The first index of the element

Argument list: <arrayname> <element> <c1> <>

Or optionally all the elements with a given root and first index. The returned list DOES include the 'zero' element which is root,0 or root,n for elements with two indices.

arrayname Name of array

element The root of an element name

c1 Optional. The first index of the element

Argument list: <arrayname> <nelements> <indexname> <listout>

Only used in tasks/import.tcl.

arrayname Name of array

The name of the element which is the counter for the indexed element indexname

The name of an indexed array element

The name of an array element to contain the list of values

Argument list: <arrayname> <arrayname1>

Only used in pre5.0 Refmac to copy from protin array

arrayname Name of source array

arrayname1 Name of target array

Argument list: <arrayname> <arrayname1>

Differs from CopyArray in that it copies the values directly and for all elements in the source array

arrayname Name of source array

arrayname1 Name of target array

Argument list: <arrayname> <var> <nmax>

arrayname Name of array

var Root of indexed array element name

nmax The number of instances of the indexed element

Argument list: <root>

Returns a unique name which is root_n which n in positive integer.

root A root name for the array

Argument list: <arrayname> <var> <text>

arrayname Name of data array

var Element name for indexed elements

text The search text

Argument list: <arrayname>

arrayname Name of array

Simple Mathematical Functions

max Return the maximum value of the values in the argument list

Argument list: <args>

min Return the minimum value of the values in the argument list

Argument list: <args>

iremainder Return the mod of n and m

Argument list: <n> <m>

Could be replaced by expr fmod (? implemented in 8.0)

Argument list: <stackVar> <levelVar> <value>

stackVar Input/output the stack variable - a Tcl list

levelVar Input/output the number of levels on the stack

value Input value to push onto stack

Argument list: <stackVar> <levelVar>

stackVar Input/output the stack variable - a Tcl list

levelVar Input/output the number of levels on the stack

value Output value from top of stack

Argument list: <input> <prec>

input Input real number

Maximum number of decimal places output

Argument list: <listin> <orderVar> <mode>

This function is used when you want to reorder one 'target' list based on sorting of another 'sortable' list which has a one-to-one matching with the target list. The target list is input to sortorder and the sorting mode can be anything supported by Tcl lsort command. The returned 'order' list is the positions in the input list of the items in sorted order. This order list can be used to pick out items from the target list to reorder that list.

listin Input 'sortable' list

orderVar Output list of item position in listin for sorted list

mode (Optional) mode argument to Tcl lsort

String Handling

IfSet Test if input argument(s) are not blank strings

Argument list: <args>

This procedure is most used in interpreting com file by CreateComScript In that context the IfSet command is usually wrapped by a catch command which will safely handle the case where the variable input to IfSet is completely undefined.

var Any number of input arguments

Argument list: <args>

Return true (1) if the first argument is the same as any subsequent argument

test Test string

compare Any number of text strings for comparison

Argument list: <namein> <args>

The removed characters (excluding leading/trailing spaces) are replaced with an underscore

namein Input text string

-space

Allow spaces in the text (default is to remove)

-title

For title text also allow - _ , . ( ) /

-report

Give warning message to user

Argument list: <path> <retpathVar>

The input to this procedure is the first component of a file name. The procedure will return the full path name for this component. The return status is 1 = substitution successful, 0 = no substitution necessary or -1 = error in input

path Input first component of a file path name

retpathVar Output the full expansion of the input path.

Argument list: <boxlist> <job_list> <display> <display_format>

Each entry is processed to see if its content correspond to a colour-coding present in the configuration.

boxlist the listbox whose entries are to be colourised

job_list the list of jobs that will be filled in the listbox

Argument list: <task> <status> <title> <counter> <0>

Returns a list of two values - the first is the foreground colour i.e. that used for the text, the second is the background colour, according to the settings specified in the configure array.

The optional argument counter can be used to indicate which of the striped backgrounds should be used, but is over-ridden if an explicit

task The name of the task

status The job status

title The job title

counter (optional) Used for job striping

Handling Data Harvesting "Central Deposit" Location

SetCentralDeposit Set the CENTRAL_DEPOSIT location for data harvesting

Argument list: <central_deposit>

Set the value of the CENTRAL_DEPOSIT parameter, which specifies a "central" directory for the user's harvesting files.

central_deposit The directory path for the CENTRAL_DEPOSIT location

Argument list: None

Return the previously stored value of CENTRAL_DEPOSIT, or {} if no value is currently stored.