Actions
-------

Actions are user-defined Tcl scripts which can be run from within
PGBrowse.  Each action is in its own "action" directory.  Action
directories are in turn grouped into "site" directories.  PGBrowse will
search for "sites" listed in the colon-separated PGBACTIONS envariable
and then the $PGBROWSE/actions directory.

Each action directory must contain the file "pgb.init" which
must at least:

  o	set the "Name" variable to the name of the action
  o	define a procedure called "Action" which takes one arguement,
	the full pathname to the action directory 

Optionally, pgb.init can:

  o	set the "Help" variable to suitable HelpText 
  o	set the "Type" variable to a list of intended types for the action


Pgb.init is sourced twice, once when PGBrwose scans all avaiable actions
for their Name (and possibly Help and/or Type variables) and again just
before the Action procedure is invoked.  Since actions run under the
same interpreter as PGBrowse, they can call any available procedures.
Aside from the utility routines in tku.tcl, the procedures ActionColNum
and ActionGetCol are useful for extracting data from the Query Results
window; ActionColNum returns the number of a requested column name (or
an alternative if the requested column doesn't exists) and ActionGetCol
returns the data in a column.

Here are some simple actions:

  o	Popup a Hello World box using a tku.tcl utility:

	set Name "Hello World"
	proc Action {ignored} {Tku_NoticeBox "Hello World"}


  o	use the ActionColNum and ActionGetCol routines to get data
	from the query results window:

	set Name "Dump pg_usename"
	set Help "This routine dumps the contents of the pg_usename to stdout"
	proc Action {ignored} {
	    # ask for the column number for the pg_usename field
	    if {[set col [ActionColNum pg_usename]] == -1} return
	    # dump the column
	    puts stdout [ActionGetCol $col]
	}

  o	copy the selected filenames to a new directory:


	set Name "File Copy"
	set Help "Copies files to a directory"
	proc Action {ignored} {
	    # use a tku.tcl utility to get a directory name
	    if {[set newdir [Tku_FdDir]] == ""} return
	    # get a list of filenames and copy them
	    if {[set col [ActionColNum filename]] == -1} return
	    foreach file [ActionGetCol $col] {
		if [catch {exec cp $file $newdir} err] {
			Tku_Error "Copy error on file: $file:  $err"
			return
		}
	    }
	}

  o	run a program stored in the action directory on each file:

	set Name "Process Files"
	set Help "Run each file through mypgm"

	proc Action {dir} {
	    if ![file exists $dir/mypgm] {
		Tku_ErrorBox "mypgm is not in the action directory: $dir"
		return
	    }
	    if {[set col [ActionColNum filename]] == -1} return
	    foreach file [ActionGetCol $col] {exec $dir/mypgm < $file}
	}




$Id: README,v 1.1 1993/12/06 18:20:49 jimbo Exp $
