Pipeline.pl Module Development

Why write pipeline.pl modules?

Writing pipeline.pl modules are an easy way to write to do things that you would normally need to write full CGI scripts to do. Some advantages are:

• You don't need to worry about getting the input.
• You can have command line-type arguments (called pipeline arguments) to your scripts, unlike in raw CGI.
• Other modules can be used in addition to yours, possibly helping your module or possibly helping those that follow yours.
• Debugging support

How do I write modules that use pipeline.pl?

See the interface guidelines in this section. You might also want to look at the HFPM modules as examples. If you let me know about a releasable module you wrote, I'll probably link to it.

Starting your module

Your module (with pipeline arguments) needs to be specified on the _pipeline field to get started. A file with the name on the pipeline is looked for, using the _path field if necessary. The file (your module) is then run and the result value of the module used as a subroutine to run. The routine is invoked with the first argument being a instance of the CGI.pm Perl class and the remaining arguments being the pipeline arguments.

Processing

After your module is started, you can do more-or-less anything you want. The fields and their values are available from the CGI.pm object and environmental variable are available through %ENV.

You may also call the reporterr subroutine to give warnings or errors to the user of your module (or to give debugging info to yourself).

Output

The fields and environmental variables are passed as you left them to the next module in the pipeline (if there is any).

You may also "print" to stdout as a means of returning something to the user. You do this in the same way as you normally do in CGI scripts. Note that if previous or following modules also output to stdout, this may cause problems.

reporterr subroutine

The reporterr subroutine provides a means of telling the user of your module of problems in configuration. The first argument is a string to use as the message. The second argument is 0 is the error is non-fatal and 1 if pipeline.pl should exit as a result.

If the _errorsto field is set, the error message is e-mailed to the e-mail address specified therein. Otherwise it is output to stdout. A couple examples:
&reporterr("Could not open \"$path\" for write.\nHint: try \"chmod +w $path\".",0)
@mailto || reporterr('no recipients found for e-mail',1);

startmail subroutine

The startmail subroutine provides support for sending e-mail from a module. This routine invokes sendmail (in the location specified in the SENDMAIL variable in pipeline.pl), provides certain mail headers, then returns an indirect filehandle to add further headers then a message body. The argument to startmail is the place to send the e-mail to, and, if the REFERER_URL environmental variable is defined, it is included in an "X-URL" mail header. Further headers can be added by printing to the filehandle. An empty line separates the headers from the main body of the message. A close on the filehandle to be sent. An real-life example:

sub mail_error { my($dest,$msg)= @_; $fh= &startmail($dest); print $fh "Subject: Pipeline error\n\n"; print $fh "$msg\n"; close $fh; return 1; }

Example module

This is an annotated version of the set.pl HFPM module:

	#!/usr/bin/perl
	
	sub process {                   the routine to call
	  my ($input,@args)= @_;        the arguments to the routine
	  foreach (@args) {
		($dest,$val)= split('=',$_,2);
		$dest =~ s/^([\$\%])//;
		if ($1 eq '%') { # env. var
		  $ENV{$dest}= $val;
		} else {
		  $input->param($dest,$val);
		}
	  }
	};
	
	\&process;                      returning the routine
	

Help!

If you have any questions that aren't answered by this online documentation, feel free to e-mail webmaster@hoagland.org for more information or with questions.

Peace and long life.