CIPP - Reference Manual
perldoc CIPP::Manual
This is the reference manual for CIPP, the powerful preprocessor language for embedding Perl and SQL in HTML. This documentation module is part of the CIPP distribution which is available on CPAN.
The manual describes all CIPP commands in alphabetical order. Each reference contains syntax notation, textual description and examples for each command.
This document is a excerpt from the full CIPP documentation which is available as PDF format. You can download the PDF document from CPAN:
$CPAN/modules/by-authors/id/J/JR/JRED/CIPP-DOC-x.xx.tar.gz
The conversion of the FrameMaker source document to the POD format is done automatically. Due to this the layout maybe slightly messed up in some sections, but everything should be readable nevertheless. If you don't like this please refer to the PDF document which has a clean layout.
If your perldoc is using 'less' or 'view' for paging, it is quite easy to jump to a particular command description.
E.g. if you want to read the <?FOO> section, simply type this.
/COMMAND...FOO
This is a alphabetical list of all CIPP commands with a short description, divided into sections of command types.
Creation of a block context to limit the scope of private variables
Declaring a private (block local) variable
Definition of a variable
Loop with condition check after first iteration
Alternative execution of a block
Subsequent conditional execution
Loop iterating with a variable over a list
Conditional execution of a block
Insertion of pure Perl code
Definition of a Perl subroutine
Loop with condition check before first iteration
Import a config file
Insertion of a CIPP Include file in the actual CIPP code
Definition of a CIPP Perl Module
Import a CIPP Perl Module
Import a standard Perl module
Execution of a block if a particular exception was thrown in a preceding TRY block.
Write a entry in a logfile.
Explicite creation of an exception.
Secured execution of a block. Any exceptions thrown in the encapsulated block are caught.
Control of transaction behaviour
Commit a transaction
Quoting of a variable for usage in a SQL statement
Returns the internal DBI database handle
Rollback a transaction
Execution of a SQL statement
Creation of a CIPP object URL
Producing a number of hidden formular fields
HTML encoding of a variable
URL encoding of a variable
Replaces <A> tag
Replaces <FORM> tag
Replaces <IMG> tag
Replaces <INPUT> tag, with sticky feature
Replaces <OPTION> tag, with sticky feature
Replaces <SELECT> Tag, with sticky feature
Replaces <TEXTAREA> tag
Recieving a non declared CGI input parameter
Returns a list of all CGI input parameter names
Declaration of a interface for CIPP Include
Declaration of a CGI interface for a CIPP program
Storing a client side upload file
Returns the internal Apache request object
Redirects to another URL internally
Controls automatic output of HTML code
Dynamic generation of a HTTP header
Initiate generation of profiling code
Dumps preformatted contents of data structures
Print arbitrary Perl expressions
Miscellaneous
<?> # arbitrary Perl Expression to be printed <?/>
This result of the Perl expression inside this block will be printed. Do not use this construct to print simple variables or generally Perl expressions which can be evaluated in a quoted string context. Simply write such expressions direct inside a HTML context into your document (see examples below).
This examples show some handy cases for this construct:
# method call with printing the result
<?>$object->get_attribute<?/>
# print actual unix timestamp
<?>time<?/>
# calculate something and print the result
<?>(time + 34800) * $$<?/>
# This is possible, but unnecessary
Value of a variable: <?>$foo<?/>
# instead simply write this:
Value of a variable: $foo
Multi Line Comment
<?#> ... <?/#>
This block command realizes a multiline comment. Simple comments are introduced with a single # sign, so you can only comment one line with them. All text inside a <?#> block will be treated as a comment and will be ignored. Nesting of <?#> is allowed.
This is a simple multi line comment.
<?#> This text will be ignored. All CIPP tags too. So this is no syntax error <?IF foo bar> <?/#>
You may nest <?#> blocks:
<?#> bla foo <?#> foo bar <?/#> <?/#>
HTML Tag Replacement
<?A HREF=hyperlinked_object_name[#anchor] [ additional_<A>_parameters ... ] > ... <?/A>
This command replaces the <A> HTML tag. You will need this in a new.spirit environment to set a link to a CIPP CGI or HTML object.
This parameter takes the name of the hyperlinked object. You may optionally add an anchor (which should be defined using <A NAME> in the referred page) using the # character as a delimiter.
This paremeter is expected as an URL in CGI::CIPP or Apache::CIPP environments and in dot-separated object notation in a new.spirit environment.
-s
All additional parameters are taken into the generated <A> tag.
Textual link to 'MSG.Main', in a new.spirit environment.
<?A HREF="MSG.Main">Back to the main menu<?/A>
Image link to '/main/menu.cgi', in a CGI::CIPP or Apache::CIPP environment:
<?A HREF="/main/menu.cgi"> <?IMG SRC="/images/logo.gif" BORDER=0> <?/A>
Apache
<?APGETREQUEST [ MY ] VAR=request_variable >
This command is only working if CIPP is used as an Apache module.
It returns the internal Apache request object, so you can use Apache specific features.
This is the variable where the request object will be stored.
If you set the MY switch, the created variable will be declared using 'my'. Its scope reaches to the end of the block which surrounds the APGETREQUEST command.
The Apache request object will be stored in the implicitely declared variable $ar.
<?APGETREQUEST MY VAR=$ar>
<?APREDIRECT URL=new_URL >
It results in an internal Apache redirect. That means, the new url will be 'executed' without notifying the client about this.
This expression is used for the new URL.
The program which uses <?APREDIRECT> should not produce any output, otherwise this may confuse the webserver or the client, if more then one HTTP header is sent. So you should use <?AUTOPRINT OFF> at the top of the program to circumvent that.
This commands redirect internally to the homepage of the corresponding website:
<?AUTOPRINT OFF> <?APREDIRECT URL="/">
SQL
<?AUTOCOMMIT ( ON | OFF ) [ DB=database_name ] [ DBH=database_handle ] [ THROW=exception ] >
The <?AUTOCOMMIT> command corresponds directly to the underlying DBI AutoCommit mechanism.
If AutoCommit is activated each SQL statement will implicitely be executed in its own transaction. Think of a <?COMMT> after each statement. Explicite use of <?COMMIT> or <?ROLLBACK> is forbidden in AutoCommit mode.
If AutoCommit is deactivated you have to call <?COMMIT> or <?ROLLBACK> yourself. CIPP will rollback any uncommited open transactions at the end of the program.
Switch AutoCommit modus either on or off.
This is the CIPP internal name of the database for this command. In CGI::CIPP or Apache::CIPP environment this name has to be defined in the appropriate global configuration. In a new.spirit environment this is the name of the database configuration object in dot-separated notation.
If DB is ommited the project default database is used.
Use this option to pass an existing DBI database handle, which should used for this SQL command. You can't use the DBH option in conjunction with DB.
With this parameter you can provide a user defined exception which should be thrown on failure. The default exception thrown by this statement is autocommit.
If the underlying database is not capable of transactions (e.g. MySQL) setting AutoCommit to ON will throw an exception.
Switch AutoCommit on for the database 'foo'.
<?AUTOCOMMIT ON DB="foo">
Switch AutoCommit off for the database 'bar' and throw the user defined exception 'myautocommit' on failure.
<?AUTOCOMMIT OFF DB="bar" THROW="myautocommit">
Preprocessor
<?!AUTOPRINT OFF>
With the <?!AUTOPRINT OFF> command the preprocessor can be advised to suppress the generation of print statements for non CIPP blocks. The default setting is ON and it is only possible to switch it OFF and not the other way around.
In earlier versions of CIPP this command was named <?AUTOPRINT>. This notation is depreciated, but will work for compatability reasons.
Automatic generation of print statements for non CIPP blocks will be deactivated.
This is a preprocessor command. Please read the chapter about preprocessor commands for details about this.
You should use this command at the very top of your program file. CIPP will not generate any HTTP headers for you, if you use <?!AUTOPRINT OFF>, so you have to do this on your own. If you only want to generate a special HTTP header, use <?!HTTPHEADER> instead.
The ,CIPP Introduction" Chapter contains a paragraph about CIPP Preprocessor Commands. Please refer to this discussion for details of <?!AUTOPRINT>.
This program sends a GIF image to the client, after generating the proper HTTP header. (For another example, see <?APREDIRECT>)
<?AUTOPRINT OFF> These lines will never be printed, they are fully ignored!!! <?PERL> my $file = "/tmp/image.gif"; my $size = -s $file; print "Content-type: image/gif\n"; print "Content-length: $size\n\n"; open (GIF, $file) or die "can't open $file"; while (<GIF>) { print; } close GIF; <?/PERL>
Variables and Scoping
<?BLOCK> ... <?/BLOCK>
Use the <?BLOCK> command to divide your program into logical blocks to control variable scoping. Variables declared with <?MY> inside a block are not valid outside.
The variable $example does not exist beyond the block.
<?BLOCK> <?MY $example> $example is known. <?/BLOCK>
$example does not exist here. This will
result in a Perl compiler error, because
$example is not declared here.
Exception Handling
<?CATCH [ THROW=exception ] [ MY ] [ EXCVAR=variable_for_exception ] [ MSGVAR=variable_for_error_message ] > ... <?/CATCH>
Typically a <?CATCH> block follows after a <?TRY> block. You can process one particular or just any exception with the <?CATCH> block.
<?CATCH> and <?TRY> has to be placed inside the same block.
See the description of <?TRY> for details about the CIPP exception handling mechanism.
If this parameter is omitted, all exceptions will be processed here. Otherwise the <?CATCH> block is executed only if the appropriate exception was thrown.
Names the variable, where the exception identifier should be stored in. Usefull if you use <?CATCH> for a generic exception handler and omitted the THROW parameter.
Name the variable, where the error message should be stored in.
If you set the MY switch the created variable will be declared using 'my'. Its scope reaches to the end of the block which surrounds the <?CATCH> command.
We try to insert a row into a database table, which has a primary key defined, and commit the transcation. We catch two exceptions: the possible primary key constraint violation and a possible commit exception, maybe the database is not capable of transactions.
<?TRY> <?SQL SQL="insert into persons (firstname, lastname) values ('John', 'Doe')"><?/SQL> <?COMMIT> <?/TRY> <?CATCH THROW=sql MY MSGVAR=$message> <?LOG MSG="Can't insert data: $message" TYPE="database"> <?/CATCH> <?CATCH THROW=commit MSGVAR=$message> <?LOG MSG="COMMIT rejected: $message" TYPE="database"> <?/CATCH>
<?COMMIT [ DB=database_name ] [ DBH=database_handle ] [ THROW=exception ] >
The <?COMMIT> command concludes the actual transaction and makes all changes to the database permanent.
Using <?COMMIT> in <?AUTOCOMMIT ON> mode is not possible.
If you are not in <?AUTOCOMMIT ON> mode a transaction begins with the first SQL statement and end either with a <?COMMIT> or <?ROLLBACK> command.
With this parameter you can provide a user defined exception which should be thrown on failure. The default exception thrown by this statement is commit.
If the underlying database is not capable of transactions (e.g. MySQL) execution of this command will throw an exception.
We insert a row into a database table and commit the change immediately. We throw a user defined exeption, if the commit fails. So be safe we first disable AutoCommiting.
<?AUTOCOMMIT OFF> <?SQL SQL="insert into foo (num, str) values (42, 'bar');"> <?/SQL> <?COMMIT THROW="COMMIT_Exception">
Import
<?CONFIG NAME=config_file [ RUNTIME ] [ NOCACHE ] [ THROW=exception ] >
The <?CONFIG> command reads a config file. This is done via a mechanism similar to Perl's require, so the config file has to be pure Perl code defining global variables.
<?CONFIG> ensures a proper load of the configuration file even in persistent Perl environments.
In contrast to "require" <?CONFIG> will reload a config file when the file was altered on disk. Otherwise the file will only be loaded once.
This is the name of the config file, expected as an URL in CGI::CIPP or Apache::CIPP environments and in dot-separated object notation in a new.spirit environment.
This switch makes sense only in a new.spirit environment. If you set it the NAME parameter will be resolved at runtime, so it can contain variables. new.spirit will not check the existance of the file in this case. Normally you'll get a CIPP error message, if the adressed file does not exist.
In CGI::CIPP and Apache::CIPP environments the NAME parameter will always be resolved at runtime.
This switch is useful in persistant Perl environments. It forces <?CONFIG> to read the config file even if it did not change on disk. You'll need this if your config file does some calculations based on the request environment, e.g. if the value of some variables depends on the clients user agent.
With this parameter you can provide a user defined exception to be thrown on failure. The default exception thrown by this statement is config.
An exception will be thrown, if the config file does not exist or is not readable.
Load of the configuration file "/lib/general.conf", with disabled cache, used in CGI::CIPP or Apache::CIPP environment:
<?CONFIG NAME="/lib/general.conf" NOCACHE>
Load of the configuration file object x.custom.general in a new.spirit environment:
<?CONFIG NAME="x.custom.general">
Load of a config file with a name determined at runtime, in a new.spirit environment, throwing "myconfig" on failure:
<?CONFIG NAME="$config_file" RUNTIME THROW="myconfig">
<?DBQUOTE VAR=variable [ MY ] [ DBVAR=quoted_result_variable ] [ DB=database_name ] [ DBH=database_handle ] >
<?SQL> (and DBI) has a nice way of quoting parameters to SQL statements (called parameter binding). Usage of that mechanism is generally recommended (see <?SQL> for details). However if you need to construct your own SQL statement, <?DBQUOTE> will let you do so.
<?DBQUOTE> will generate the string representation of the given scalar variable as fit for an SQL statement. That is, it takes care of quoting special characteres.
This is the scalar variable containing the parameter you want to be quoted.
This optional parameters takes the variable where the quoted content should be stored. The surrounding ' characters are part of the result, if the variable is not undef. A value of undef will result in NULL (without the surrounding '), so the quoted variable can be placed directly in a SQL statement.
If you ommit DBVAR, the name of the target variable is computed by placing the prefix 'db_' in front of the VAR name.
If you set the MY switch the created variable will be declared using 'my'. Its scope reaches to the end of the block which surrounds the <?DBQUOTE> command.
This quotes the variable $name, the result will be stored in the just declared variable $db_name.
<?DBQUOTE MY VAR="$name">
This quotes $name, but stores the result in the variable $quoted_name.
<?DBQUOTE VAR="$name" MY DBVAR="$quoted_name">
The quoted variable can be used in a SQL statement this way:
<?SQL SQL="insert into persons (name) values ( $quoted_name )">
Control Structure
<?DO> ... <?/DO COND=condition >
The <?DO> block repeats executing the contained code as long as the condition evaluates true. The condition is checked afterwards. That means that the block will always be executed at least once.
This takes a Perl condition. As long as this condition is true the <?DO> block will be repeated.
Print "Hello World" $n times. (note: for n=0 and n=1 you get the same result)
<?DO> Hello World<BR> <?/DO COND="--$n > 0">
Debugging
<?DUMP $var_1 ... $var_n>
The <?DUMP> command dumps the contents of the given variables using Data::Dumper, inside of a HTML <pre></pre> block.
$var_1 .. $var_n
The contents of this variables are dumped to STDOUT.
<?DUMP $hash_ref $list_ref>
<?ELSE>
<?ELSE> closes an open <?IF> or <?ELSIF> conditional block and opens a new block (which is later terminated by <?/IF>). The block is only executed if the condition of the preceding block was evaluated and failed.
<?MY> variables are only visible inside this block.
(Or short: it works as you would expect.)
Only Larry gets a personal greeting message:
<?IF COND="$name eq 'Larry'"> Hi Larry, you're welcome! <?ELSE> Hi Stranger! <?/IF>
<?ELSIF COND=condition >
<?ELSIF> closes an open <?IF> or <?ELSIF> conditional block and opens a new block. The condition is only evaluated if the condition of the preceding block was evaluated and failed.
Takes the Perl condition.
Larry and Linus get personal greeting messages:
<?IF COND="$name eq 'Larry'"> Hi Larry, you're welcome! <?ELSIF COND="$name eq 'Linus'"> Hi Linus, you're velkomma! <?ELSE> Hi Stranger! <?/IF>
<?FOREACH [ MY ] VAR=running_variable LIST=perl_list > ... <?/FOREACH>
<?FOREACH> corresponds directly the Perl foreach command. The running variable will iterate of the list, executing the enclosed block for each value of the list.
This is the scalar running variable.
You can write any Perl list here, e.g. using the bracket notation or pass a array variable using the @ notation.
If you set the MY switch the created running variable will be declared using 'my'. Its scope reaches to the end of the block which surrounds the <?FOREACH> command.
Note: this is a slightly different behaviour compared to a Perl "foreach my $var (@list)" command, where the running variable $var is valid only inside of the foreach block.
Counting up to 'three':
<?FOREACH MY VAR="$cnt" LIST="('one', 'two', 'three')"> $cnt <?/FOREACH>
<?FORM ACTION=cgi_file [ additional_<FORM>_parameters ... ] > ... <?/FORM>
<?FORM> generates a HTML <FORM> tag, setting the ACTION option to the appropriate URL. The request METHOD defaults to POST if no other value is given.
This is the name of the form target CGI program, expected as an URL in CGI::CIPP or Apache::CIPP environments and in dot-separated object notation in a new.spirit environment.
All additional parameters are taken over without changes into the produced <FORM> tag. If you ommit the METHOD parameter it will default to POST.
Creating a named form with a submit button, pointing to the CGI object "x.login.start", in a new.spirit environment:
<?FORM ACTION="x.login.start" NAME="myform"> <?INPUT TYPE=SUBMIT VALUE=" Start "> <?/FORM>
Creating a similar form, but the action is written as an URL because we are in CGI::CIPP or Apache::CIPP environment:
<?FORM ACTION="/login/start.cgi" NAME="myform"> <?INPUT TYPE=SUBMIT VALUE=" Start "> <?/FORM>
<?GETDBHANDLE [ DB=database_name ] [ MY ] VAR=handle_variable >
This command returns a reference to the internal Perl database handle, which is the object references returned by DBI->connect.
With this handle you are able to perform DBI specific functions which are currently not directly available through CIPP.
This is the variable where the database handle will be stored.
If you set the MY switch the created variable will be declared using 'my'. Its scope reaches to the end of the block which surrounds the <?GETDBHANDLE> command.
We get the database handle for the database object 'x.Oracle' in a new.spirit environment and perform a select query using this handle.
Ok, you simply can do this with the <?SQL> command, but now you can see how much work is done for you through CIPP :)
<?GETDBHANDLE DB="MSG.Oracle" MY VAR="$dbh"> <?PERL> my $sth = $dbh->prepare ( qq{ select n,s from TEST_table where n between 10 and 20 }); die "my_sql\t$DBI::errstr" if $DBI::errstr; $sth->execute; die "my_sql\t$DBI::errstr" if $DBI::errstr; my ($n, $s); while ( ($n, $s) = $sth->fetchrow ) { print "n=$n s=$s<BR>\n"; } $sth->finish; die "my_sql\t$DBI::errstr" if $DBI::errstr; <?/PERL>
Interfaces
<?GETPARAM NAME=parameter_name [ MY ] [ VAR=content_variable ] >
With this command you can explicitely get a CGI parameter. This is useful if your CGI program uses dynamically generated parameter names, so you are not able to use <?INTERFACE> for them.
Refer to <?INTERFACE> to see how easy it is to handle standard CGI input parameters.
Identifier of the CGI input parameter
This is the variable where the content of the CGI parameter will be stored. This can be either a scalar variable (indicated through a $ sign) or an array variable (indicated through a @ sign).
If you set the MY switch the created variable will be declared using 'my'. Its scope reaches to the end of the block which surrounds the <?GETPARAM> command.
We recieve two parameters, one staticly named parameter and one scalar parameter, which has a dynamic generated identifier.
<?GETPARAM NAME="listparam" MY VAR="@list"> <?GETPARAM NAME="scalar$name" MY VAR="$scalar">
<?GETPARAMLIST [ MY ] VAR=variable >
This command returns a list containing the identifiers of all CGI input parameters.
This is the variable where the identifiers of all CGI input parameters will be stored in. It must be an array variable, indicated through a @ sign.
If you set the MY switch the created list variable will be declared using 'my'. Its scope reaches to the end of the block which surrounds the <?GETPARAMLIST> command.
The list of all CGI input parameter identifiers will be stored into the array variable @input_param_names.
<?GETPARAMLIST MY VAR="@input_param_names">
URL and Form Handling
<?GETURL NAME=object_file [ MY ] VAR=target_variable [ RUNTIME ] [ THROW=exception ] > [ PARAMS=parameters_variables ] [ PAR_1=value_1 ... PAR_n=value_n ] >
This command returns a URL, optionally with parameters. In a new.spirit environment you use this to resolve the dot-separated object name to a real life URL.
In CGI::CIPP and Apache::CIPP environments this is not necessary, because you work always with real URLs. Nevertheless it also useful there, because its powerfull possibilities of generating parmeterized URLs.
This is the name of the specific file, expected as an URL in CGI::CIPP or Apache::CIPP environments and in dot-separated object notation in a new.spirit environment.
This is the scalar variable where the generated URL will be stored in. In earlier versions of CIPP this option was named URLVAR. The usage of the URLVAR notation is depreciated, but it works for compatibility reasons. To prevent from logical errors CIPP throws an error if you use URLVAR and VAR inside of one command (e.g. to create an URL which contains a parameter called VAR or URLVAR).
Depreciated. See description of VAR.
If you set the MY switch the created variable will be declared using 'my'. Its scope reaches to the end of the block which surrounds the <?GETURL> command.
This switch makes only sense in a new.spirit environment. The NAME parameter will be resolved at runtime, so it can contain variables. CIPP will not check the existance of the file in this case. Normally you get a CIPP error message, if the adressed file does not exist.
With this parameter you can define the exception to be thrown on failure. The default exception thrown by this statement is geturl.
An exception will be thrown, if the adressed file does not exist.
This takes a comma separated list of parameters, which will be encoded and added to the generated URL. You may pass scalar variables (indicated through the $ sign) and also array variables (indicated through the @ sign).
With the PARAMS option you can only pass parameters whose values are stored in variables with the same name (where case is significant). The variables listed in PARAMS will be treated case sensitive.
Any additional parameters to <?GETURL> are interpreted as named parameters for the URL. You can pass scalar and array values this way (using $ and @). Variables passed this way are seen by the called program as lower case written variable names, no matter which case you used in <?GETURL>.
It is highly recommended to use lower case variable names. Due to historical reasons CIPP converts parameter names to lower case without telling you about it. If this ever gets "fixed" and you have uppercase latters, your code will break. So, use lowercase.
We are in a new.spirit environment and produce a <IMG> tag, pointing to a new.spirit object (btw: the easiest way of doing this is the <?IMG> command):
<?GETURL NAME="x.Images.Logo" MY VAR=$url> <IMG SRC="$url">
Now we link the CGI script "/secure/messager.cgi" in a CGI::CIPP or Apache::CIPP environment. We pass some parameters to this script. (Note the case sensitivity of the parameter names, we really should use lower case variables all the time!)
<?VAR MY NAME=$Username>hans<?/VAR> <?VAR MY NAME=@id>(1,42,5)<?/VAR> <?GETURL NAME="/secure/messager.cgi" MY VAR=$url PARAMS="$Username, @id" EVENT=delete> <A HREF="$url">delete messagse</A>
The CGI program "/secure/messager.cgi" recieves the parameters this way (note that the $Username parameter is seen as $Username, but EVENT is seen as $event). If you find this confusing, use always lower case variable names.
<?INTERFACE INPUT="$event, $Username, @id"> <?IF COND="$event eq 'delete'"> <?MY $id_text> <?PERL>$id_text = join (", " @id)<?PERL> You are about to delete $username's ID's?: $id_text<BR> <?/IF>
<?HIDDENFIELDS [ PARAMS=parameter_variables ] [ PAR_1=value_1 ... PAR_n=value_n ] >
This command produces a number of <INPUT TYPE=HIDDEN> HTML tags, one for each parameter you specify. Use this to transport a bunch of parameters via a HTML form. This command takes care of special characters in the parameter values and quotes them if necessary.
This takes a comma separated list of parameters, which will be encoded and transformed to a <INPUT TYPE=HIDDEN> HTML tag. You may pass scalar variables (indicated through the $ sign) and also array variables (indicated through the @ sign).
With the PARAMS option you can only pass parameters whose values are stored in variables with the same name (where case is significant).
Any additional parameters to <?HIDDENFIELDS> are interpreted as named parameters. You can pass scalar and array values this way (using $ and @). Variables passed this way are seen by the called program as lower case written variable names, no matter which case you used in <?HIDDENFIELDS>.
This is a form in a new.spirit environment, pointing to the object "x.secure.messager". The two parameters $username and $password are passed via PARAMS, the parameter "event" is set to "show".
<?FORM ACTION="x.secure.messager"> <?HIDDENFIELDS PARAMS="$username, $password" event="show"> <INPUT TYPE=SUBMIT VALUE="show messages"> <?/FORM>
<?HTMLQUOTE VAR=variable_to_encode [ MY ] HTMLVAR=target_variable >
This command quotes the content of a variable, so that it can be used inside a HTML option or <TEXTAREA> block without the danger of syntax clashes. The following conversions are done in this order:
& => & < => < " => "
This non-optional parameter takes the variable where the quoted content will be stored.
If you set the MY switch the created variable will be declared using 'my'. Its scope reaches to the end of the block which surrounds the <?HTMLQUOTE> command.
We produce a <TEXTAREA> tag with a quoted instance of the variable $text. Note: you can also use the <?TEXTAREA> command for this purpose.
<?HTMLQUOTE VAR="$text" MY HTMLVAR="$html_text"> <TEXTAREA NAME="text">$html_text</TEXTAREA>
<?!HTTPHEADER [ MY ] VAR=http_header_hash_ref > # Perl Code which modifies the # http_header_hash_ref variable <?/!HTTPHEADER>
Use this command, if you want to modify the standard HTTP header response. CIPP generates by default a simple HTTP header of this form:
Content-type: text/html\n\n
In a new.spirit environment you can define a project wide default HTTP header extension, e.g. ,Pragme: no-cache", or something similar.
If you want to modify the HTTP header at runtime, you can use this command. The <?!HTTPHEADER> command switches to Perl context, so you write Perl code inside the block. The variable you declared with the VAR option is accessable inside this block and will contain a reference to a hash containing the default HTTP header tags. Your Perl code now can delete, add or modifiy HTTP header tags.
But be careful: because <?!HTTPHEADER> is a preprocessor command, the position of the <?!HTTPHEADER> command inside your CIPP program (even if you use it inside an Include), does not indicate the time, on which your HTTP header code is executed.
CIPP inserts the code you write in the <?!HTTPHEADER> block at the top of the generated CGI code, so it is executed before any other code you wrote in you CIPP program or Include, because the HTTP header must appear before any content.
So it is not possible to access any lexically scoped variables declared outside the <?!HTTPHEADER> block within the block. Usually you statically add or delete HTTP header fields. Your code may depend on CGI environment variables, or on a result of a SQL query, but that's it. If you want to access configuration variables, you must use the <?CONFIG> command inside your <?!HTTPHEADER> block.
This command is not implemented for Apache::CIPP and CGI::CIPP environments, but you can use it with new.spirit .
The actual HTTP header will be assigned to this variable, as a reference to a hash. This keys of this hash are the HTTP header tags.
If you set the MY switch the created variable will be declared using 'my'. Its scope reaches to the end of the <?!HTTPHEADER> block .
A HTTP header is created, which tells proxies how long they may cache the content of the produces HTML page.
<?!HTTPHEADER MY VAR="$http"> # delete a Pragma Tag (may be defined # globally in a new.spirit environment) delete $http->{Pragma}; # read a global config <?CONFIG NAME="x.global"> # get cache time my $cache_time = $global::cachable_time || 1200; # set Cache-Control header tag $http->{'Cache-Control'} = "max-age=$cache_time, public"; <?!/HTTPHEADER>
<?IF COND=condition > ... [ <?ELSIF COND=condition > ] ... [ <?ELSE> ] ... <?/IF>
The <?IF> command executes the enclosed block if the condition is true. <?ELSE> and <?ELSIF> can be used inside an <?IF> block in the common manner.
This takes a Perl condition. If this condition is true, the code inside the <?IF> block is executed.
Only Larry gets a greeting message here.
<?IF COND="$name eq 'Larry'"> Hi Larry! <?/IF>
<?IMG SRC=image_file [ additional_<IMG>_parameters ... ] >
A HTML <IMG> Tag will be generated, whoms SRC option points to the appropriate image URL.
This is the name of the image, expected as an URL in CGI::CIPP or Apache::CIPP environments and in dot-separated object notation in a new.spirit environment.
All additional parameters are taken without changes into the produced <IMG> tag.
In a new.spirit environment we produce a image link to another page, setting the border to 0.
<?A HREF="x.main.menu"> <?IMG SRC="x.images.logo" BORDER=0> <?/A>
In CGI::CIPP or Apache::CIPP environment we provide an URL instead of a dot-separated object name.
<?A HREF="/main/menu.cgi"> <?IMG SRC="/images/logo.jpg" BORDER=0> <?/A>
Interface
<?INCINTERFACE [ INPUT=list_of_variables ] [ OPTIONAL=list_of_variables [ NOQUOTE=list_of_variables ] [ OUTPUT=list_of_variables ] >
Use this command to declare an interface for an Include file. You can use this inside the Include file. In order to declare the interface of a CGI file this, use the <?INTERFACE> command.
You can declare mandatory and optional parameters. Parameters are always identified by name, not by position like in many programming languages. You can pass all types of Perl variables (scalars, arrays and hashes, also references). Also you can specify output parameters, which are passed back to the caller. Even these parameters are named, which requires some getting used to for most people. However it is very useful. :)
All input parameters declared this way are visible as the appropriate variables inside the Include file. They are always declared with my to prevent name clashes with other parts of the program.
All parameters of <?INCINTERFACE> expect a comma separated list of variables. All Perl variable types are supported: scalars ($), arrays (@)and hashes (%). Whitespaces are ignored. Read the note beneath the NOQUOTE section about passing non scalar values to an Include.
Note: You have to use lower case variable names, because the <?INCLUDE> command converts all variable names to lower case.
This parameters takes the list of variables the caller must provide in his <?INCLUDE> command (mandatory parameters).
The variables listed here are optional input parameters. They are always declared with my and visible inside the Include, but are set to undef, if the caller ommits them.
If you want your Include to pass values back to the caller, list the appropriate variables here. This variables are declared with my. Set them everywhere in your Include, they will be passed back automatically.
Note: the name of the variable receiving the output from the include must be different from the name of the output parameter. This is due to restrictions of the internal implementation.
By default all input parameters are defined by assigning the given value using double quotes. This means it is possible to pass either string constants or string expressions to the Include, which are interpreted at runtime, in the same manner. Often this is the behaviour you expect.
You have to list input (no output) parameters in the NOQUOTE parameter if you want them to be interpreted as a real Perl expression, and not in the string context (e.g. $i+1 will result in a string containing the value of $i concatenated with +1 in a string context, but in an incremented $i otherwise).
Note: Also you have to list all non-scalar and reference input parameters here, because array, hash and reference variables are also computed inside a string context by default, and this is usually not what you expect.
Note: Maybe this will change in future. Listing array and hash parameters in NOQUOTE will be optional, the default behaviour for those variables will change, so that they are not computed in string context by default.
The <?INCINTERFACE> command may occur several times inside one Include file. The position inside the source code does not matter. All declarations will be added to an interface accordingly.
If you ommit a <?INCINTERFACE> command inside your Include, its interface is empty. That means, you cannot pass any parameters to it. If you try so this will result in an error message at CIPP compile time.
This example declares an interface, expecting some scalars and an array. Note the usage of NOQUOTE for the array input parameter. The Include also returns a scalar and an array parameter.
<?INCINTERFACE INPUT="$firstname, $lastname" OPTIONAL="@id" OUTPUT="$scalar, @list" NOQUOTE="@id"> ... <?PERL> $scalar="returning a scalar"; @list= ("returning", "a", "list"); <?/PERL>
The caller may use this <?INCLUDE> command. Note that all input parameter names are converted to lower case.
<?INCLUDE NAME="/include/test.inc" FIRSTNAME="Larry" lastname="Wall" ID="(5,4,3)" MY $s=SCALAR @l=LIST>
<?INCLUDE NAME=include_name [ input_parameter_1=Wert1 ... ] [ MY ] [ variable_1=output_parameter_1 ... ] >
Use Includes to divide your project into reusable pieces of code. Includes are defined in separate files. They have a well defined interface due to the <?INCINTERFACE> command. CIPP performs parameter checking for you and complain about unknown or missing parameters.
The Include file code will be inserted at the same position you write <?INCLUDE>, inside of a Perl block. Due to this variables declared inside the Include are not valid outside.
Please refer to the <?INCINTERFACE> chapter to see how parameters are processed by an Include.
This is the name of the Include file, expected as an URL in CGI::CIPP or Apache::CIPP environments and in dot-separated object notation in a new.spirit environment.
You can pass parameters to the Include using the usual PARAMETER=VALUE notation. Note that parameter names are converted to lower case. For more details about Include input parameters refer to the appropriate section of the <?INCINTERFACE> chapter.
You can recieve parameters from the Include using the notation
{$@%}variable=output_parameter
Note that the name of the output parameters are automatically converted to lower case. Note also that the caller must not use the same name like the output parameter for the local variable which recieves the output parameter. That means for the above notation that variable must be different from output_parameter, ignoring the case.
For more details about Include output parameters refer to the appropriate section of the <?INCINTERFACE> chapter.
If you set the MY switch all created output parameter variables will be declared using 'my'. Their scope reaches to the end of the block which surrounds the <?INCLUDE> command.
Important note
The actual CIPP implementation does really include the Include code at the position where the <?INCLUDE> command occurs. This affects variable scoping. All variables visible at the callers source code where you write the <?INCLUDE> command are also visible inside your Include. So you can use these variables, although you never declared them inside your Include. Use of this feature is discouraged, in fact you should avoid the usage of variables you did not declared in your scope.
See example of <?INCINTERFACE>.
<?INPUT [ NAME=parameter_name ] [ VALUE=parameter_value ] [ SRC=image_object ] [ TYPE=input_type ] [ STICKY[=sticky_var] ] [ additional_<INPUT>_parameters ... ] >
This generates a HTML <INPUT> tag where the content of the VALUE option is escaped to prevent HTML syntax clashes. In case of TYPE="radio" or TYPE="checkbox" in conjunction with the STICKY Option, the state of the input widget will be preserved.
The name of the input widget.
This is the VALUE of the corresponding <INPUT> tag. Its content will be escaped.
Only the TYPEs ,radio" and ,checkbox" are specially handled when the STICKY option is also given.
If this option is set and the TYPE of the input widget is eiterh ,radio" or ,checkbox" CIPP will generate the CHECKED option automatically, if the value of the corresponding Perl variable (which is $parameter_name for TYPE="radio" and @parameter_name for TYPE="checkbox") equals to the VALUE of this widget. If you assign a value to the STICKY option, this will be taken as the Perl variable for checking the state of the widget. But the default behaviour of deriving the name from the NAME option will fit most cases.
All additional parameters are taken without changes into the generated <INPUT> tag.
If you use the STICKY feature in conjuncion with checkboxes, please note that the internal implementation may be ineffective, if you handle large checkbox groups. This is due the internal representation of the checkbox values as a list, so a grep is neccesary to check, wheter a checkbox is checked or not. If you feel uncomfortable about that, use a classic HTML <INPUT> tag, maybe with a loop around it, and check state of the checkboxes using a hash.
We generate two HTML input fields, a simple text and a password field, both initialized with some values. Also two checkboxes are generated, using the STICKY feature to initalize their state genericly.
<?VAR MY NAME=$username>larry<?/VAR <?VAR MY NAME=$password>this is my "password"<?/VAR> <?INPUT TYPE=TEXT SIZE=40 VALUE=$username> <?INPUT TYPE=PASSWORD SIZE=40 VALUE=$password> <?VAR MY NAME=$check>42<?/VAR> <?INPUT TYPE=CHECKBOX NAME="check" VALUE="42" STICKY> 42 <?INPUT TYPE=CHECKBOX NAME="check" VALUE="43" STICKY> 43
This will produce the following HTML code:
<INPUT TYPE=TEXT SIZE=40 VALUE="larry"> <INPUT TYPE=TEXT SIZE=40 VALUE="this ist my "password""> <INPUT TYPE=CHECKBOX NAME="check" VALUE="42" CHECKED> <INPUT TYPE=CHECKBOX NAME="check" VALUE="43">
<?INTERFACE [ INPUT=list_of_variables ] [ OPTIONAL=list_of_variables ] >
This command declares the interface of a CGI program. You can declare mandatory and optional parameters. Parameters are always identified by their name. You can recieve scalar and array parameters.
All input parameters declared this way are visible as the appropriate variables inside the CGI program. They are always declared with my to prevent name clashes with other parts of the program.
Using <?INTERFACE> is optional, if you are not in 'use strict' mode. If you ommit <?INTERFACE> all actual parameters are passed to your program, no parameter checking is done in this case. But it is strongly recommended to use <?INTERFACE> because CIPP checks the consistency of your CGI calls at runtime.
If you are in 'use strict' mode (which is the default), using <?INTERFACE> is mandatory, because one cannot create lexical variables at runtime. They must be declared in this manner, so CIPP can add the appropriate decalaration statements to the generated source code.
All parameters of <?INTERFACE> expect a comma separated list of variables. Scalars ($) and arrays (@) are supported. Whitespaces are ignored.
Note: It is recommended that you use lower case variable names for your CGI interfaces, because some CIPP commands for generating URLs (e.g. <?GETURL>) convert parameter names to lower case.
This parameters takes the list of variables the caller must pass to the CGI program.
The variables listed here are optional input parameters. They are always declared with my and visible inside the program, but are set to undef, if the caller ommits them.
The <?INTERFACE> command may occur several times inside a CGI program, the position inside the source code does not matter. All declarations will be added to an interface accordingly.
We specify an interface for two scalars and an array.
<?INTERFACE INPUT="$firstname, $lastname" OPTIONAL="@id">
A HTML form which adresses this CGI program may look like this (assuming we are in a CGI::CIPP or Apache::CIPP environment).
<?VAR MY NAME="@id" NOQUOTE>(1,2,3,4)<?/VAR> <?FORM ACTION="/user/save.cgi"> <?HIDDENFIELDS PARAMS="@id"> <P>firstname: <?INPUT TYPE=TEXT NAME=firstname> <P>lastname: <?INPUT TYPE=TEXT NAME=lastname> <?/FORM>
<?LOG MSG=error_message [ TYPE=type_of_message ] [ FILENAME=special_logfile ] [ THROW=exception ] >
The <?LOG> command adds a line to the project specific logfile, if no other filename is specified. In new.spirit environments the default filename of the logfile is prod/log/cipp.log. In CGI::CIPP and Apache::CIPP environments messages are written to /tmp/cipp.log (c:\tmp\cipp.log under Win32) by default.
Log file entries contain a timestamp, client IP adress, a message type and the message itself.
This is the message.
You can use the TYPE parameter to speficy a special type for this message. This is simply a string. You can use this feature to ease logfile analysis.
If you want to add this message to a special logfile you pass the full path of this file with FILENAME.
With this parameter you can provide a user defined exception to be thrown on failure. The default exception thrown by this statement is log.
An exception will be thrown, if the log file is not writable or the path is not reachable.
If the variable $error is set a simple entry will be added to the default logfile.
<?IF COND="$error != 0"> <?LOG MSG="internal error: $error"> <?/IF>
The error message "error in SQL statement" is added to the special logfile with the path /tmp/my.log. This entry is marked with the special type dberror. If this file is not writable an exception called fileio is thrown.
<?LOG MSG="error in SQL statement" TYPE="dberror" FILE="/tmp/my.log" THROW="fileio">
<?MODULE NAME=cipp_perl_module > ... <?/MODULE>
With this command you define a CIPP Perl Module. This works currently in a new.spirit environment only.
The generated Perl code will be installed in the project specific lib/ folder and can be imported with the <?REQUIRE> command. Don't <?USE> for CIPP Perl modules, because <?REQUIRE> does some database initialization.
This is the name of the module you want to use. Nested module names are delimited by ::.
It is not possible to use a variable or expression for NAME, you must always use a literal string here.
<?MODULE NAME="Test::Module"> <?SUB NAME="new"> <?PERL> my $class = shift; return bless { foo => 1, }, $class; <?/PERL> <?/SUB> <?SUB NAME="print_foo"> <?PERL> my $self = shift; print $self->{foo}, ,<p>\n"; <?/PERL> <?/SUB> <?/MODULE>
<?MY [ VAR=list_of_variables ] variable_1 ... variable_N >
This command declares private variables, using the Perl command my internally. Their scope reaches to the end of the block which surrounds the <?MY> command, for example only inside a <?IF> block.
All types of Perl variables (Scalars, Arrays and Hashes) can be declared this way.
If you want to initialize the variables with a value you must use the <?VAR> command or Perl commands directly. <?MY> only declares variables. Their initial value is undef.
This parameter takes a comma separated list of variable names, that should be declared. With this option it is possible to declare variables which are not in lower case.
You can place additionel variables everywhere inside the <?MY> command. This variables are always declared in lower case notation.
If you need a new variable for another CIPP command, you can most often use the MY switch of that command, which declares the variable for you. This saves you one additional CIPP command and makes your code more readable.
See <?BLOCK>
<?OPTION [ VALUE=parameter_value ] [ additional_<OPTION>_parameters ... ] > ... <?/OPTION>
This command generates a HTML <OPTION> tag, where the text inside the <OPTION> block is HTML escaped and the VALUE is quoted. The usage of the <?OPTION> command outside of a <?SELECT> block is forbidden. If the surrounding <?SELECT> command has its STICKY option set, the select state of the options are preserved (see <?SELECT> for more information about the STICKY feature).
This is the VALUE of the generated <OPTION> tag. Its content will be escaped.
All additional parameters are taken over without changes into the produced <OPTION> tag.
See the description of the <?SELECT> command for a complete example.
.
<?PERL [ COND=condition ] > ... <?/PERL>
With this command you open a block with pure Perl commands. You may place any valid Perl code inside this block.
You may use the Perl print statement to produce HTML code (or whatever output you want) for the client.
At the moment, there are only two CIPP commands which are actually supported inside a <?PERL> block: <?INCLUDE> and <?SQL>. Support of more commands will be added in the future.
If you set the COND parameter, the Perl block is only executed, if the given condition is true.
All occurences of the string 'nt' in the scalar variable $str will be replaced by 'no thanks'. The result will be printed to the client.
<?PERL> $text =~ s/nt/no thanks/g; print $text; <?/PERL>
If this list contains some elements a string based on the list is generated.
<?PERL COND="scalar(@list) != 0"> my ($string, $element); foreach $element ( @list ) { $string .= $element; } print $string; <?/PERL> # OK, its easier to use 'join', but it's # only an example... :-)
Preprocessor Command
<?!PROFILE { ON | OFF } [ DEEP ] >
This preprocessor command controls the generation of profiling code. This feature is currently experimental, the syntax of the <?!PROFILE> command may change in future.
If you switch profiling on, CIPP will generate profile code for the rest of the file, respectively until a <?!PROFILE OFF> command occurs. Switching profiling at runtime is not possible, because the <?!PROFILE> command takes effect on the preprocessor.
Currently two tasks are profiled: SQL statements and Include executions. If profiling is switched on, you'll get a line on STDERR for every executed SQL and Include command, which contains the corresponding execution time. You need the Perl module Time::HiRes installed on your system if you want to use profiling.
ON | OFF
Switch profiling either on or off.
If you set the DEEP option, the content all processed Includes will be profiled, too. Otherwise only the document itself, where the <?!PROFILE> command stands, will be profiled.
Note that the DEEP switch can produce lots of output.
The following SQL Statement and Include will be profiled.
<?!PROFILE ON> <?SQL SQL="select foo, bla from bar where baz=?" PARAMS="$baz" MY VAR="$foo, $bla"> $foo $bla<br> <?/SQL> <?INCLUDE NAME="/foo/bar.inc"> <?!/PROFILE OFF> # no profiling here <?INCLUDE NAME="/bar/foo.inc">
Something like this will appear on STDERR and thus in your webserver error log:
PROFILE 42421 START
PROFILE 42421 SQL select foo, baz 0.0178
PROFILE 42421 INCLUDE /foo/bar.inc 0.0020
PROFILE 42421 STOP
The 42421 is the PID of the serving process, so you can differ between outputs of several processes. You see the head of each SQL statement and the name of an Include, followed by the execution time in seconds.
You can use the PROFILE option of the <?SQL> command to replace the output of the SQL statement with a user defined label. See <?SQL> for details.
<?REQUIRE NAME="cipp_perl_module" >
This command imports a module which was created with new.spirit in conjunction with the <?MODULE> command. You can't import other Perl modules, because <?REQUIRE> executes CIPP specific initialization code to establish database connections, if they're needed by the module.
<?REQUIRE> uses internally the Perl command 'require' to import the module. So CIPP Perl Modules are unable to export symbols to the callers namespace. You have to fully quallify function names, or write OO style modules.
This is the name of the module you want to use. Nested module names are delimited by ::. This is the name of the module you provided with the <?MODULE> command.
You may also place a scalar variable here, which contains the name of the module. So it is possible to load modules dynamically at runtime.
# refer to the description of <?MODULE> to see # the implementation of the Test::Module module. <?REQUIRE NAME="Test::Module"> <?PERL> my $t = new Test::Module; $t->print_foo; <?/PERL>
<?ROLLBACK [ DB=database_name ] [ DBH=database_handle ] [ THROW=exception ] >
The <?ROLLBACK> command concludes the actual transaction and cancels all changes to the database.
Using <?ROLLBACK> in <?AUTOCOMMIT ON> mode is not possible.
If you are not in <?AUTOCOMMIT ON> mode a transaction begins with the first SQL statement and ends either with a <?COMMIT> or <?ROLLBACK> command.
With this parameter you can provide a user defined exception which should be thrown on failure. The default exception thrown by this statement is rollback.
We insert a row into a database table and rollback the change immediately. We throw a user defined exeption, if the rollback fails, maybe the database is not capable of transactions.
<?SQL SQL="insert into foo (num, str) values (42, 'bar');"> <?/SQL> <?ROLLBACK THROW="ROLLBACK_Exception">
<?SAVEFILE FILENAME=server_side_filename VAR=upload_formular_variable [ SYMBOLIC ] [ THROW=exception ] >
This command saves a file which was uploaded by a client in the webservers filesystem.
This is the fully qualified filename where the file will be stored.
This is the identifier you used in the HTML form for the filename on client side, the value of the <INPUT NAME> parameter) .
If this switch is set, VAR is the name of the variable which contains the <INPUT TYPE=FILE> identifier. Use this if you want to determine the name of the field at runtime.
With this parameter you can provide a user defined exception which should be thrown on failure. The default exception thrown by this statement is savefile.
The client side file upload will only function proper if you set the encoding type of the HTML form to ENCTYPE="multipart/form-data". Otherwise you will get a exception, that the file could not be fetched.
There is another quirk you should notice. The variable which corresponds to the <INPUT NAME> option in the file upload form is a GLOB reference (due to the internal implementation of the CGI module, which CIPP uses). That means, if you use that variable in string context you get the client side filename of the uploaded file. But also you can use the variable as a filehandle, to read data from the file (this is what <?SAVEFILE> does for you).
This GLOB thing is usually no problem, as long as you don't pass the variable as a binding parameter to a <?SQL> command (because you want to store the client side filename in the database). The DBI module (which CIPP uses for the database stuff) complains about passing GLOBS as binding parameters.
The solution is to create a new variable assigned from the value of the file upload variable enforced to be in string context using double quotes.
<?INTERFACE INPUT="$upfilename">
<?MY $client_filename>
<?PERL> $client_filename = "$upfilename" <?/PERL>
First we provide a HTML form with the file upload field.
<?FORM METHOD="POST" ACTION="/image/save.cgi" ENCTYPE="multipart/form-data"> Fileupload: <INPUT TYPE=FILE NAME="upfilename" SIZE=45><BR> <INPUT TYPE="reset"> <INPUT TYPE="submit" NAME="submit" VALUE="Upload"> </FORM>
The /image/save.cgi program has the following code to store the file in the filesystem.
<?SAVEFILE FILENAME="/tmp/upload.tmp" VAR="upfilename" THROW=my_upload>
The same procedure using the RUNTIME parameter.
<?VAR MY=$field_name>upfilename<?/VAR> <?SAVEFILE FILENAME="/tmp/upload.tmp" SYMBOLIC VAR="$field_name" THROW=upload>
<?SELECT [ NAME=parameter_name ] [ MULTIPLE ] [ STICKY ] [ additional_<SELECT>_parameters ... ] > ... <?/SELECT>
This command generates a selection widget providing preservation of the selection state (similar to the STICKY feature of the <?INPUT> command).
The name of the formular widget.
If this is set, a multi selection list will be generated, instead of a single selection popup widget.
If the STICKY option is set, the <?OPTION> commands inside the <?SELECT> block preserve their state in generating automatically a SELECTED option, if the corresponding entry was selected before. This is done in checking the value of the corresponding Perl variable (which is $parameter_name for a popup and @parameter_name for MULTIPLE selection list). If you assign a value to the STICKY option, this will be taken as the Perl variable for checking the state of the widget. But the default behaviour of deriving the name from the NAME option will fit most cases.
All additional parameters are taken over without changes into the produced <SELECT> tag.
If you use the STICKY feature in conjuncion with a MULTIPLE selection list widget, please note that the internal implementation may be ineffective, if you handle large lists. This is due the internal representation of the list values as an array, so a grep is neccesary to check, wheter a list entry is selected or not. If you feel uncomfortable about that, use classic HTML <SELECT> and <OPTION> tags, maybe with a loop around it, and check state of the checkboxes using a hash.
This is a complete CIPP program, which provides a mulitple selection list and preservers its state over subsequent executions of the program.
<?INCINTERFACE OPTIONAL="@list"> <?FORM ACTION="sticky.cgi"> <?SELECT NAME="list" MULTIPLE STICKY> <?OPTION VALUE="1">value 1<?/OPTION> <?OPTION VALUE="2">value 2<?/OPTION> <?OPTION VALUE="3">value 3<?/OPTION> <?/SELECT> <?INPUT TYPE="submit" VALUE="send"> <?/FORM>
<?SQL SQL=sql_statement [ VAR=list_of_variables_for_the_result ] [ PARAMS=input_parameter ] [ WINSTART=start_row ] [ WINSIZE=number_of_rows_to_fetch ] [ RESULT=sql_return_code ] [ DB=database_name ] [ DBH=database_handle ] [ THROW=exception ] > [ MY ] [ PROFILE=profile_label ] ... <?/SQL>
Use the <?SQL> command to execute arbitrary SQL statements in a specific database. You can fetch results from a SELECT query, or simply execute INSERT, UPDATE or other SQL statements.
When you execute a SELECT query (resp. set the VAR parameter, see below) the code inside the <?SQL> block will be repeated for every row returned from the database.
This takes the SQL statement to be executed. A trailing semicolon will be stripped off.
The statement may contain ? placeholders. They will be replaced by the expressions listed in the PARAMS parameter. See the PARAMS section for details about placeholders.
This is an example of a simple insert without placeholders.
<?SQL SQL="insert into foo values (42, 'bar')"> <?/SQL>
If you set the VAR parameter, CIPP asumes that you execute a SQL statement which returns a result set (normally a SELECT statement).
The VAR parameter takes a list of scalar variables. Each variable corresponds to the according column of the result set, so the position of the variables inside the list is relevant.
You can use this variable inside the <?SQL> block to access the actual processed row of the result set. Below the <?SQL> block the variable contains the values of the last row fetched, even when they are implicitely declared via a MY switch.
This is an example of creating a simple HTML table out of an SQL result set.
<TABLE> <?SQL SQL="select num, str from foo" MY VAR="$n, $s"> <TR> <TD>$n</TD> <TD>$s</TD> </TR> <?/SQL> </TABLE>
All placeholders inside your SQL statement will be replaced with the values given in PARAMS. It expects a comma separated list (white spaces are ignored) of Perl expressions, normally variables (scalar or array), literals or constants. The Perl value undef will be translated to the SQL value NULL. The content of the first expression substitutes the first placeholder in the SQL string, etc.
Values of parameters are quoted, if necessary, before substitution. This is the main advantage of PARAMS in this context. (You could place the perl variables into the SQL statement as such, but you would have to use <?DBQUOTE> on them first. Or else.).
Beware that you cannot use placeholders to contain (parts of) SQL code. The SQL must contain the syntactically complete statement - placeholders can only contain values. (The main reason for this is that the SQL statement is parsed by most databases before the placeholders are substituted. See the DBI manpage for details about placeholders.)
Here are some examples which demonstate the usage of placeholders.
<?VAR MY NAME=$n>42<?/VAR> <?VAR MY NAME=$s>Hello 'World'<?/VAR> <?SQL SQL="insert into foo values (?, ?, ?)" PARAMS="$n, $s, time()"> <?/SQL> <?VAR MY NAME=$where_num>42<?/VAR> <?SQL SQL="select num,str from foo where num = ?" PARAMS="$where_num"> MY VAR="$column_n, $column_s"> n=$column_n s='$column_s'<BR> <?/SQL> <?SQL SQL="update foo set str=? where n=?" PARAMS="$s, $where_num"> <?/SQL>
If you want to process only a part of the result set you can specfiy the first row you want to see with the WINSTART parameter. All rows before the given WINSTART row will be fetched but ignored. Execution of the <?SQL> block begins with the WINSTART row.
The row count begins with 1.
Here is an example. The first 5 rows will be skipped.
<?SQL SQL="select num, str from foo" MY VAR="$n, $s" WINSTART=6 n=$n s='$s'<BR> <?/SQL>
Set this parameter to specify the number of rows you want to process. You can combine this parameter with WINSTART to process a "window" of the result set.
This is an example of doing this (skipping 5 rows, processing 5 rows).
<?SQL SQL="select num, str from foo" MY VAR="$n, $s" WINSTART=6 WINSIZE=5 n=$n s='$s'<BR> <?/SQL>
Some SQL statements return a scalar result value, e.g. the number of rows processed (e.b. UPDATE and DELETE). The variable placed here will take the SQL result code, if there is one.
Example:
<?SQL SQL="delete from foo where num=42" MY RESULT=$deleted> <?/SQL> Successfully deleted $deleted rows!
With this parameter you can provide a user defined exception which should be thrown on failure. The default exception thrown by this statement is sql.
If you set the MY switch all created variables will be declared using 'my'. Their scope reaches to the end of the block which surrounds the <?SQL> command.
Here you can define a profile label for this SQL statement. If you use the <?!PROFILE> command this label is printed out instead of the head of the SQL statement. See the chapter of <?!PROFILE> about details.
Breaking the <?SQL> loop
If you want to break the SQL loop of a select statement, simply use this Perl Code:
<?PERL> last SQL; <?/PERL>
Please refer to the examples in the parameter sections above.
<?SUB NAME=subroutine_name > ... <?/SUB>
This defines the <?SUB> block as a Perl subroutine. You may use any CIPP commands inside the block.
Generally Includes are the best way to create reusable modules with CIPP. But sometimes you need real Perl subroutines, e.g. if you want to do some OO programming.
This is the name of the subroutine. Please refer to the perlsub manpage for details about Perl subroutines.
It is not possible to declare protoyped subroutines with <?SUB>.
This is a subroutine to create a text input field in a specific layout.
<?SUB NAME=print_input_field> # Catch the input parameters <?MY $label $name $value> <?PERL> ($label, $name, $value) = @_; <?/PERL> # print the text field <P> <B>$label:</B><BR> <?INPUT TYPE=TEXT SIZE=40 NAME=$name VALUE=$value> <?/SUB> You may call this subroutine from every Perl context this way. <?PERL> print_input_field ('Firstname', 'firstname', 'Larry'); print_input_field ('Lastname', 'surname', 'Wall'); <?/PERL>
<?TEXTAREA [ additional_<TEXTAREA>_parameters ... ]> ... <?/TEXTAREA>
This generates a HTML <TEXTAREA> tag, with a HTML quoted content to prevent from HTML syntax clashes.
There are no special parameters. All parameters you pass to <?TEXTAREA> are taken in without changes.
This creates a <TEXTAREA> initialized with the content of the variable $fulltext.
<?VAR MY NAME=$fulltext><B>HTML Text</B><?/VAR> <?TEXTAREA NAME=fulltext ROWS=10 COLS=80>$fulltext<?/TEXTAREA>
This leads to the following HTML code.
<TEXTAREA NAME=fulltext ROWS=10 COLS=80><B>HTML Text<B></TEXTAREA>
<?THROW THROW=exception [ MSG=message ] >
This command throws an user specified exception.
This is the exception identifier, a simple string. It is the criteria for the <?CATCH> command.
Optionally, you can pass a additional message for your exception, e.g. a error message you have got from a system call.
We try to open a file and throw a exception if this fails.
<?MY $error> <?PERL> open (INPUT, '/bar/foo') or $error=$!; <?/PERL> <?IF COND="$error"> <?THROW THROW="open_file" MSG="file /bar/foo, $error"> <?/IF>
If you want to throw a exception inside a Perl block you can do this with the Perl die function. The die argument must follow this convention:
identifier TAB message
This is the above example using this technique.
<?PERL>
open (INPUT, '/bar/foo') or die "open_file\tfile /bar/foo, $!";
<?/PERL>
<?TRY > ... <?/TRY >
Normally your program exits with a general exception message if an error/exception occurs or is thrown explicitely. The general exception handler which is responsible for this behaviour is part of any program code which CIPP generates.
You can provide your own exception handling using the <?TRY> and <?CATCH> commands.
All exceptions thrown inside a <?TRY> block are caught. You can use a subsequent <?CATCH> block to process the exceptions to set up your own exception handling.
If you ommit the <?CATCH> block, nothing will happen. You never see something of the exception, it will be fully ignored and the program works on.
We try to insert a row into a database table and write a log file entry with the error message, if the INSERT fails.
<?TRY> <?SQL SQL="insert into foo values (42, 'bar')"> <?/SQL> <?/TRY> <?CATCH THROW="insert" MY MSGVAR="$msg"> <?LOG MSG="unable to insert row, $msg" TYPE="database"> <?/CATCH>
<?URLENCODE VAR=unencoded_variable [ MY ] ENCVAR=encoded_variable >
Use this command to URL encode the content of a scalar variable. Parameters passed via URL always have to be encoded this way, otherwise you risk syntax clashes.
This is the variable you want to be encoded.
The encoded result will be stored in this variable.
If you set the MY switch the created variable will be declared using 'my'. Its scope reaches to the end of the block which surrounds the <?URLENCODE> command.
In this example we link an external CGI script and pass the content of the variable $query after using <?URLENCODE> on it.
<?URLENCODE VAR=$query MY ENCVAR=$enc_query> <A HREF="www.search.org?query=$enc_query"> find something </A>
Hint: in CGI::CIPP and Apache::CIPP environments you also can use the <?A> command for doing this.
<?USE NAME=perl_module >
With this command you can access the extensive Perl module library. You can access any Perl module which is installed on your system.
In a new.spirit environment you can place user defined modules in the prod/lib directory of your project, which is included in the library search path by default.
If you want to use a CIPP Module (generated with new.spirit and the <?MODULE> command), use <?REQUIRE> instead.
This is the name of the module you want to use. Nested module names are delimited by ::. This is exactly what the Perl use pragma expects (you guessed right, CIPP simply translates <?USE> to use :-).
The standard modules File::Path and Text::Wrap are imported to your program.
<?USE NAME="File::Path"> <?USE NAME="Text::Wrap">
<?VAR NAME=variable [ MY ] [ DEFAULT=value ] [ NOQUOTE ]> ... <?/VAR>
This command defines and optionally declares a Perl variable of any type (scalar, array and hash). The value of the variable is derived from the content of the <?VAR> block. You can assign constants, string expressions and any Perl expressions this way.
It is not possible to nest the <?VAR> command or to use any CIPP command inside the <?VAR> block. The content of the <?VAR> block will be evaluated and assigned to the variable.
This is the name of the variable. You must specify the full Perl variable here, including the $, @ or % sign to indicate the type of the variable.
These are some examples for creating variables using <?VAR>.
<?VAR NAME=$skalar>a string<?/VAR> <?VAR NAME=@liste>(1,2,3,4)<?/VAR> <?VAR NAME=%hash>( 1 => 'a', 2 => 'b' )<?/VAR>
If you set the DEFAULT parameter, this value will be assigned to the variable, if the variable is actually undef. In this case the content of the <?VAR> block will be ignored.
Setting the DEFAULT parameter is only supported for scalar variables.
You can use this feature to provide default values for input parameters this way.
<?VAR NAME=$event DEFAULT="show">$event<?/VAR>
Hint: you may think there must be a easier way of doing this. You are right. :-) We recommend you using this alternative code, the usage of DEFAULT is deprecated.
<?PERL> $event ||= 'show'; <?/PERL>
By default the variable is defined by assigning the given value using double quotes. This means it is possible to assign either string constants or string expressions to the variable without using extra quotes.
If you do not want the content of <?VAR> block to be evaluated in string context set the NOQUOTE switch. E.g., so it is possible to assign an integer expression to the variable.
This is an example of using NOQUOTE for an non string expression.
<?VAR MY NAME=$element_cnt NOQUOTE> scalar(@liste) <?/VAR>
If you set the MY switch the created variable will be declared using 'my'. Its scope reaches to the end of the block which surrounds the <?VAR> command.
<?WHILE COND=condition > ... <?/WHILE>
This realizes a loop, where the condition is checked first before entering the loop code.
As long as this Perl condition is true, the <?WHILE> block will be repeated.
This creates a HTML table out of an array using <?WHILE> to iterate over the two arrays @firstname and @lastname, assuming that they are of identical size.
<TABLE> <?VAR MY NAME=$i>0<?/VAR> <?WHILE COND="$i++ < scalar(@lastname)"> <TR> <TD>$lastname[$i]</TD> <TD>$firstname[$i]</TD> </TR> <?/WHILE> </TABLE>
Joern Reder <joern@dimedis.de>
Copyright (C) 1997-2001 by Joern Reder and dimedis GmbH, All Rights Reserved. This documentation is free; you can redistribute it and/or modify it under the same terms as Perl itself.
To install CIPP, copy and paste the appropriate command in to your terminal.
cpanm
cpanm CIPP
CPAN shell
perl -MCPAN -e shell install CIPP
For more information on module installation, please visit the detailed CPAN module installation guide.