This page describes how to write modules for use with Pipeline version 2.0, the latest release of my Unix - perl 5 implementation of CGI FPI.
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:
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 moduleYour 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. ProcessingAfter 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). OutputThe 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 subroutineThe 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: startmail subroutineThe 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 moduleThis 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. |
7 January 1997