CIPP/Manual.pm untested

filter: Statementstmt n/a Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub n/a Podpod n/a SCAR -
1 =head1 NAME
2  
3 CIPP - Reference Manual
4  
5 =head1 SYNOPSIS
6  
7 perldoc CIPP::Manual
8  
9 =head1 DESCRIPTION
10  
11 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.
12  
13 The manual describes CIPP's basic syntax rules, classifies its execution environments and describes all CIPP commands in alphabetical order. Each reference contains syntax notation, textual description and examples.
14  
15 Configuration hints for CGI::CIPP and Apache::CIPP can be found in the correspondent manpages.
16  
17 =head1 QUICK FIND A COMMAND DESCRIPTION
18  
19 If your perldoc is using 'less' or 'view' for paging, it is quite easy to jump to a particular command description.
20  
21 E.g. if you want to read the <?FOO> section, simply type this.
22  
23 /COMMAND...FOO
24  
25 =for pdf-manual
26  
27 =for html <!--NewPage-->
28  
29 =head1 Introduction
30  
31 The name CIPP is an acronym for CgI Perl Preprocessor. With CGI, a web server calls a program which generates a HTML page. The CGI allows passing of parameters, so the returned page might look different depending on the input to the program. This is what is commonly refered to as a "dynamic" page.
32  
33 CGI programms are just like normal ones, only there is a lot of code printing out HTML statements. The majority of the code is concerned about the layout of the generated page. This is a nuisance for two reasons: first, it is difficult to see the structure of the generated page by looking at the source code, second, a lot of the code just consists of ,print" statements - these are boring to write.
34  
35 CIPP takes another approach to CGI programming: you basically write an ordinary HTML page and insert into the page the code, which is responsible for the dynamic parts. This way, you can easily see the structure of the page and for generating HTML, you can simply write the HTML directly onto the page.
36  
37 =head2 CIPP generates Perl code
38  
39 CIPP is a preprocessor which generates pure Perl code out of your CIPP embedded HTML pages. Depending on your environment, this Perl code can either be installed as a CGI program on the webserver or is executed immediately through an appropriate handler. More details about the different environments and their properties are discussed later in this document.
40  
41 Here is a little example of a CIPP code snippet to demonstrate the simplicity of the preprocessing mechanism (this anticipates some basics of the CIPP programming language, a detailed description of the language follow beyond this chapter).
42  
43 <?IF COND="$event eq 'show'">
44  
45 The value of the variable 'foo' is:<BR>
46  
47 <B>$foo</B>
48  
49 <?/IF>
50  
51 You will get a HTML formatted content of the Perl variable $foo, assumed the variable $event contains the string 'show'.
52  
53 CIPP will generate Perl code similar to this.
54  
55 if ( $event eq 'show' ) {
56  
57 print "The value of the variable 'foo' is:<BR>\n";
58  
59 print "<B>$foo</B>\n";
60  
61 }
62  
63 This was really a simple example. The CIPP <?IF> is translated to a Perl 'if' command. The non CIPP text blocks (usually containing some HTML) are translated to a Perl 'print' command. There are many, more complex CIPP commands that save you a lot of work.
64  
65 So, here you can see the difference between CIPP and ordinary CGI programming. With CIPP, HTML is normal and code is embedded in a way which almost looks like HTML. CGI programs, on the other hand, contain a lot of print statements which makes them hard to read.
66  
67 Ok, message understood. Now you know what CIPP basically does for you. In the next chapter you will learn in what way and environment you can apply it.
68  
69 =head1 Environments where CIPP can be used
70  
71 As mentioned above there are three different environments where you can use CIPP programs:
72  
73 =over 8
74  
75 =item CIPP::CGI
76  
77 using CIPP via a central CGI wrapper program
78  
79 =item Apache::CGI
80  
81 using CIPP as a module inside the Apache webserver
82  
83 =item new.spirit
84  
85 managing projects of many CIPP files, generating standalone CGI programs for production web systems.
86  
87 =back
88  
89 A discussion of these three possible use cases follows, where the architecture of each environment is described briefly. There are extra chapters with configuration details about all of them.
90  
91 =head2 CGI::CIPP
92  
93 CGI::CIPP is a Perl module which enables you to use CIPP on every CGI capable webserver. It is based on a central wrapper script, which does all the preprocessing. It executes the generated Perl code directly afterwards. Additionally, it implements a filesystem based cache for the generated code. Preprocessing is done only when the corresponding CIPP source code changed on disk, otherwise this step is skipped.
94  
95 CGI::CIPP is prepared for usage inside a persistent Perl environment, e.g. in conjunction with the CGI::SpeedyCGI module, which is not part of the CIPP distribution, but freely available on CPAN. CGI::CIPP will cache the Perl compiled programs as subroutines. Subsequent calls to the same CIPP page are answered immediately, because neither CIPP preprocessing nor Perl compiling needs to be done in this case.
96  
97 Your CIPP source files are placed in a particular directory on a webserver. With some additional webserver configuration you can handle them as ,normal" HTML documents beneath other webserver documents like images or traditional static HTML documents. See the chapter about CGI::CIPP configuration for details.
98  
99 =head2 Apache::CIPP
100  
101 The architecture of the Apache::CIPP is very similar to the one of CGI::CIPP. The main difference is that the central CGI wrapper of CGI::CIPP is plugged into the Apache webserver as a Request Handler using mod_perl, which extends the Apache webserver with a Perl interpreter. Another difference ist that the configuration options for Apache::CIPP are placed into the webserver configuration file.
102  
103 All the caching is done exactly like CGI::CIPP does. See the chapter about Apache::CIPP configuration for details.
104  
105 =head2 new.spirit
106  
107 new.spirit uses CIPP in a different way. new.spirit is a web based development environment for creating software projects based on CIPP. In this environment the Perl code generated by CIPP for each page will be stored as a CGI executable, installed in a cgi-bin path of your webserver. This prevents you from installing your CIPP sources on the productive webserver system, only the preprocessed Perl code is installed there.
108  
109 Another difference using CIPP with new.spirit is the naming convention for adressing CIPP programs. CGI::CIPP and Apache::CIPP use URL's as adresses, new.spirit expects a special dot-separated notation. See the chapter ,Basic syntax rules" for details. For new.spirit CIPP configuration please refer to the new.spirit documentation.
110  
111 =head1 Basic Syntax Rules
112  
113 This chapter describes the CIPP syntax rules.
114  
115 =head2 CIPP command structure
116  
117 CIPP commands are embedded into HTML code, so the syntax is related to the HTML syntax. CIPP commands are written as tags, like HTML does. The main difference is that CIPP command tags begin with <? instead of <.
118  
119 Like in HTML, there are two kinds of commands: single commands and block commands. Block commands have a start and end tag. A block command influences the HTML respectively CIPP code surrounded by it.
120  
121 <?COMMAND [ par=value ... ] >
122  
123 or
124  
125 <?COMMAND [ par=value ... ]>
126  
127 HTML or CIPP code
128  
129 <?/COMMAND [ par=value ... ]>
130  
131 Whitespace between <? and COMMAND is ignored. The command names are not case sensitive. Parameters are written als par=value pairs. Assigning a value to a parameters is optional. A parameter without a value is called a switch.
132  
133 A parameter with value has the following syntax:
134  
135 parameter_name = parameter_value
136  
137 Whitespaces before and behind the = sign are ignored. If the value you want to assign contains whitespaces you must quote the value using double quotes.
138  
139 <?COMMAND par_1=value_without_whitespaces
140 par_2="value with whitespaces">
141  
142 If your value contains double quotes you must escape them using the backslash character.
143  
144 <?COMMAND par_2="value with \"double quotes\"">
145  
146 You may place Perl variables inside your value string, they are expanded in the usual way (there is one exception regarding return parameters, see section below).
147  
148 A switch without a value has this simple syntax:
149  
150 <?COMMAND SWITCH_NAME>
151  
152 =head2 Case sensitivity of CIPP parameters
153  
154 Due to historical reasons parameter names are also not case sensitive. Actually the CIPP preprocessor converts all parameter names to lower case at a very early stage. So the exact case notation of the parameters is lost for later processing. This is usually no problem and works as you expect. HTML behaves the same.
155  
156 Important Note: This approach has some side effects which you need to be aware of. For certain CIPP commands, you will be expected to specify Perl variables in the same syntactical manner of CIPP parameters. Not matter what you do, CIPP will always work on the lower case version of these names - without giving you any warning.
157  
158 The CIPP commands affected by this are: <?MY>, <?INCLUDE>, <?GETURL> and <?HIDDENFIELDS>. Please refer to the CIPP Reference chapter for details about these commands.
159  
160 Important Hint: Always use lower case variable names!
161  
162 =head2 CIPP return parameters
163  
164 There are many CIPP commands that return parameters back to you. Since commands are inside tags, there is no way to use them in an assignment. This means that you have to specify a variable (or more than one) which should hold the return values.
165  
166 These return variables are treated different from input variables.
167  
168 $foo = "whatever"; $bar = "x";
169  
170 ...
171  
172 <?COMMAND input=$foo output=$bar>
173  
174 is the same as
175  
176 <?COMMAND input="whatever" output=$bar>
177  
178 but no the same as
179  
180 <?COMMAND input=$foo output="x">
181  
182 So, the return value from the command will be placed inside $bar. You cannot see from the syntax alone which parameter is expanded and which isn't. However, for each CIPP command there is a desription of return parameters (if there are any).
183  
184 =head2 Context of CIPP commands
185  
186 There are three different contexts which CIPP knows. They are listed and explained below. CIPP switches from one context to another only by certain block commands. Normal CIPP commands do not change the context.
187  
188 B<1. HTML>
189  
190 This is the default context your CIPP program is in. That means, if your program does not contain any CIPP commands, you will produce a simple, static HTML page.
191  
192 Inside HTML context, Perl variables are expanded with their content, like Perl does it if you use variables in a double quoted string.
193  
194 In fact HTML contexts are translated to a Perl print command, which prints the whole HTML block using some kind of double quotes.
195  
196 You can force the HTML context using the <?HTML> command, if you are in a Perl context (see below).
197  
198 B<2. Variable Assignment>
199  
200 This is a special context which is only existent inside of a <?VAR> block. Inside this block no other CIPP commands are allowed. Perl variables will be expanded. Perl expressions are also possible - see the command description for details.
201  
202 With <?/VAR> you terminate the assignment block and CIPP goes back to HTML context.
203  
204 B<3. Perl>
205  
206 The block command <?PERL> switches to this context. The whole block will be interpreted as pure Perl code. No automatic HTML output is done here, you have to use print yourself to do that. You may also use only certain CIPP commands inside a Perl block, which are <?INCLUDE> and <?SQL>. This list of such commands will be expanded in future.
207  
208 With <?/PERL> you terminate the command block and CIPP goes back to HTML context.
209  
210 =head2 Add comments to your source
211  
212 CIPP uses a similar mechanism for writing comments like Perl does. Each line which begins with a # sign is interpreted as a comment and is fully ignored. Leading whitespace is ignored; you're free to indent your comments.
213  
214 It is not possible to preceed a CIPP comment by a CIPP command or HTML code. This would prevent you from using # in HTML code (and the least things that we want is to mess up HTML code - that is any more than it already is).
215  
216 You can use the CIPP command <?#> for nestable multiline comments.
217  
218 These lines show valid CIPP comments:
219  
220 <?PERL>
221 # this is indented comment
222 <?/PERL>
223  
224 # this comment is not indented
225  
226 <?#>
227 this is a multiline comment
228 <?/#>
229  
230 The following example is invalid. The comment will be printed, because it is interpreted in HTML context (see section above about HTML context).
231  
232 <?PERL> $path = '/' <?/PERL> # setting the path
233  
234 The corresponding web page will contain your comment:
235  
236 # setting the path
237  
238 =head2 Error messages
239  
240 There are two kinds of error messages a CIPP developer must handle, depending on the stage the error occured: in CIPP preprocessing or Perl execution. Both stages have their own error messages.
241  
242 B<CIPP errors>
243  
244 These errors occur while translating your CIPP code to Perl. They regard only the CIPP syntax, no Perl syntax checking is done at this stage. The corresponding error messages and line numbers point to the appropriate sections of your CIPP program. In CGI::CIPP and Apache::CIPP environments you'll get a HTML page with the CIPP error messages. The source code is printed out with the according sections highlighted.
245  
246 B<Perl errors>
247  
248 Perl errors occur while executing the Perl program, which has been generated by CIPP. There are two classes of Perl errors: compiler and runtime errors.
249  
250 Normally, a compiler error in a CGI program results in a ,Server Error", if you execute it on your webserver. The error messages may be written to the webserver error log file, depending on your webserver software and configuration.
251  
252 With CIPP generated programs you should never see a ,Server Error". All CIPP environments (CGI::CIPP, Apache::CIPP and new.spirit) initiate a Perl syntax check after translating the CIPP code and before executing the Perl code the first time. Perl compiler errors are caught this way and a HTML error page is generated for you. This saves you the hassle of digging into your webserver error log file for detailed information.
253  
254 Runtime errors are caught by the CIPP execption handler and can appear in different ways, depending on the location inside your program, where the error occurs. The exception handler prints out the error message, at the actual position, where the error occured. Maybe you produced already some HTML output, the error message will appear right beyond it. If you're using some complex table layout, it can happen, that your webbrowser is unable to render the page correctly and the error message is invisible due to this. You have to look into the produced HTML source code to see the error message in this case.
255  
256 All Perl error messages refer to the generated Perl code, not to your CIPP code. So line numbers are not comparable with the line numbers of your CIPP program.
257  
258 =head2 CIPP preprocessor commands
259  
260 There are several preprocessor commands. Those commands always begin with an exclamation mark:
261  
262 <?!COMMAND [ par=value ... ] >
263  
264 or
265  
266 <?!COMMAND [ par=value ... ]>
267  
268 ...
269  
270 <?/!COMMAND>
271  
272 The special about these commands is, that they take effect at the preprocessor time and not at runtime. They modify the internal state of the preprocessor and do not create Perl code directly, like most of the other CIPP commands do.
273  
274 Due to this the lexical environment of preprocessor commands does not matter the usual way. E.g. you may want to place a <?!AUTOPRINT> command inside of an <?IF> block to advice the preprocessor to generate print statements for HTML blocks or not (see the description of the <?!AUTOPRINT> command for details). But this will not work. See this example:
275  
276 <?IF COND="$user_wants_an_image_file">
277  
278 <?!AUTOPRINT OFF>
279  
280 <?PERL>
281  
282 print "Content-Type: image/gif\n\n";
283  
284 system ("cat /tmp/image.gif");
285  
286 <?/PERL>
287  
288 <?ELSE>
289  
290 Ok, you want no image, so you will
291  
292 get some nice <b>html</b> code.
293  
294 <?/IF>
295  
296 Looks ok but will not work!
297  
298 1. The <?AUTOPRINT> command causes CIPP not to generate any HTTP headers for you. So the <?ELSE> block will not work, because no HTTP headers are printed. You'll get a 500 Server Error.
299  
300 2. But even if you print headers there (with ,Content-type: text/html"): the HTML block will not be printed either. The <?!AUTOPRINT> command does not care about the logical context. The preprocessor reads the file from the top to the bottom and will switch off autoprinting when recognizing the <?!AUTOPRINT OFF>. It will not be switched on and the end of the <?IF> block. Autoprinting will be disabled for the rest of the file. So the HTML code inside the <?ELSE> block will never be printed out.
301  
302 So use preprocessor commands with care and keep this special implementation always in mind. Each preprocessor command description in this manual will give you hints about the corresponding special behaviour.
303  
304 =for html <!--NewPage-->
305  
306 =head1 LIST OF CIPP COMMANDS
307  
308 This is a alphabetical list of all CIPP commands with a
309 short description, divided into sections of command types.
310  
311 =head2 Variables and Scoping
312  
313 =over 8
314  
315 =item <?BLOCK>
316  
317 Creation of a block context to limit the scope of private variables
318  
319 =item <?MY>
320  
321 Declaring a private (block local) variable
322  
323 =item <?VAR>
324  
325 Definition of a variable
326  
327 =back
328  
329 =head2 Control Structures
330  
331 =over 8
332  
333 =item <?DO>
334  
335 Loop with condition check after first iteration
336  
337 =item <?ELSE>
338  
339 Alternative execution of a block
340  
341 =item <?ELSIF>
342  
343 Subsequent conditional execution
344  
345 =item <?EXIT>
346  
347 Abort the program
348  
349 =item <?FOREACH>
350  
351 Loop iterating with a variable over a list
352  
353 =item <?HTML>
354  
355 Switches to HTML context
356  
357 =item <?IF>
358  
359 Conditional execution of a block
360  
361 =item <?PERL>
362  
363 Insertion of pure Perl code
364  
365 =item <?SUB>
366  
367 Definition of a Perl subroutine
368  
369 =item <?WHILE>
370  
371 Loop with condition check before first iteration
372  
373 =back
374  
375 =head2 Import
376  
377 =over 8
378  
379 =item <?CONFIG>
380  
381 Import a config file
382  
383 =item <?INCLUDE>
384  
385 Insertion of a CIPP Include file in the actual CIPP code
386  
387 =item <?MODULE>
388  
389 Definition of a CIPP Perl Module
390  
391 =item <?REQUIRE>
392  
393 Import a CIPP Perl Module
394  
395 =item <?USE>
396  
397 Import a standard Perl module
398  
399 =back
400  
401 =head2 Exception Handling
402  
403 =over 8
404  
405 =item <?CATCH>
406  
407 Execution of a block if a particular exception was thrown in a preceding TRY block.
408  
409 =item <?LOG>
410  
411 Write a entry in a logfile.
412  
413 =item <?THROW>
414  
415 Explicite creation of an exception.
416  
417 =item <?TRY>
418  
419 Secured execution of a block. Any exceptions thrown in the encapsulated block are caught.
420  
421 =back
422  
423 =head2 SQL
424  
425 =over 8
426  
427 =item <?AUTOCOMMIT>
428  
429 Control of transaction behaviour
430  
431 =item <?COMMIT>
432  
433 Commit a transaction
434  
435 =item <?DBQUOTE>
436  
437 Quoting of a variable for usage in a SQL statement
438  
439 =item <?GETDBHANDLE>
440  
441 Returns the internal DBI database handle
442  
443 =item <?ROLLBACK>
444  
445 Rollback a transaction
446  
447 =item <?SQL>
448  
449 Execution of a SQL statement
450  
451 =back
452  
453 =head2 URL- and Form Handling
454  
455 =over 8
456  
457 =item <?GETURL>
458  
459 Creation of a CIPP object URL
460  
461 =item <?HIDDENFIELDS>
462  
463 Producing a number of hidden formular fields
464  
465 =item <?HTMLQUOTE>
466  
467 HTML encoding of a variable
468  
469 =item <?URLENCODE>
470  
471 URL encoding of a variable
472  
473 =back
474  
475 =head2 HTML Tag Replacements
476  
477 =over 8
478  
479 =item <?A>
480  
481 Replaces <A> tag
482  
483 =item <?FORM>
484  
485 Replaces <FORM> tag
486  
487 =item <?FRAME>
488  
489 Replaces <FRAME> tag
490  
491 =item <?IMG>
492  
493 Replaces <IMG> tag
494  
495 =item <?INPUT>
496  
497 Replaces <INPUT> tag, with sticky feature
498  
499 =item <?OPTION>
500  
501 Replaces <OPTION> tag, with sticky feature
502  
503 =item <?SELECT>
504  
505 Replaces <SELECT> Tag, with sticky feature
506  
507 =item <?TEXTAREA>
508  
509 Replaces <TEXTAREA> tag
510  
511 =back
512  
513 =head2 Interface
514  
515 =over 8
516  
517 =item <?GETPARAM>
518  
519 Recieving a non declared CGI input parameter
520  
521 =item <?GETPARAMLIST>
522  
523 Returns a list of all CGI input parameter names
524  
525 =item <?INCINTERFACE>
526  
527 Declaration of a interface for CIPP Include
528  
529 =item <?INTERFACE>
530  
531 Declaration of a CGI interface for a CIPP program
532  
533 =item <?FETCHUPLOAD> (was <?SAVEFILE>)
534  
535 Storing a client side upload file
536  
537 =back
538  
539 =head2 Apache
540  
541 =over 8
542  
543 =item <?APGETREQUEST>
544  
545 Returns the internal Apache request object
546  
547 =item <?APREDIRECT>
548  
549 Redirects to another URL internally
550  
551 =back
552  
553 =head2 Preprocessor
554  
555 =over 8
556  
557 =item <?!AUTOPRINT>
558  
559 Controls automatic output of HTML code
560  
561 =item <?!HTTPHEADER>
562  
563 Dynamic generation of a HTTP header
564  
565 =item <?!PROFILE>
566  
567 Initiate generation of profiling code
568  
569 =back
570  
571 =head2 Debugging
572  
573 =over 8
574  
575 =item <?DUMP>
576  
577 Dumps preformatted contents of data structures
578  
579 =back
580  
581 =head2 Miscellaneous
582  
583 =over 8
584  
585 =item <?>
586  
587 Print arbitrary Perl expressions
588  
589 =item <?_>
590  
591 Do l10n with Locale::TextDomain
592  
593 =back
594  
595 =head1 COMMAND <?>
596  
597 =head2 Type
598  
599 Miscellaneous
600  
601 =head2 Syntax
602  
603 <?>
604 # arbitrary Perl Expression to be printed
605 <?/>
606  
607 =head2 Description
608  
609 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).
610  
611 =head2 Examples
612  
613 These examples show some handy cases for this construct:
614  
615 # method call with printing the result
616  
617 <?>$object->get_attribute<?/>
618  
619 # print actual unix timestamp
620  
621 <?>time<?/>
622  
623 # calculate something and print the result
624  
625 <?>(time + 34800) * $$<?/>
626  
627 # This is possible, but unnecessary
628  
629 Value of a variable: <?>$foo<?/>
630  
631 # instead simply write this:
632  
633 Value of a variable: $foo
634  
635 =head1 COMMAND <?#>
636  
637 =head2 Type
638  
639 Multi Line Comment
640  
641 =head2 Syntax
642  
643 <?#>
644 ...
645 <?/#>
646  
647 =head2 Description
648  
649 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.
650  
651 =head2 Example
652  
653 This is a simple multi line comment.
654  
655 <?#>
656 This text will be ignored.
657 All CIPP tags too.
658 So this is no syntax error
659 <?IF foo bar>
660 <?/#>
661  
662 You may nest <?#> blocks:
663  
664 <?#>
665 bla foo
666 <?#>
667 foo bar
668 <?/#>
669 <?/#>
670  
671 =head1 COMMAND <?A>
672  
673 =head2 Type
674  
675 HTML Tag Replacement
676  
677 =head2 Syntax
678  
679 <?A HREF=hyperlinked_object_name[#anchor]
680 [ additional_<A>_parameters ... ] >
681 ...
682 <?/A>
683  
684 =head2 Description
685  
686 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.
687  
688 =head2 Parameter
689  
690 =over 8
691  
692 =item B<HREF>
693  
694 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.
695  
696 This parameter is expected as an URL in CGI::CIPP or Apache::CIPP environments and in dot separated object notation in a new.spirit environment.
697  
698 =item B<additional_A_parameters>
699  
700 All additional parameters are taken into the generated <A> tag.
701  
702 =back
703  
704 =head2 Example
705  
706 Textual link to 'MSG.Main', in a new.spirit environment.
707  
708 <?A HREF="MSG.Main">Back to the main menu<?/A>
709  
710 Image link to '/main/menu.cgi', in a CGI::CIPP or Apache::CIPP environment:
711  
712 <?A HREF="/main/menu.cgi">
713 <?IMG SRC="/images/logo.gif" BORDER=0>
714 <?/A>
715  
716 =head1 COMMAND <?APGETREQUEST>
717  
718 =head2 Type
719  
720 Apache
721  
722 =head2 Syntax
723  
724 <?APGETREQUEST [ MY ] VAR=request_variable >
725  
726 =head2 Description
727  
728 This command is only working if CIPP is used as an Apache module.
729  
730 It returns the internal Apache request object, so you can use Apache specific features.
731  
732 =head2 Parameter
733  
734 =over 8
735  
736 =item B<VAR>
737  
738 This is the variable where the request object will be stored.
739  
740 =item B<MY>
741  
742 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.
743  
744 =back
745  
746 =head2 Example
747  
748 The Apache request object will be stored in the implicitely declared variable $ar.
749  
750 <?APGETREQUEST MY VAR=$ar>
751  
752 =head1 COMMAND <?APREDIRECT>
753  
754 =head2 Type
755  
756 Apache
757  
758 =head2 Syntax
759  
760 <?APREDIRECT URL=new_URL >
761  
762 =head2 Description
763  
764 This command is only working if CIPP is used as an Apache module.
765  
766 It results in an internal Apache redirect. That means, the new url will be 'executed' without notifying the client about this.
767  
768 =head2 Parameter
769  
770 =over 8
771  
772 =item B<URL>
773  
774 This expression is used for the new URL.
775  
776 =item B<Note:>
777  
778 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.
779  
780 =back
781  
782 =head2 Example
783  
784 This commands redirect internally to the homepage of the corresponding website:
785  
786 <?AUTOPRINT OFF>
787 <?APREDIRECT URL="/">
788  
789 =head1 COMMAND <?AUTOCOMMIT>
790  
791 =head2 Type
792  
793 SQL
794  
795 =head2 Syntax
796  
797 <?AUTOCOMMIT ( ON | OFF )
798 [ DB=database_name ]
799 [ DBH=database_handle ]
800 [ THROW=exception ] >
801  
802 =head2 Description
803  
804 The <?AUTOCOMMIT> command corresponds directly to the underlying DBI AutoCommit mechanism.
805  
806 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.
807  
808 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.
809  
810 Enabling AutoCommit when AutoCommit is already enabled (or disabling when it's already disabled) is prohibited and will result in an runtime exception.
811  
812 =head2 Parameter
813  
814 =over 8
815  
816 =item B<ON | OFF>
817  
818 Switch AutoCommit modus either on or off.
819  
820 =item B<DB>
821  
822 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.
823  
824 If DB is ommited the project default database is used.
825  
826 If DB is a variable name (resp. something containing a $ sigil) the content of this variable will be evaluated to the corresponding database name at runtime.
827  
828 =item B<DBH>
829  
830 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.
831  
832 =item B<THROW>
833  
834 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.
835  
836 If the underlying database is not capable of transactions setting AutoCommit to ON will throw a runtime exception.
837  
838 =back
839  
840 =head2 Example
841  
842 Switch AutoCommit on for the database 'foo'.
843  
844 <?AUTOCOMMIT ON DB="foo">
845  
846 Switch AutoCommit off for the database 'bar' and throw the user defined exception 'myautocommit' on failure.
847  
848 <?AUTOCOMMIT OFF DB="bar" THROW="myautocommit">
849  
850 =head1 COMMAND <?!AUTOPRINT>
851  
852 =head2 Type
853  
854 Preprocessor
855  
856 =head2 Syntax
857  
858 <?!AUTOPRINT ( OFF | ON ) >
859  
860 =head2 Description
861  
862 With the <?!AUTOPRINT> command the preprocessor can be advised to suppress the generation of print statements for non CIPP blocks, resp. switching the generation of print statements on.
863  
864 In earlier versions of CIPP this command was named <?AUTOPRINT>. This notation is depreciated, but will work for compatability reasons.
865  
866 =head2 Parameter
867  
868 =over 8
869  
870 =item B<OFF>
871  
872 Automatic generation of print statements for non CIPP blocks will be deactivated.
873  
874 =item B<ON>
875  
876 Automatic generation of print statements for non CIPP blocks will be switched on again.
877  
878 =back
879  
880 =head2 Note
881  
882 This is a preprocessor command. Please read the chapter about preprocessor commands for details about this.
883  
884 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.
885  
886 The "CIPP Introduction" Chapter contains a paragraph about CIPP Preprocessor Commands. Please refer to this discussion for details of <?!AUTOPRINT>.
887  
888 =head2 Example
889  
890 This program sends a GIF image to the client, after generating the proper HTTP header. (For another example, see <?APREDIRECT>)
891  
892 <?AUTOPRINT OFF>
893  
894 These line will never be printed, it's fully ignored!!!
895  
896 <?PERL>
897 my $file = "/tmp/image.gif";
898 my $size = -s $file;
899  
900 print "Content-type: image/gif\n";
901 print "Content-length: $size\n\n";
902  
903 open (GIF, $file) or die "can't open $file";
904 binmode GIF; # help dump operating systems...
905 print while <GIF>;
906 close GIF;
907 <?/PERL>
908  
909 =head1 COMMAND <?BLOCK>
910  
911 =head2 Type
912  
913 Variables and Scoping
914  
915 =head2 Syntax
916  
917 <?BLOCK>
918 ...
919 <?/BLOCK>
920  
921 =head2 Description
922  
923 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.
924  
925 =head2 Example
926  
927 The variable $example does not exist beyond the block.
928  
929 <?BLOCK>
930 <?MY $example>
931 $example is known.
932 <?/BLOCK>
933  
934 $example does not exist here. This will result in a Perl
935 compiler error, because $example is not declared here.
936  
937 =head1 COMMAND <?CATCH>
938  
939 =head2 Type
940  
941 Exception Handling
942  
943 =head2 Syntax
944  
945 <?CATCH [ THROW=exception ]
946 [ MY ]
947 [ EXCVAR=variable_for_exception ]
948 [ MSGVAR=variable_for_error_message ] >
949 ...
950 <?/CATCH>
951  
952 =head2 Description
953  
954 Typically a <?CATCH> block follows after a <?TRY> block. You can process one particular or just any exception with the <?CATCH> block.
955  
956 <?CATCH> and <?TRY> has to be placed inside the same block.
957  
958 See the description of <?TRY> for details about the CIPP exception handling mechanism.
959  
960 =head2 Parameter
961  
962 =over 8
963  
964 =item B<THROW>
965  
966 If this parameter is omitted, all exceptions will be processed here. Otherwise the <?CATCH> block is executed only if the appropriate exception was thrown.
967  
968 =item B<EXCVAR>
969  
970 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.
971  
972 =item B<MSGVAR>
973  
974 Name the variable, where the error message should be stored in.
975  
976 =item B<MY>
977  
978 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.
979  
980 =back
981  
982 =head2 Example
983  
984 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.
985  
986 <?TRY>
987 <?SQL SQL="insert into persons
988 (firstname, lastname)
989 values ('John', 'Doe')"><?/SQL>
990 <?COMMIT>
991 <?/TRY>
992  
993 <?CATCH THROW=sql MY MSGVAR=$message>
994 <?LOG MSG="Can't insert data: $message"
995 TYPE="database">
996 <?/CATCH>
997  
998 <?CATCH THROW=commit MSGVAR=$message>
999 <?LOG MSG="COMMIT rejected: $message"
1000 TYPE="database">
1001 <?/CATCH>
1002  
1003 =head1 COMMAND <?COMMIT>
1004  
1005 =head2 Type
1006  
1007 SQL
1008  
1009 =head2 Syntax
1010  
1011 <?COMMIT [ DB=database_name ]
1012 [ DBH=database_handle ]
1013 [ THROW=exception ] >
1014  
1015 =head2 Description
1016  
1017 The <?COMMIT> command concludes the actual transaction and makes all changes to the database permanent.
1018  
1019 Using <?COMMIT> in <?AUTOCOMMIT ON> mode is not possible and will result in a runtime exception.
1020  
1021 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.
1022  
1023 =head2 Parameter
1024  
1025 =over 8
1026  
1027 =item B<DB>
1028  
1029 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.
1030  
1031 If DB is ommited the project default database is used.
1032  
1033 If DB is a variable name (resp. something containing a $ sigil) the content of this variable will be evaluated to the corresponding database name at runtime.
1034  
1035 =item B<DBH>
1036  
1037 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.
1038  
1039 =item B<THROW>
1040  
1041 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.
1042  
1043 If the underlying database is not capable of transactions (e.g. MySQL) execution of this command will throw an exception.
1044  
1045 =back
1046  
1047 =head2 Example
1048  
1049 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.
1050  
1051 <?AUTOCOMMIT OFF>
1052 <?SQL SQL="insert into foo (num, str)
1053 values (42, 'bar');">
1054 <?/SQL>
1055 <?COMMIT THROW="COMMIT_Exception">
1056  
1057 =head1 COMMAND <?CONFIG>
1058  
1059 =head2 Type
1060  
1061 Import
1062  
1063 =head2 Syntax
1064  
1065 <?CONFIG NAME=config_file
1066 [ RUNTIME ] [ NOCACHE ]
1067 [ THROW=exception ] >
1068  
1069 =head2 Description
1070  
1071 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.
1072  
1073 <?CONFIG> ensures a proper load of the configuration file even in persistent Perl environments.
1074  
1075 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.
1076  
1077 =head2 Parameter
1078  
1079 =over 8
1080  
1081 =item B<NAME>
1082  
1083 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.
1084  
1085 =item B<RUNTIME>
1086  
1087 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.
1088  
1089 In CGI::CIPP and Apache::CIPP environments the NAME parameter will always be resolved at runtime.
1090  
1091 =item B<NOCACHE>
1092  
1093 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.
1094  
1095 =item B<THROW>
1096  
1097 With this parameter you can provide a user defined exception to be thrown on failure. The default exception thrown by this statement is config.
1098  
1099 An exception will be thrown, if the config file does not exist or is not readable.
1100  
1101 =back
1102  
1103 =head2 Example
1104  
1105 Load of the configuration file "/lib/general.conf", with disabled cache, used in CGI::CIPP or Apache::CIPP environment:
1106  
1107 <?CONFIG NAME="/lib/general.conf" NOCACHE>
1108  
1109 Load of the configuration file object x.custom.general in a new.spirit environment:
1110  
1111 <?CONFIG NAME="x.custom.general">
1112  
1113 Load of a config file with a name determined at runtime, in a new.spirit environment, throwing "myconfig" on failure:
1114  
1115 <?CONFIG NAME="$config_file" RUNTIME
1116 THROW="myconfig">
1117  
1118 =head1 COMMAND <?DBQUOTE>
1119  
1120 =head2 Type
1121  
1122 SQL
1123  
1124 =head2 Syntax
1125  
1126 <?DBQUOTE VAR=variable
1127 [ MY ]
1128 [ DBVAR=quoted_result_variable ]
1129 [ DB=database_name ]
1130 [ DBH=database_handle ] >
1131  
1132 =head2 Description
1133  
1134 <?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.
1135  
1136 <?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.
1137  
1138 =head2 Parameter
1139  
1140 =over 8
1141  
1142 =item B<VAR>
1143  
1144 This is the scalar variable containing the parameter you want to be quoted.
1145  
1146 =item B<DBVAR>
1147  
1148 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.
1149  
1150 If you ommit DBVAR, the name of the target variable is computed by placing the prefix 'db_' in front of the VAR name.
1151  
1152 =item B<MY>
1153  
1154 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.
1155  
1156 =item B<DB>
1157  
1158 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.
1159  
1160 If DB is ommited the project default database is used.
1161  
1162 If DB is a variable name (resp. something containing a $ sigil) the content of this variable will be evaluated to the corresponding database name at runtime.
1163  
1164 =item B<DBH>
1165  
1166 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.
1167  
1168 =back
1169  
1170 =head2 Example
1171  
1172 This quotes the variable $name, the result will be stored in the just declared variable $db_name.
1173  
1174 <?DBQUOTE MY VAR="$name">
1175  
1176 This quotes $name, but stores the result in the variable $quoted_name.
1177  
1178 <?DBQUOTE VAR="$name" MY DBVAR="$quoted_name">
1179  
1180 The quoted variable can be used in a SQL statement this way:
1181  
1182 <?SQL SQL="insert into persons (name)
1183 values ( $quoted_name )">
1184  
1185 =head1 COMMAND <?DO>
1186  
1187 =head2 Type
1188  
1189 Control Structure
1190  
1191 =head2 Syntax
1192  
1193 <?DO>
1194 ...
1195 <?/DO COND=condition >
1196  
1197 =head2 Description
1198  
1199 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.
1200  
1201 =head2 Parameter
1202  
1203 =over 8
1204  
1205 =item B<COND>
1206  
1207 This takes a Perl condition. As long as this condition is true the <?DO> block will be repeated.
1208  
1209 =back
1210  
1211 =head2 Example
1212  
1213 Print "Hello World" $n times. (note: for n=0 and n=1 you get the same result)
1214  
1215 <?DO>
1216 Hello World<BR>
1217 <?/DO COND="--$n > 0">
1218  
1219 =head1 COMMAND <?DUMP>
1220  
1221 =head2 Type
1222  
1223 Debugging
1224  
1225 =head2 Syntax
1226  
1227 <?DUMP [LOG] [STDERR] $var_1 ... $var_n>
1228  
1229 =head2 Description
1230  
1231 The <?DUMP> command dumps the contents of the given variables using Data::Dumper, inside of a HTML <pre></pre> block. By default the data is written to STDOUT (into the HTML page), but you can alternatively write the data to CIPP's logfile and/or STDERR.
1232  
1233 =head2 Parameter
1234  
1235 =over 8
1236  
1237 =item B<LOG>
1238  
1239 Dumps the data to CIPP's logfile, instead of STDOUT.
1240  
1241 =item B<STDERR>
1242  
1243 Dumps the data to STDERR (and thus the webserver's error log), instead of STDOUT.
1244  
1245 =item B<$var_1 .. $var_n>
1246  
1247 Variable, which should be dumped.
1248  
1249 =back
1250  
1251 =head2 Example
1252  
1253 <?DUMP $hash_ref $list_ref>
1254  
1255 =head1 COMMAND <?ELSE>
1256  
1257 =head2 Type
1258  
1259 Control Structure
1260  
1261 =head2 Syntax
1262  
1263 <?ELSE>
1264  
1265 =head2 Description
1266  
1267 <?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.
1268  
1269 <?MY> variables are only visible inside this block.
1270  
1271 (Or short: it works as you would expect.)
1272  
1273 =head2 Example
1274  
1275 Only Larry gets a personal greeting message:
1276  
1277 <?IF COND="$name eq 'Larry'">
1278 Hi Larry, you're welcome!
1279 <?ELSE>
1280 Hi Stranger!
1281 <?/IF>
1282  
1283 =head1 COMMAND <?ELSIF>
1284  
1285 =head2 Type
1286  
1287 Control Structure
1288  
1289 =head2 Syntax
1290  
1291 <?ELSIF COND=condition >
1292  
1293 =head2 Description
1294  
1295 <?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.
1296  
1297 <?MY> variables are only visible inside this block.
1298  
1299 (Or short: it works as you would expect.)
1300  
1301 =head2 Parameter
1302  
1303 =over 8
1304  
1305 =item B<COND>
1306  
1307 Takes the Perl condition.
1308  
1309 =back
1310  
1311 =head2 Example
1312  
1313 Larry and Linus get personal greeting messages:
1314  
1315 <?IF COND="$name eq 'Larry'">
1316 Hi Larry, you're welcome!
1317 <?ELSIF COND="$name eq 'Linus'">
1318 Hi Linus, you're velkomma!
1319 <?ELSE>
1320 Hi Stranger!
1321 <?/IF>
1322  
1323 =head1 COMMAND <?EXIT>
1324  
1325 =head2 Type
1326  
1327 Control Structure
1328  
1329 =head2 Syntax
1330  
1331 <?EXIT>
1332  
1333 =head2 Description
1334  
1335 <?EXIT> aborts the current program. You can use it at CGI program level and in an Include at any time, but not inside a <?TRY> resp. eval {} block! <?EXIT> issues a special exception, which is catched by the default exception handler and does the necessary request cleanup (e.g. closing pending database connections).
1336  
1337 =head2 Note
1338  
1339 Due to the internal implementation as an exception, you can't use <?EXIT> inside a <?TRY> or eval{} block, unless you catch the special exception "_cipp_exit_command" and throw it upwards yourself.
1340  
1341 =head2 Example
1342  
1343 Exit the program if the user doesn't know the preconfigured secret:
1344  
1345 <?INTERFACE INPUT="$secret">
1346  
1347 <?IF COND="$secret ne $conf::the_ultimate_secret">
1348 <p>
1349 You don't know the secret. Go away!
1350 </p>
1351 <?EXIT>
1352 <?/IF>
1353  
1354 You're welcome, secret keeper!
1355  
1356 =head1 COMMAND <?FETCHUPLOAD>
1357  
1358 =head2 Type
1359  
1360 Interface
1361  
1362 =head2 Syntax
1363  
1364 <?FETCHUPLOAD FILENAME=server_side_filename
1365 VAR=upload_formular_variable
1366 [ THROW=exception ] >
1367  
1368 =head2 Description
1369  
1370 This command fetches a file which was uploaded by a client and saves it in the webservers filesystem. It replaces the deprecated CIPP 2.x command <?SAVEFILE> and has a cleaner interface.
1371  
1372 =head2 Parameter
1373  
1374 =over 8
1375  
1376 =item B<FILENAME>
1377  
1378 This is the fully qualified filename where the file should be stored.
1379  
1380 =item B<VAR>
1381  
1382 This is the variable which holds the value of the correspondent HTML file upload field (mostly declared with <?INTERFACE> or fetched with <?GETPARAM>).
1383  
1384 =item B<THROW>
1385  
1386 With this parameter you can provide a user defined exception which should be thrown on failure. The default exception thrown by this statement is "fetchupload".
1387  
1388 =back
1389  
1390 =head2 Note
1391  
1392 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.
1393  
1394 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 <?FETCHUPLAOD> actually does for you).
1395  
1396 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.
1397  
1398 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.
1399  
1400 <?INTERFACE INPUT="$upfilename">
1401 <?MY $client_filename>
1402 <?PERL> $client_filename = "$upfilename" <?/PERL>
1403  
1404 =head2 Example
1405  
1406 First we provide a HTML form with the file upload field.
1407  
1408 <?FORM METHOD="POST" ACTION="/image/save.cgi"
1409 ENCTYPE="multipart/form-data">
1410  
1411 Fileupload:
1412 <INPUT TYPE=FILE NAME="upfilename" SIZE=45>
1413 <P>
1414 <INPUT TYPE="reset">
1415 <INPUT TYPE="submit" NAME="submit" VALUE="Upload">
1416  
1417 <?/FORM>
1418  
1419 The /image/save.cgi program has the following code to store the file in the filesystem.
1420  
1421 <?FETCHUPLOAD FILENAME="/tmp/upload.tmp"
1422 VAR="upfilename"
1423 THROW=my_upload>
1424  
1425 =head1 COMMAND <?FOREACH>
1426  
1427 =head2 Type
1428  
1429 Control Structure
1430  
1431 =head2 Syntax
1432  
1433 <?FOREACH [ MY ] VAR=running_variable
1434 LIST=perl_list >
1435 ...
1436 <?/FOREACH>
1437
1438  
1439 =head2 Description
1440  
1441 <?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.
1442  
1443 =head2 Parameter
1444  
1445 =over 8
1446  
1447 =item B<VAR>
1448  
1449 This is the scalar running variable.
1450  
1451 =item B<LIST>
1452  
1453 You can write any Perl list here, e.g. using the bracket notation or pass a array variable using the @ notation.
1454  
1455 =item B<MY>
1456  
1457 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.
1458  
1459 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.
1460  
1461 =back
1462  
1463 =head2 Example
1464  
1465 Counting up to 'three':
1466  
1467 <?FOREACH MY VAR="$cnt"
1468 LIST="('one', 'two', 'three')">
1469 $cnt
1470 <?/FOREACH>
1471  
1472 =head1 COMMAND <?FORM>
1473  
1474 =head2 Type
1475  
1476 HTML Tag Replacement
1477  
1478 =head2 Syntax
1479  
1480 <?FORM ACTION="target_action_object[#anchor]"
1481 [ additional_<FORM>_parameters ... ] >
1482 ...
1483 <?/FORM>
1484  
1485 =head2 Description
1486  
1487 <?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.
1488  
1489 =head2 Parameter
1490  
1491 =over 8
1492  
1493 =item B<ACTION>
1494  
1495 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. You may optionally add an anchor (which should be defined using <A NAME> in the referred page) using the # character as a delimiter.
1496  
1497 =item B<additional_FORM_parameters>
1498  
1499 All additional parameters are taken over without changes into the produced <FORM> tag. If you ommit the METHOD parameter it will default to POST.
1500  
1501 =back
1502  
1503 =head2 Example
1504  
1505 Creating a named form with a submit button, pointing to the CGI object "x.login.start", in a new.spirit environment:
1506  
1507 <?FORM ACTION="x.login.start" NAME="myform">
1508 <?INPUT TYPE=SUBMIT VALUE=" Start ">
1509 <?/FORM>
1510  
1511 Creating a similar form, but the action is written as an URL because we are in CGI::CIPP or Apache::CIPP environment:
1512  
1513 <?FORM ACTION="/login/start.cgi" NAME="myform">
1514 <?INPUT TYPE=SUBMIT VALUE=" Start ">
1515 <?/FORM>
1516  
1517 =head1 COMMAND <?FRAME>
1518  
1519 =head2 Type
1520  
1521 HTML Tag Replacement
1522  
1523 =head2 Syntax
1524  
1525 <?FRAME SRC=hyperlinked_object_name[#anchor]
1526 [ additional_<FRAME>_parameters ... ] >
1527  
1528 =head2 Description
1529  
1530 This command replaces the <FRAME> HTML tag. You can use this in a new.spirit environment to embed CIPP or HTML object as a frame.
1531  
1532 =head2 Parameter
1533  
1534 =over 8
1535  
1536 =item B<SRC>
1537  
1538 This parameter takes the name of the embedded object. You may optionally add an anchor (which should be defined using <A NAME> in the referred page) using the # character as a delimiter.
1539  
1540 This parameter is expected as an URL in CGI::CIPP or Apache::CIPP environments and in dot separated object notation in a new.spirit environment.
1541  
1542 =item B<additional_FRAME_parameters>
1543  
1544 All additional parameters are taken into the generated <FRAME> tag.
1545  
1546 =back
1547  
1548 =head2 Example
1549  
1550 A frameset with two frames in a new.spirit environment:
1551  
1552 <FRAMESET ROWS="50,*">
1553 <?FRAME SRC="x.frame.top" FRAMEBORDER="no">
1554 <?FRAME SRC="x.frame.bottom" FRAMEBORDER="no">
1555 </FRAMESET>
1556  
1557 =head1 COMMAND <?GETDBHANDLE>
1558  
1559 =head2 Type
1560  
1561 SQL
1562  
1563 =head2 Syntax
1564  
1565 <?GETDBHANDLE [ DB=database_name ] [ MY ]
1566 VAR=handle_variable >
1567  
1568 =head2 Description
1569  
1570 This command returns a reference to the internal Perl database handle, which is the object references returned by DBI->connect.
1571  
1572 With this handle you are able to perform DBI specific functions which are currently not directly available through CIPP.
1573  
1574 =head2 Parameter
1575  
1576 =over 8
1577  
1578 =item B<VAR>
1579  
1580 This is the variable where the database handle will be stored.
1581  
1582 =item B<MY>
1583  
1584 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.
1585  
1586 =item B<DB>
1587  
1588 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.
1589  
1590 If DB is ommited the project default database is used.
1591  
1592 If DB is a variable name (resp. something containing a $ sigil) the content of this variable will be evaluated to the corresponding database name at runtime.
1593  
1594 =back
1595  
1596 =head2 Example
1597  
1598 We get the database handle for the database object 'x.Oracle' in a new.spirit environment and perform a select query using this handle.
1599  
1600 Ok, you simply can do this with the <?SQL> command, but now you can see how much work is done for you through CIPP :)
1601  
1602 <?GETDBHANDLE DB="MSG.Oracle" MY VAR="$dbh">
1603  
1604 <?PERL>
1605 my $sth = $dbh->prepare ( qq{
1606 select n,s from TEST_table
1607 where n between 10 and 20
1608 });
1609 die "my_sql\t$DBI::errstr" if $DBI::errstr;
1610  
1611 $sth->execute;
1612 die "my_sql\t$DBI::errstr" if $DBI::errstr;
1613  
1614 my ($n, $s);
1615 while ( ($n, $s) = $sth->fetchrow ) {
1616 print "n=$n s=$s<BR>\n";
1617 }
1618 $sth->finish;
1619 die "my_sql\t$DBI::errstr" if $DBI::errstr;
1620  
1621 <?/PERL>
1622  
1623 =head1 COMMAND <?GETPARAM>
1624  
1625 =head2 Type
1626  
1627 Interfaces
1628  
1629 =head2 Syntax
1630  
1631 <?GETPARAM NAME=parameter_name
1632 [ MY ] [ VAR=content_variable ] >
1633  
1634 =head2 Description
1635  
1636 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.
1637  
1638 Refer to <?INTERFACE> to see how easy it is to handle standard CGI input parameters.
1639  
1640 =head2 Parameter
1641  
1642 =over 8
1643  
1644 =item B<NAME>
1645  
1646 Identifier of the CGI input parameter
1647  
1648 =item B<VAR>
1649  
1650 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).
1651  
1652 =item B<MY>
1653  
1654 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.
1655  
1656 =back
1657  
1658 =head2 Example
1659  
1660 We recieve two parameters, one staticly named parameter and one scalar parameter, which has a dynamic generated identifier.
1661  
1662 <?GETPARAM NAME="listparam" MY VAR="@list">
1663 <?GETPARAM NAME="scalar$name" MY VAR="$scalar">
1664  
1665 =head1 COMMAND <?GETPARAMLIST>
1666  
1667 =head2 Type
1668  
1669 Interfaces
1670  
1671 =head2 Syntax
1672  
1673 <?GETPARAMLIST [ MY ] VAR=variable >
1674  
1675 =head2 Description
1676  
1677 This command returns a list containing the identifiers of all CGI input parameters.
1678  
1679 =head2 Parameter
1680  
1681 =over 8
1682  
1683 =item B<VAR>
1684  
1685 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.
1686  
1687 =item B<MY>
1688  
1689 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.
1690  
1691 =back
1692  
1693 =head2 Example
1694  
1695 The list of all CGI input parameter identifiers will be stored into the array variable @input_param_names.
1696  
1697 <?GETPARAMLIST MY VAR="@input_param_names">
1698  
1699 =head1 COMMAND <?GETURL>
1700  
1701 =head2 Type
1702  
1703 URL and Form Handling
1704  
1705 =head2 Syntax
1706  
1707 <?GETURL NAME=object_file
1708 [ MY ] VAR=target_variable
1709 [ RUNTIME ] [ THROW=exception ] >
1710 [ PARAMS=parameters_variables ]
1711 [ PATHINFO=pathinfo ]
1712 [ PAR_1=value_1 ... PAR_n=value_n ] >
1713  
1714 =head2 Description
1715  
1716 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.
1717  
1718 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.
1719  
1720 =head2 Parameter
1721  
1722 =over 8
1723  
1724 =item B<NAME>
1725  
1726 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.
1727  
1728 =item B<VAR>
1729  
1730 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).
1731  
1732 =item B<URLVAR>
1733  
1734 Depreciated. See description of VAR.
1735  
1736 =item B<MY>
1737  
1738 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.
1739  
1740 =item B<RUNTIME>
1741  
1742 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.
1743  
1744 In CGI::CIPP and Apache::CIPP environments the NAME parameter will always be resolved at runtime.
1745  
1746 =item B<THROW>
1747  
1748 With this parameter you can define the exception to be thrown on failure. The default exception thrown by this statement is geturl.
1749  
1750 An exception will be thrown, if the adressed file does not exist.
1751  
1752 =item B<PARAMS>
1753  
1754 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).
1755  
1756 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.
1757  
1758 =item B<PATHINFO>
1759  
1760 You can specify the PATH_INFO part of the url using this option. The content of PATHINFO will be added to the filename part of the URL, delimited with a slash. All query parameters are added after PATHINFO, delimited with a question mark. In case of dynamically generated file downloads some browsers use the PATHINFO as a default for the filename. Also you can use this for beautifying URL's, resp. hiding URL parameters.
1761  
1762 =item B<PAR_1..PAR_n>
1763  
1764 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>.
1765  
1766 =back
1767  
1768 =head2 Note
1769  
1770 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.
1771  
1772 =head2 Example
1773  
1774 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):
1775  
1776 <?GETURL NAME="x.Images.Logo" MY VAR=$url>
1777 <IMG SRC="$url">
1778  
1779 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!)
1780  
1781 <?VAR MY NAME=$Username>hans<?/VAR>
1782 <?VAR MY NAME=@id>(1,42,5)<?/VAR>
1783 <?GETURL NAME="/secure/messager.cgi" MY VAR=$url
1784 PARAMS="$Username, @id" EVENT=delete>
1785 <A HREF="$url">delete messagse</A>
1786  
1787 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.
1788  
1789 <?INTERFACE INPUT="$event, $Username, @id">
1790 <?IF COND="$event eq 'delete'">
1791 <?MY $id_text>
1792 <?PERL>$id_text = join (", " @id)<?PERL>
1793 You are about to delete
1794 $username's ID's?: $id_text<BR>
1795 <?/IF>
1796  
1797 This is an example for the usage of PATHINFO:
1798  
1799 <?GETURL NAME="/pub/download.cgi"
1800 PATHINFO="manual.pdf" oid=42
1801 MY VAR="$down_url">
1802  
1803 <a href="$down_url">Download</a>
1804  
1805 This will produce the following HTML code:
1806  
1807 <a href="/pub/download.cgi/manual.pdf?oid=42">Download</a>
1808  
1809 =head1 COMMAND <?HIDDENFIELDS>
1810  
1811 =head2 Type
1812  
1813 URL and Form Handling
1814  
1815 =head2 Syntax
1816  
1817 <?HIDDENFIELDS [ PARAMS=parameter_variables ]
1818 [ PAR_1=value_1 ... PAR_n=value_n ] >
1819  
1820 =head2 Description
1821  
1822 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.
1823  
1824 =head2 Parameter
1825  
1826 =over 8
1827  
1828 =item B<PARAMS>
1829  
1830 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).
1831  
1832 With the PARAMS option you can only pass parameters whose values are stored in variables with the same name (where case is significant).
1833  
1834 =item B<PAR_1..PAR_n>
1835  
1836 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>.
1837  
1838 =back
1839  
1840 =head2 Example
1841  
1842 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".
1843  
1844 <?FORM ACTION="x.secure.messager">
1845 <?HIDDENFIELDS PARAMS="$username, $password"
1846 event="show">
1847 <INPUT TYPE=SUBMIT VALUE="show messages">
1848 <?/FORM>
1849  
1850 =head1 COMMAND <?HTML>
1851  
1852 =head2 Type
1853  
1854 Control Structures
1855  
1856 =head2 Syntax
1857  
1858 <?HTML>
1859 ...
1860 <?/HTML>
1861  
1862 =head2 Description
1863  
1864 This command switches the CIPP program context to HTML. It's handy if you're doing a lot of logic and control structure stuff inside a <?PERL> block, but occasionally need some HTML output. You can nest <?PERL> and <?HTML> block arbitrarily.
1865  
1866 =head2 Example
1867  
1868 Some useless code in a <?PERL> block, with some <?HTML> output:
1869  
1870 <?PERL>
1871 if ( $foo ne $bar ) {
1872 <?HTML>
1873 <p>
1874 Sorry, I have to tell you, that \$foo and \$bar
1875 differ.
1876 </p>
1877 <?/HTML>
1878 }
1879 <?/PERL>
1880  
1881 =head1 COMMAND <?HTMLQUOTE>
1882  
1883 =head2 Type
1884  
1885 URL and Form Handling
1886  
1887 =head2 Syntax
1888  
1889 <?HTMLQUOTE VAR=variable_to_encode
1890 [ MY ] HTMLVAR=target_variable >
1891  
1892 =head2 Description
1893  
1894 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:
1895  
1896 & => &amp;
1897  
1898 < => &lt;
1899  
1900 " => &quot;
1901  
1902 =head2 Parameter
1903  
1904 =over 8
1905  
1906 =item B<VAR>
1907  
1908 This is the scalar variable containing the parameter you want to be quoted.
1909  
1910 =item B<HTMLVAR>
1911  
1912 This non-optional parameter takes the variable where the quoted content will be stored.
1913  
1914 =item B<MY>
1915  
1916 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.
1917  
1918 =back
1919  
1920 =head2 Example
1921  
1922 We produce a <TEXTAREA> tag with a quoted instance of the variable $text. Note: you can also use the <?TEXTAREA> command for this purpose.
1923  
1924 <?HTMLQUOTE VAR="$text" MY HTMLVAR="$html_text">
1925 <TEXTAREA NAME="text">$html_text</TEXTAREA>
1926  
1927 =head1 COMMAND <?!HTTPHEADER>
1928  
1929 =head2 Type
1930  
1931 Preprocessor
1932  
1933 =head2 Syntax
1934  
1935 <?!HTTPHEADER [ MY ] VAR=http_header_hash_ref >
1936 # Perl Code which modifies the
1937 # http_header_hash_ref variable
1938 <?/!HTTPHEADER>
1939  
1940 =head2 Description
1941  
1942 Use this command, if you want to modify the standard HTTP header response. CIPP generates by default a simple HTTP header of this form:
1943  
1944 Content-type: text/html\n\n
1945  
1946 In a new.spirit environment you can define a project wide default HTTP header extension, e.g. ,Pragme: no-cache", or something similar.
1947  
1948 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.
1949  
1950 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.
1951  
1952 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.
1953  
1954 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.
1955  
1956 =head2 Note
1957  
1958 This command is not implemented for Apache::CIPP and CGI::CIPP environments, but you can use it with new.spirit .
1959  
1960 =head2 Parameter
1961  
1962 =over 8
1963  
1964 =item B<VAR>
1965  
1966 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.
1967  
1968 =item B<MY>
1969  
1970 If you set the MY switch the created variable will be declared using 'my'. Its scope reaches to the end of the <?!HTTPHEADER> block .
1971  
1972 =back
1973  
1974 =head2 Example
1975  
1976 A HTTP header is created, which tells proxies how long they may cache the content of the produces HTML page.
1977  
1978 <?!HTTPHEADER MY VAR="$http">
1979 # delete a Pragma Tag (may be defined
1980 # globally in a new.spirit environment)
1981 delete $http->{Pragma};
1982  
1983 # read a global config
1984 <?CONFIG NAME="x.global">
1985  
1986 # get cache time
1987 my $cache_time = $global::cachable_time || 1200;
1988  
1989 # set Cache-Control header tag
1990 $http->{'Cache-Control'} =
1991 "max-age=$cache_time, public";
1992 <?!/HTTPHEADER>
1993  
1994 =head1 COMMAND <?IF>
1995  
1996 =head2 Type
1997  
1998 Control Structure
1999  
2000 =head2 Syntax
2001  
2002 <?IF COND=condition >
2003 ...
2004 [ <?ELSIF COND=condition >
2005 ... ]
2006 [ <?ELSE>
2007 ... ]
2008 <?/IF>
2009  
2010 =head2 Description
2011  
2012 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.
2013  
2014 =head2 Parameter
2015  
2016 =over 8
2017  
2018 =item B<COND>
2019  
2020 This takes a Perl condition. If this condition is true, the code inside the <?IF> block is executed.
2021  
2022 =back
2023  
2024 =head2 Example
2025  
2026 Only Larry gets a greeting message here.
2027  
2028 <?IF COND="$name eq 'Larry'">
2029 Hi Larry!
2030 <?/IF>
2031  
2032 =head1 COMMAND <?IMG>
2033  
2034 =head2 Type
2035  
2036 HTML Tag Replacement
2037  
2038 =head2 Syntax
2039  
2040 <?IMG SRC="image_file"
2041 [ NOSIZE ]
2042 [ additional_<IMG>_parameters ... ] >
2043  
2044 =head2 Description
2045  
2046 A HTML <IMG> Tag will be generated, whoms SRC option points to the appropriate image URL.
2047  
2048 If no WIDTH or HEIGHT is given and not NOSIZE, CIPP tries at compile time to determine the image's dimensions using the Perl module Image::Size and sets WIDTH and HEIGHT accordingly in the generated <IMG> tag. If the Image::Size module isn't installed on the system, this step is silently skipped.
2049  
2050 =head2 Parameter
2051  
2052 =over 8
2053  
2054 =item B<SRC>
2055  
2056 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.
2057  
2058 =item B<NOSIZE>
2059  
2060 Set this if you don't want CIPP to determine the image dimensions and to set WIDTH/HEIGHT accordingly.
2061  
2062 =item B<additional_IMG_parameters>
2063  
2064 All additional parameters are taken without changes into the produced <IMG> tag.
2065  
2066 =back
2067  
2068 =head2 Example
2069  
2070 In a new.spirit environment we produce a image link to another page, setting the border to 0.
2071  
2072 <?A HREF="x.main.menu">
2073 <?IMG SRC="x.images.logo" BORDER=0>
2074 <?/A>
2075  
2076 In CGI::CIPP or Apache::CIPP environment we provide an URL instead of a dot separated object name.
2077  
2078 <?A HREF="/main/menu.cgi">
2079 <?IMG SRC="/images/logo.jpg" BORDER=0>
2080 <?/A>
2081  
2082 =head1 COMMAND <?INCINTERFACE>
2083  
2084 =head2 Type
2085  
2086 Interface
2087  
2088 =head2 Syntax
2089  
2090 <?INCINTERFACE [ INPUT=list_of_variables ]
2091 [ OPTIONAL=list_of_variables
2092 [ NOQUOTE=list_of_variables ]
2093 [ OUTPUT=list_of_variables ] >
2094  
2095 =head2 Description
2096  
2097 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.
2098  
2099 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. :)
2100  
2101 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.
2102  
2103 =head2 Parameter
2104  
2105 =over 8
2106  
2107 All parameters of <?INCINTERFACE> expect a comma separated list of variables. All Perl variable types are supported: scalars ($), arrays (@)and hashes (%). Whitespace is ignored. Read the note beneath the NOQUOTE section about passing non scalar values to an Include.
2108  
2109 Note: You have to use lower case variable names, because the <?INCLUDE> command converts all variable names to lower case.
2110  
2111 =item B<INPUT>
2112  
2113 This parameters takes the list of variables the caller must provide in his <?INCLUDE> command (mandatory parameters).
2114  
2115 =item B<OPTIONAL>
2116  
2117 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.
2118  
2119 =item B<OUTPUT>
2120  
2121 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.
2122  
2123 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.
2124  
2125 =item B<NOQUOTE>
2126  
2127 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.
2128  
2129 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).
2130  
2131 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.
2132  
2133 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.
2134  
2135 =back
2136  
2137 =head2 Notes
2138  
2139 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.
2140  
2141 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.
2142  
2143 =head2 Example
2144  
2145 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.
2146  
2147 <?INCINTERFACE INPUT="$firstname, $lastname"
2148 OPTIONAL="@id"
2149 OUTPUT="$scalar, @list"
2150 NOQUOTE="@id">
2151 ...
2152  
2153 <?PERL>
2154 $scalar="returning a scalar";
2155 @list= ("returning", "a", "list");
2156 <?/PERL>
2157  
2158 The caller may use this <?INCLUDE> command. Note that all input parameter names are converted to lower case.
2159  
2160 <?INCLUDE NAME="/include/test.inc"
2161 FIRSTNAME="Larry"
2162 lastname="Wall"
2163 ID="(5,4,3)"
2164 MY
2165 $s=SCALAR
2166 @l=LIST>
2167  
2168 =head1 COMMAND <?INCLUDE>
2169  
2170 =head2 Type
2171  
2172 Import
2173  
2174 =head2 Syntax
2175  
2176 <?INCLUDE NAME=include_name
2177 [ input_parameter_1=Wert1 ... ]
2178 [ MY ]
2179 [ variable_1=output_parameter_1 ... ] >
2180  
2181 =head2 Description
2182  
2183 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.
2184  
2185 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.
2186  
2187 Please refer to the <?INCINTERFACE> chapter to see how parameters are processed by an Include.
2188  
2189 =head2 Parameter
2190  
2191 =over 8
2192  
2193 =item B<NAME>
2194  
2195 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.
2196  
2197 =item B<INPUT-PARAMETERS>
2198  
2199 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.
2200  
2201 =item B<OUTPUT-PARAMETERS>
2202  
2203 You can recieve parameters from the Include using the notation
2204  
2205 {$@%}variable=output_parameter
2206  
2207 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.
2208  
2209 For more details about Include output parameters refer to the appropriate section of the <?INCINTERFACE> chapter.
2210  
2211 =item B<MY>
2212  
2213 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.
2214  
2215 Important note
2216  
2217 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.
2218  
2219 =back
2220  
2221 =head2 Example
2222  
2223 See example of <?INCINTERFACE>.
2224  
2225 =head1 COMMAND <?INPUT>
2226  
2227 =head2 Type
2228  
2229 HTML Tag Replacement
2230  
2231 =head2 Syntax
2232  
2233 <?INPUT [ NAME=parameter_name ]
2234 [ VALUE=parameter_value ]
2235 [ SRC=image_object ]
2236 [ TYPE=input_type ] [ STICKY[=sticky_var] ]
2237 [ additional_<INPUT>_parameters ... ] >
2238  
2239 =head2 Description
2240  
2241 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.
2242  
2243 =head2 Parameter
2244  
2245 =over 8
2246  
2247 =item B<NAME>
2248  
2249 The name of the input widget.
2250  
2251 =item B<VALUE>
2252  
2253 This is the VALUE of the corresponding <INPUT> tag. Its content will be escaped.
2254  
2255 =item B<SRC>
2256  
2257 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.
2258  
2259 =item B<TYPE>
2260  
2261 Only the TYPEs ,radio" and ,checkbox" are specially handled when the STICKY option is also given.
2262  
2263 =item B<STICKY>
2264  
2265 If this option is set and the TYPE of the input widget is either "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.
2266  
2267 =item B<additional_INPUT_parameters>
2268  
2269 All additional parameters are taken without changes into the generated <INPUT> tag.
2270  
2271 =back
2272  
2273 =head2 Note
2274  
2275 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.
2276  
2277 =head2 Example
2278  
2279 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.
2280  
2281 <?VAR MY NAME="$username">larry<?/VAR
2282 <?VAR MY NAME="$password">this is my "password"<?/VAR>
2283 <?VAR MY NAME="@check">42<?/VAR>
2284  
2285 <?INPUT TYPE="TEXT" SIZE="40" VALUE="$username">
2286 <?INPUT TYPE="PASSWORD" SIZE="40" VALUE="$password">
2287 <?INPUT TYPE="CHECKBOX" NAME="check" VALUE="42"
2288 STICKY> 42
2289 <?INPUT TYPE="CHECKBOX" NAME="check" VALUE="43"
2290 STICKY> 43
2291  
2292 This will produce the following HTML code:
2293  
2294 <INPUT TYPE=TEXT SIZE=40 VALUE="larry">
2295 <INPUT TYPE=TEXT SIZE=40
2296 VALUE="this ist my &quot;password&quot;">
2297  
2298 <INPUT TYPE=CHECKBOX NAME="check" VALUE="42"
2299 CHECKED>
2300 <INPUT TYPE=CHECKBOX NAME="check" VALUE="43">
2301  
2302 =head1 COMMAND <?INTERFACE>
2303  
2304 =head2 Type
2305  
2306 Interface
2307  
2308 =head2 Syntax
2309  
2310 <?INTERFACE [ INPUT=list_of_variables ]
2311 [ OPTIONAL=list_of_variables ] >
2312  
2313 =head2 Description
2314  
2315 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.
2316  
2317 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.
2318  
2319 Using <?INTERFACE> is optional, your program officially has no input parameters, if you ommit it (it's still possible to get parmeters using the <?GETPARAM> command. But use this with care, because defining a unique interface at the top of your program is good coding style, whereas picking arbitary paramters from the environment anywhere in the program is rather confusing.)
2320  
2321 =head2 Parameter
2322  
2323 =over 8
2324  
2325 All parameters of <?INTERFACE> expect a comma separated list of variables. Scalars ($) and arrays (@) are supported. Whitespaces are ignored.
2326  
2327 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.
2328  
2329 =item B<INPUT>
2330  
2331 This parameters takes the list of variables the caller must pass to the CGI program.
2332  
2333 =item B<OPTIONAL>
2334  
2335 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.
2336  
2337 =back
2338  
2339 =head2 Notes
2340  
2341 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.
2342  
2343 =head2 Example
2344  
2345 We specify an interface for two scalars and an array.
2346  
2347 <?INTERFACE INPUT="$firstname, $lastname"
2348 OPTIONAL="@id">
2349  
2350 A HTML form which adresses this CGI program may look like this (assuming we are in a CGI::CIPP or Apache::CIPP environment).
2351  
2352 <?VAR MY NAME="@id" NOQUOTE>(1,2,3,4)<?/VAR>
2353  
2354 <?FORM ACTION="/user/save.cgi">
2355 <?HIDDENFIELDS PARAMS="@id">
2356 <P>firstname:
2357 <?INPUT TYPE=TEXT NAME=firstname>
2358 <P>lastname:
2359 <?INPUT TYPE=TEXT NAME=lastname>
2360 <?/FORM>
2361  
2362 =head1 COMMAND <?L>
2363  
2364 =head2 Type
2365  
2366 Miscellaneous
2367  
2368 =head2 Syntax
2369  
2370 <?l [key="value" ...] >
2371 Message to be translated with Locale::TextDomain,
2372 including placehoders: {key}
2373 <?/l>
2374  
2375 =head2 IMPORTANT NOTE
2376  
2377 This syntax is functionally functional, but currently implemented without any active translation. The message text is passed through as-is, including placeholder substitution. Translation functionality will follow, inlcuding the neccessary command line tools to extract the message catalog from CIPP source files.
2378  
2379 =head2 Description
2380  
2381 This command uses (resp. will use) the Locale::TextDomain module to translate the text in the enclosed block, including the substitution of placeholders with actual values.
2382  
2383 Placeholder names are written in curly brackets. The actual values are passed as options to the <?L> command. Note that the placeholder names are treated case sensitive.
2384  
2385 You may use this command in HTML and PERL context as well. In HTML context the translated text is printed into the HTML page. In PERL context a Perl expression is generated which can be used in any expression context, e.g. a simple variable assignment or as a part of a arbitrary complex Perl expression.
2386  
2387 =head2 Examples
2388  
2389 Print a translated "Hello World":
2390
2391 <?l>Hello World<?/l>
2392  
2393 Placeholder example:
2394  
2395 <?l cnt="$age">You are {age} year(s) old.<?/l>
2396  
2397 Use in Perl Context
2398
2399 <?PERL>
2400 #-- Simple variable assignment
2401 my $translated = <?l age="42">You You are {age} year(s) old.<?/l>;
2402  
2403 #-- Assign a bold message to a variable
2404 my $translated_bold =
2405 "<b>".
2406 <?l age="42">You are {age} year(s) old.<?/l>.
2407 "</b>";
2408  
2409 #-- Throw a translated error message
2410 die <?l>A fatal error occured<?/l>;
2411 <?/PERL>
2412  
2413 =head1 COMMAND <?LOG>
2414  
2415 =head2 Type
2416  
2417 Exception Handling
2418  
2419 =head2 Syntax
2420  
2421 <?LOG MSG=error_message
2422 [ TYPE=type_of_message ]
2423 [ FILENAME=special_logfile ]
2424 [ THROW=exception ] >
2425  
2426 =head2 Description
2427  
2428 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.
2429  
2430 Log file entries contain a timestamp, client IP adress, a message type and the message itself.
2431  
2432 =head2 Parameter
2433  
2434 =over 8
2435  
2436 =item B<MSG>
2437  
2438 This is the message.
2439  
2440 =item B<TYPE>
2441  
2442 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.
2443  
2444 =item B<FILENAME>
2445  
2446 If you want to add this message to a special logfile you pass the full path of this file with FILENAME.
2447  
2448 =item B<THROW>
2449  
2450 With this parameter you can provide a user defined exception to be thrown on failure. The default exception thrown by this statement is log.
2451  
2452 An exception will be thrown, if the log file is not writable or the path is not reachable.
2453  
2454 =back
2455  
2456 =head2 Example
2457  
2458 If the variable $error is set a simple entry will be added to the default logfile.
2459  
2460 <?IF COND="$error != 0">
2461 <?LOG MSG="internal error: $error">
2462 <?/IF>
2463  
2464 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.
2465  
2466 <?LOG MSG="error in SQL statement"
2467 TYPE="dberror"
2468 FILENAME="/tmp/my.log"
2469 THROW="fileio">
2470  
2471 =head1 COMMAND <?MODULE>
2472  
2473 =head2 Type
2474  
2475 Import
2476  
2477 =head2 Syntax
2478  
2479 <?MODULE NAME=perl_module_name
2480 [ ISA=list_of_isa_modules ] >
2481 ...
2482 <?/MODULE>
2483  
2484 =head2 Description
2485  
2486 With this command you define a CIPP Perl Module. This works currently in a new.spirit environment only.
2487  
2488 The generated Perl code will be installed in the project specific lib/ folder and can be imported with the <?USE> or <?REQUIRE> command, resp. with the correspondent Perl commands.
2489  
2490 =head2 Parameter
2491  
2492 =over 8
2493  
2494 =item B<NAME>
2495  
2496 This is the Perl name of the module you want to use. Nested module names are delimited by ::.
2497  
2498 It is not possible to use a variable or expression for NAME, you must always use a literal string here.
2499  
2500 =item B<ISA>
2501  
2502 You can specify a comma separated list of module names, which should be added the the module's @ISA array (that means: the modules from which the actual module is derived). All modules listed here will be loaded dynamically using Perl's require command. If you need compile time loading of the modules (e.g. for importing symbols in the actual namespace), use Perl's "use base" instead or load all modules explicitely with the "use" command.
2503  
2504 =back
2505  
2506 =head2 Example
2507  
2508 <?MODULE NAME="Test::Module" ISA="Test::Base">
2509  
2510 #-- Using CIPP's <?SUB> command enables a lexical
2511 #-- variable check inside the sub, which prevents
2512 #-- the sub from accessing lexicals defined outside.
2513 <?SUB NAME="new">
2514 <?PERL>
2515 my $class = shift;
2516 return bless {
2517 foo => 1,
2518 }, $class;
2519 <?/PERL>
2520 <?/SUB>
2521  
2522 #-- But you can write the sub still as a sub ;)
2523 <?PERL>
2524 sub print_foo {
2525 my $self = shift;
2526 print $self->{foo},"<p>\n";
2527 }
2528 <?/PERL>
2529  
2530 <?/MODULE>
2531  
2532 =head1 COMMAND <?MY>
2533  
2534 =head2 Type
2535  
2536 Variables and Scoping
2537  
2538 =head2 Syntax
2539  
2540 <?MY [ VAR=list_of_variables ]
2541 variable_1 ... variable_N >
2542  
2543 =head2 Description
2544  
2545 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.
2546  
2547 All types of Perl variables (Scalars, Arrays and Hashes) can be declared this way.
2548  
2549 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.
2550  
2551 =head2 Parameter
2552  
2553 =over 8
2554  
2555 =item B<VAR>
2556  
2557 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.
2558  
2559 =item B<variable_1..variable_N>
2560  
2561 You can place additionel variables everywhere inside the <?MY> command.
2562  
2563 =item B<Note:>
2564  
2565 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.
2566  
2567 =back
2568  
2569 =head2 Example
2570  
2571 See <?BLOCK>
2572  
2573 =head1 COMMAND <?OPTION>
2574  
2575 =head2 Type
2576  
2577 HTML Tag Replacement
2578  
2579 =head2 Syntax
2580  
2581 <?OPTION [ VALUE=parameter_value ]
2582 [ additional_<OPTION>_parameters ... ] >
2583 ...
2584 <?/OPTION>
2585  
2586 =head2 Description
2587  
2588 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).
2589  
2590 =head2 Parameter
2591  
2592 =over 8
2593  
2594 =item B<VALUE>
2595  
2596 This is the VALUE of the generated <OPTION> tag. Its content will be escaped.
2597  
2598 =item B<additional_OPTION_parameters>
2599  
2600 All additional parameters are taken over without changes into the produced <OPTION> tag.
2601  
2602 =back
2603  
2604 =head2 Example
2605  
2606 See the description of the <?SELECT> command for a complete example.
2607  
2608 =head1 COMMAND <?PERL>
2609  
2610 =head2 Type
2611  
2612 Control Structure
2613  
2614 =head2 Syntax
2615  
2616 <?PERL [ COND=condition ] >
2617 ...
2618 <?/PERL>
2619  
2620 =head2 Description
2621  
2622 With this command you open a block with pure Perl commands. You may place any valid Perl code inside this block.
2623  
2624 You may use the Perl print statement to produce HTML code (or whatever output you want) for the client.
2625  
2626 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.
2627  
2628 =head2 Parameter
2629  
2630 =over 8
2631  
2632 =item B<COND>
2633  
2634 If you set the COND parameter, the Perl block is only executed, if the given condition is true.
2635  
2636 =back
2637  
2638 =head2 Example
2639  
2640 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.
2641  
2642 <?PERL>
2643 $text =~ s/nt/no thanks/g;
2644 print $text;
2645 <?/PERL>
2646  
2647 If this list contains some elements a string based on the list is generated.
2648  
2649 <?PERL COND="scalar(@list) != 0">
2650 my ($string, $element);
2651 foreach $element ( @list ) {
2652 $string .= $element;
2653 }
2654 print $string;
2655 <?/PERL>
2656 # OK, its easier to use 'join', but it's
2657 # only an example... :-)
2658  
2659 =head1 COMMAND <?!PROFILE>
2660  
2661 =head2 Type
2662  
2663 Preprocessor Command
2664  
2665 =head2 Syntax
2666  
2667 <?!PROFILE [ NAME="profile_name" ]
2668 [ DEEP ]
2669 [ FILENAME="profile_filename" ]
2670 [ FILTER="minimum_duration" ]
2671 [ SCALEUNIT="" ] >
2672 ...
2673 <?!/PROFILE>
2674  
2675 =head2 Description
2676  
2677 This preprocessor command controls the generation of profiling code for a specific block.
2678  
2679 Currently two tasks are profiled: SQL statements and Include executions. If profiling is active, a line is added to the given log file for every executed SQL and Include command, giving a protocol of the execution durations. You need the Perl module Time::HiRes installed on your system if you want to use profiling.
2680  
2681 The profile log file will be truncated automatically, if the size exceeds 8MB.
2682  
2683 =head2 Parameter
2684  
2685 =over 8
2686  
2687 =item B<NAME>
2688  
2689 Gives a name to this profile action, which will appear in the log output.
2690  
2691 =item B<DEEP>
2692  
2693 If you set the DEEP option, the content all included Includes will be profiled, too. Otherwise only the document itself, where the <?!PROFILE> command stands, will be profiled.
2694  
2695 Note that the DEEP switch can produce lots of output.
2696  
2697 =item B<FILENAME>
2698  
2699 Specifies the filename for the profile output. This defaults to "$project_log_dir/profile.log".
2700  
2701 =item B<FILTER>
2702  
2703 You can filter very fast executed sections by defining a minimum duration here. E.g. set this to "1.2" if you want to omit all entries which need less than 1.2 seconds. This defaults to 0.
2704  
2705 =item B<SCALEUNIT>
2706  
2707 Each profile log entry has a "time meter", which prints five o's, for a duration of 1 second (see example output beyond). That's a B<SCAULEUNIT> of 0.2. Change this default to get higher or lower precision here.
2708  
2709 =back
2710  
2711 =head2 Note
2712  
2713 You can tag specific <?SQL> commands in the profile log by specifying the B<PROFILE> option in the corresponding <?SQL> commands. This helps identifying specific SQL statements inside the log output.
2714  
2715 =head2 Example
2716  
2717 The following SQL Statement and Include will be profiled as "foobar", to "/tmp/profile.log", with all inclusion levels, but only code sections which need longer than 0.005 seconds.
2718  
2719 <?!PROFILE
2720 NAME="foobar"
2721 FILENAME="/tmp/profile.log"
2722 FILTER="0.005"
2723 DEEP>
2724  
2725 <?SQL SQL="select foo, bla
2726 from bar
2727 where baz=?"
2728 PARAMS="$baz"
2729 MY VAR="$foo, $bla">
2730 $foo $bla<br>
2731 <?/SQL>
2732  
2733 <?INCLUDE NAME="/foo/bar.inc">
2734  
2735 <?!/PROFILE>
2736  
2737 #-- no profiling here
2738 <?INCLUDE NAME="/bar/foo.inc">
2739  
2740 Here some example profiling output (it's not from the code example above):
2741  
2742 PROFILE 923 foobar START ----------------------------------
2743 PROFILE 923 foobar inc in + Login/Check.code
2744 PROFILE 923 foobar inc out + Login/Check.code ............... 0.0665
2745 PROFILE 923 foobar sql + select count(*) from MSG_Message
2746 PROFILE 923 foobar sql out + select count(*) from MSG_Message 1.0039 ooooo
2747 PROFILE 923 foobar END SUMMARY ========================== 1.0704 ooooo
2748  
2749 923 is the PID of the corresponding process, "foobar" the B<NAME>
2750 specified in the <?!PROFILE> tag. START/END mark a profiled
2751 block. "inc in" and "inc out" stands for "entering Include"
2752 and "leaving Include", "sql" and "sql out" appropriatly for <?SQL>
2753 statements. The needed time is printed on the right, followed
2754 by the o-Meter.
2755  
2756 =head1 COMMAND <?REQUIRE>
2757  
2758 =head2 Type
2759  
2760 Import
2761  
2762 =head2 Syntax
2763  
2764 <?REQUIRE NAME="cipp_perl_module" >
2765  
2766 =head2 Description
2767  
2768 This command loads a module at runtime. A module created with new.spirit in conjunction with the <?MODULE> command, or any other Perl module, which can be found in the Perl library directories.
2769  
2770 =head2 Parameter
2771  
2772 =over 8
2773  
2774 =item B<NAME>
2775  
2776 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.
2777  
2778 You may also place a B<lexical> scalar variable here (must not contain colons), which has the name of the module. So it is possible to load modules dynamically at runtime.
2779  
2780 =back
2781  
2782 =head2 Example
2783  
2784 # refer to the description of <?MODULE> to see
2785 # the implementation of the Test::Module module.
2786 <?REQUIRE NAME="Test::Module">
2787  
2788 <?PERL>
2789 my $t = Test::Module->new;
2790 $t->print_foo;
2791 <?/PERL>
2792  
2793 =head1 COMMAND <?ROLLBACK>
2794  
2795 =head2 Type
2796  
2797 SQL
2798  
2799 =head2 Syntax
2800  
2801 <?ROLLBACK [ DB=database_name ]
2802 [ DBH=database_handle ]
2803 [ THROW=exception ] >
2804  
2805 =head2 Description
2806  
2807 The <?ROLLBACK> command concludes the actual transaction and cancels all changes to the database.
2808  
2809 Using <?ROLLBACK> in <?AUTOCOMMIT ON> mode is not possible and will result in a runtime exception.
2810  
2811 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.
2812  
2813 =head2 Parameter
2814  
2815 =over 8
2816  
2817 =item B<DB>
2818  
2819 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.
2820  
2821 If DB is ommited the project default database is used.
2822  
2823 If DB is a variable name (resp. something containing a $ sigil) the content of this variable will be evaluated to the corresponding database name at runtime.
2824  
2825 =item B<DBH>
2826  
2827 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.
2828  
2829 =item B<THROW>
2830  
2831 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.
2832  
2833 If the underlying database is not capable of transactions (e.g. MySQL) execution of this command will throw an exception.
2834  
2835 =back
2836  
2837 =head2 Example
2838  
2839 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.
2840  
2841 <?SQL SQL="insert into foo (num, str)
2842 values (42, 'bar');">
2843 <?/SQL>
2844 <?ROLLBACK THROW="ROLLBACK_Exception">
2845  
2846 =head1 COMMAND <?SAVEFILE>
2847  
2848 =head2 Type
2849  
2850 Interface
2851  
2852 =head2 Syntax
2853  
2854 <?SAVEFILE FILENAME=server_side_filename
2855 VAR=upload_formular_variable
2856 [ SYMBOLIC ]
2857 [ THROW=exception ] >
2858  
2859 =head2 Description
2860  
2861 This command is deprecated. Use <?FETCHUPLOAD> instead.
2862  
2863 This command saves a file which was uploaded by a client in the webservers filesystem.
2864  
2865 =head2 Parameter
2866  
2867 =over 8
2868  
2869 =item B<FILENAME>
2870  
2871 This is the fully qualified filename where the file will be stored.
2872  
2873 =item B<VAR>
2874  
2875 This is the identifier you used in the HTML form for the filename on client side, the value of the <INPUT NAME> parameter) .
2876  
2877 =item B<SYMBOLIC>
2878  
2879 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.
2880  
2881 =item B<THROW>
2882  
2883 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.
2884  
2885 =back
2886  
2887 =head2 Note
2888  
2889 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.
2890  
2891 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).
2892  
2893 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.
2894  
2895 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.
2896  
2897 <?INTERFACE INPUT="$upfilename">
2898  
2899 <?MY $client_filename>
2900  
2901 <?PERL> $client_filename = "$upfilename" <?/PERL>
2902  
2903 =head2 Example
2904  
2905 First we provide a HTML form with the file upload field.
2906  
2907 <?FORM METHOD="POST" ACTION="/image/save.cgi"
2908 ENCTYPE="multipart/form-data">
2909 Fileupload:
2910  
2911 <INPUT TYPE=FILE NAME="upfilename" SIZE=45><BR>
2912 <INPUT TYPE="reset">
2913 <INPUT TYPE="submit" NAME="submit" VALUE="Upload">
2914 </FORM>
2915  
2916 The /image/save.cgi program has the following code to store the file in the filesystem.
2917  
2918 <?SAVEFILE FILENAME="/tmp/upload.tmp"
2919 VAR="upfilename"
2920 THROW=my_upload>
2921  
2922 The same procedure using the RUNTIME parameter.
2923  
2924 <?VAR MY=$field_name>upfilename<?/VAR>
2925 <?SAVEFILE FILENAME="/tmp/upload.tmp"
2926 SYMBOLIC
2927 VAR="$field_name"
2928 THROW=upload>
2929  
2930 =head1 COMMAND <?SELECT>
2931  
2932 =head2 Type
2933  
2934 HTML Tag Replacement
2935  
2936 =head2 Syntax
2937  
2938 <?SELECT [ NAME=parameter_name ]
2939 [ MULTIPLE ] [ STICKY ]
2940 [ additional_<SELECT>_parameters ... ] >
2941 ...
2942 <?/SELECT>
2943
2944  
2945 =head2 Description
2946  
2947 This command generates a selection widget providing preservation of the selection state (similar to the STICKY feature of the <?INPUT> command).
2948  
2949 =head2 Parameter
2950  
2951 =over 8
2952  
2953 =item B<NAME>
2954  
2955 The name of the formular widget.
2956  
2957 =item B<MULTIPLE>
2958  
2959 If this is set, a multi selection list will be generated, instead of a single selection popup widget.
2960  
2961 =item B<STICKY>
2962  
2963 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.
2964  
2965 =item B<additional_SELECT_parameters>
2966  
2967 All additional parameters are taken over without changes into the produced <SELECT> tag.
2968  
2969 =back
2970  
2971 =head2 Note
2972  
2973 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.
2974  
2975 =head2 Example
2976  
2977 This is a complete CIPP program, which provides a mulitple selection list and preservers its state over subsequent executions of the program.
2978  
2979 <?INCINTERFACE OPTIONAL="@list">
2980  
2981 <?FORM ACTION="sticky.cgi">
2982  
2983 <?SELECT NAME="list" MULTIPLE STICKY>
2984 <?OPTION VALUE="1">value 1<?/OPTION>
2985 <?OPTION VALUE="2">value 2<?/OPTION>
2986 <?OPTION VALUE="3">value 3<?/OPTION>
2987 <?/SELECT>
2988  
2989 <?INPUT TYPE="submit" VALUE="send">
2990  
2991 <?/FORM>
2992  
2993 =head1 COMMAND <?SQL>
2994  
2995 =head2 Type
2996  
2997 SQL
2998  
2999 =head2 Syntax
3000  
3001 <?SQL SQL=sql_statement
3002 [ VAR=list_of_variables_for_the_result ]
3003 [ PARAMS=input_parameter ]
3004 [ WINSTART=start_row ]
3005 [ WINSIZE=number_of_rows_to_fetch ]
3006 [ COND=fetch_condition ]
3007 [ RESULT=sql_return_code ]
3008 [ DB=database_name ]
3009 [ DBH=database_handle ]
3010 [ THROW=exception ]
3011 [ MY ]
3012 [ PROFILE=profile_label ] >
3013 ...
3014 <?/SQL>
3015  
3016 =head2 Description
3017  
3018 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.
3019  
3020 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.
3021  
3022 =head2 Parameter
3023  
3024 =over 8
3025  
3026 =item B<SQL>
3027  
3028 This takes the SQL statement to be executed. A trailing semicolon will be stripped off.
3029  
3030 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.
3031  
3032 This is an example of a simple insert without placeholders.
3033  
3034 <?SQL SQL="insert into foo values (42, 'bar')">
3035 <?/SQL>
3036  
3037 =item B<VAR>
3038  
3039 If you set the VAR parameter, CIPP asumes that you execute a SQL statement which returns a result set (normally a SELECT statement).
3040  
3041 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.
3042  
3043 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.
3044  
3045 This is an example of creating a simple HTML table out of an SQL result set.
3046  
3047 <TABLE>
3048 <?SQL SQL="select num, str from foo"
3049 MY VAR="$n, $s">
3050 <TR>
3051 <TD>$n</TD>
3052 <TD>$s</TD>
3053 </TR>
3054 <?/SQL>
3055 </TABLE>
3056  
3057 =item B<PARAMS>
3058  
3059 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. Also empty strings will be converted to undef resp. NULL. The content of the first expression substitutes the first placeholder in the SQL string, etc.
3060  
3061 Values of parameters are quoted implicitly. 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.).
3062  
3063 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.)
3064  
3065 Here are some examples which demonstate the usage of placeholders.
3066  
3067 <?PERL>
3068 my $n = 42;
3069 my $s = "Hello 'World'";
3070  
3071 <?SQL SQL="insert into foo (num, str, unix_time)
3072 values (?, ?, ?)"
3073 PARAMS="$n, $s, time()">
3074 <?/SQL>
3075  
3076 my $where_num = 42;
3077  
3078 <?SQL SQL="select num, str
3079 from foo
3080 where num = ?"
3081 PARAMS="$where_num">
3082 MY VAR="$column_n, $column_s">
3083 <?HTML>
3084 n=$column_n s='$column_s'<BR>
3085 <?/HTML>
3086 <?/SQL>
3087  
3088 <?SQL SQL="update foo
3089 set str=?
3090 where n=?"
3091 PARAMS="$s, $where_num">
3092 <?/SQL>
3093 <?/PERL>
3094  
3095 =item B<WINSTART>
3096  
3097 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.
3098  
3099 The row count begins with 1.
3100  
3101 Here is an example. The first 5 rows will be skipped.
3102  
3103 <?SQL SQL="select num, str from foo"
3104 MY VAR="$n, $s"
3105 WINSTART=6
3106 n=$n s='$s'<BR>
3107 <?/SQL>
3108  
3109 =item B<WINSIZE>
3110  
3111 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.
3112  
3113 This is an example of doing this (skipping 5 rows, processing 5 rows).
3114  
3115 <?SQL SQL="select num, str from foo"
3116 MY VAR="$n, $s"
3117 WINSTART=6 WINSIZE=5
3118 n=$n s='$s'<BR>
3119 <?/SQL>
3120  
3121 =item B<COND>
3122  
3123 If the COND parameter is given, the given condition is checked before fetching a row from a SELECT statement. This is useful for premature leaving of the <?SQL> loop.
3124  
3125 Example:
3126  
3127 my @bus;
3128 my $bus_is_full = 10;
3129  
3130 <?SQL SQL="select name
3131 from person"
3132 COND="@bus < $bus_is_full">
3133  
3134 push @bus, $person;
3135
3136 <?/SQL>
3137  
3138 =item B<RESULT>
3139  
3140 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.
3141  
3142 Example:
3143  
3144 <?SQL SQL="delete from foo where num=42"
3145 MY RESULT=$deleted>
3146 <?/SQL>
3147  
3148 Successfully deleted $deleted rows!
3149  
3150 =item B<DB>
3151  
3152 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.
3153  
3154 If DB is ommited the project default database is used.
3155  
3156 If DB is a variable name (resp. something containing a $ sigil) the content of this variable will be evaluated to the corresponding database name at runtime.
3157  
3158 =item B<DBH>
3159  
3160 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.
3161  
3162 =item B<THROW>
3163  
3164 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.
3165  
3166 =item B<MY>
3167  
3168 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.
3169  
3170 =item B<PROFILE>
3171  
3172 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.
3173  
3174 =head2 Leaving the <?SQL> loop prematurely
3175  
3176 You can use the COND option for leaving the SQL loop of a select statement prematurely. The CIPP 2.x construct "last SQL" is deprecated and should not be used in newly written code.
3177  
3178 =back
3179  
3180 =head2 Example
3181  
3182 Please refer to the examples in the parameter sections above.
3183  
3184 =head1 COMMAND <?SUB>
3185  
3186 =head2 Type
3187  
3188 Control Structure
3189  
3190 =head2 Syntax
3191  
3192 <?SUB NAME=subroutine_name
3193 [ IMPORT=list_of_global_variables ] >
3194 ...
3195 <?/SUB>
3196  
3197 =head2 Description
3198  
3199 This defines the <?SUB> block as a Perl subroutine. You may use any CIPP commands inside the block.
3200  
3201 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.
3202  
3203 =head2 Parameter
3204  
3205 =over 8
3206  
3207 =item B<NAME>
3208  
3209 This is the name of the subroutine. Please refer to the perlsub manpage for details about Perl subroutines.
3210  
3211 It is not possible to declare protoyped subroutines with <?SUB>.
3212  
3213 =item B<IMPORT>
3214  
3215 If your subroutine needs acccess to lexical variables declared outside of the subroutine's scope, you must list these variables here. Using such global variables without listing them in the IMPORT option will be reported during CIPP's Perl compiler error checking as a violation of "strict vars". In persistent environments accessing such variables may be evil, when the program itself will be compiled as a subroutine. This way your subroutine is a "inner" subroutine, and the global variables aren't global any more the way you expected. See
3216  
3217 http://perl.apache.org/docs/general/perl_reference/perl_reference.html
3218  
3219 for a detailed discussion of this problem (chapter "my() Scoped Variable in Nested Subroutines").
3220  
3221 =back
3222  
3223 =head2 Example
3224  
3225 This is a subroutine to create a text input field in a specific layout.
3226  
3227 <?SUB NAME=print_input_field>
3228 # Catch the input parameters
3229 <?MY $label $name $value>
3230 <?PERL>
3231 ($label, $name, $value) = @_;
3232 <?/PERL>
3233  
3234 # print the text field
3235 <P>
3236 <B>$label:</B><BR>
3237 <?INPUT TYPE=TEXT SIZE=40 NAME=$name VALUE=$value>
3238 <?/SUB>
3239  
3240 You may call this subroutine from every Perl context this way.
3241  
3242 <?PERL>
3243 print_input_field ('Firstname', 'firstname', 'Larry');
3244 print_input_field ('Lastname', 'surname', 'Wall');
3245 <?/PERL>
3246  
3247 This is a proper example of using a global lexical variable. It's a small class which provides an instance counter for its objects.
3248  
3249 <?MODULE NAME="My::ObjectCounter">
3250  
3251 <?VAR NAME="$count">0<?/VAR>
3252  
3253 <?SUB NAME="new" IMPORT="$count">
3254 <?PERL>
3255 my $class = shift;
3256 my $self = {
3257 nr => ++$count,
3258 };
3259 return bless $self, $class;
3260 <?/PERL>
3261 <?/SUB>
3262  
3263 <?/MODULE>
3264  
3265 =head1 COMMAND <?SWITCHDB>
3266  
3267 =head2 Type
3268  
3269 Database access
3270  
3271 =head2 Syntax
3272  
3273 <?SWITCHDB
3274 { DB=database_name |
3275 DBH=database_handle } >
3276 ...
3277 <?/SWITCHDB>
3278  
3279 =head2 Description
3280  
3281 Inside the block described by <?SWITCHDB> the default database is switched
3282 to the given DB name or DBH database handle.
3283  
3284 <?SWITCHDB> can be nested. Also it's exception safe. It's guaranteed that
3285 the original default database handle is active after the <?SWITCHDB>
3286 block.
3287  
3288 =head2 Parameter
3289  
3290 =over 8
3291  
3292 =item B<DB>
3293  
3294 This is the CIPP internal name of the database, which should be the new default inside the <?SWITCHDB> block. 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.
3295  
3296 =item B<DBH>
3297  
3298 Use this option to pass an existing DBI database handle, which should be the new default database. You can't use the DBH option in conjunction with DB.
3299  
3300 =back
3301  
3302 =head2 Example
3303  
3304 An Include is called twice, once with the project's default database,
3305 a second time with another specific database:
3306  
3307 # print statistics using the default database
3308 <?INCLUDE NAME="x.statistic.print">
3309  
3310 <?SWITCHDB DB="x.special.db">
3311  
3312 # print statistics from this specific database
3313 <?INCLUDE NAME="x.statistic.print">
3314  
3315 <?/SWITCHDB>
3316  
3317 # here we have the standard default database again
3318  
3319 =head1 COMMAND <?TEXTAREA>
3320  
3321 =head2 Type
3322  
3323 HTML Tag Replacement
3324  
3325 =head2 Syntax
3326  
3327 <?TEXTAREA [ additional_<TEXTAREA>_parameters ... ]>
3328 ...
3329 <?/TEXTAREA>
3330  
3331 =head2 Description
3332  
3333 This generates a HTML <TEXTAREA> tag, with a HTML quoted content to prevent from HTML syntax clashes.
3334  
3335 =head2 Parameter
3336  
3337 =over 8
3338  
3339 =item B<additional_TEXTAREA_parameters>
3340  
3341 There are no special parameters. All parameters you pass to <?TEXTAREA> are taken in without changes.
3342  
3343 =back
3344  
3345 =head2 Example
3346  
3347 This creates a <TEXTAREA> initialized with the content of the variable $fulltext.
3348  
3349 <?VAR MY NAME=$fulltext><B>HTML Text</B><?/VAR>
3350 <?TEXTAREA NAME=fulltext ROWS=10
3351 COLS=80>$fulltext<?/TEXTAREA>
3352  
3353 This leads to the following HTML code.
3354  
3355 <TEXTAREA NAME=fulltext ROWS=10
3356 COLS=80>&lt;B>HTML Text&lt;B></TEXTAREA>
3357  
3358 =head1 COMMAND <?THROW>
3359  
3360 =head2 Type
3361  
3362 Exception Handling
3363  
3364 =head2 Syntax
3365  
3366 <?THROW THROW=exception [ MSG=message ] >
3367  
3368 =head2 Description
3369  
3370 This command throws an user specified exception.
3371  
3372 =head2 Parameter
3373  
3374 =over 8
3375  
3376 =item B<THROW>
3377  
3378 This is the exception identifier, a simple string. It is the criteria for the <?CATCH> command.
3379  
3380 =item B<MSG>
3381  
3382 Optionally, you can pass a additional message for your exception, e.g. a error message you have got from a system call.
3383  
3384 =back
3385  
3386 =head2 Example
3387  
3388 We try to open a file and throw a exception if this fails.
3389  
3390 <?MY $error>
3391 <?PERL>
3392 open (INPUT, '/bar/foo') or $error=$!;
3393 <?/PERL>
3394  
3395 <?IF COND="$error">
3396 <?THROW THROW="open_file"
3397 MSG="file /bar/foo, $error">
3398 <?/IF>
3399  
3400 =head2 Note
3401  
3402 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:
3403  
3404 identifier TAB message
3405  
3406 This is the above example using this technique.
3407  
3408 <?PERL>
3409  
3410 open (INPUT, '/bar/foo')
3411  
3412 or die "open_file\tfile /bar/foo, $!";
3413  
3414 <?/PERL>
3415  
3416 =head1 COMMAND <?TRY>
3417  
3418 =head2 Type
3419  
3420 Exception Handling
3421  
3422 =head2 Syntax
3423  
3424 <?TRY >
3425 ...
3426 <?/TRY >
3427  
3428 =head2 Description
3429  
3430 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.
3431  
3432 You can provide your own exception handling using the <?TRY> and <?CATCH> commands.
3433  
3434 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.
3435  
3436 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.
3437  
3438 =head2 Example
3439  
3440 We try to insert a row into a database table and write a log file entry with the error message, if the INSERT fails.
3441  
3442 <?TRY>
3443 <?SQL SQL="insert into foo values (42, 'bar')">
3444 <?/SQL>
3445 <?/TRY>
3446  
3447 <?CATCH THROW="insert" MY MSGVAR="$msg">
3448 <?LOG MSG="unable to insert row, $msg"
3449 TYPE="database">
3450 <?/CATCH>
3451  
3452 =head1 COMMAND <?URLENCODE>
3453  
3454 =head2 Type
3455  
3456 URL and Form Handling
3457  
3458 =head2 Syntax
3459  
3460 <?URLENCODE VAR=unencoded_variable
3461 [ MY ] ENCVAR=encoded_variable >
3462  
3463 =head2 Description
3464  
3465 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.
3466  
3467 =head2 Parameter
3468  
3469 =over 8
3470  
3471 =item B<VAR>
3472  
3473 This is the variable you want to be encoded.
3474  
3475 =item B<ENCVAR>
3476  
3477 The encoded result will be stored in this variable.
3478  
3479 =item B<MY>
3480  
3481 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.
3482  
3483 =back
3484  
3485 =head2 Example
3486  
3487 In this example we link an external CGI script and pass the content of the variable $query after using <?URLENCODE> on it.
3488  
3489 <?URLENCODE VAR=$query MY ENCVAR=$enc_query>
3490 <A HREF="www.search.org?query=$enc_query">
3491 find something
3492  
3493 </A>
3494  
3495 Hint: in CGI::CIPP and Apache::CIPP environments you also can use the <?A> command for doing this.
3496  
3497 =head1 COMMAND <?USE>
3498  
3499 =head2 Type
3500  
3501 Import
3502  
3503 =head2 Syntax
3504  
3505 <?USE NAME=perl_module >
3506  
3507 =head2 Description
3508  
3509 With this command you can access the extensive Perl module library. You can access any Perl module which is installed on your system.
3510  
3511 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.
3512  
3513 If you want to use a CIPP Module (generated with new.spirit and the <?MODULE> command), use <?REQUIRE> instead.
3514  
3515 =head2 Parameter
3516  
3517 =over 8
3518  
3519 =item B<NAME>
3520  
3521 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 :-).
3522  
3523 It is not possible to use a variable or expression for NAME, you must always use a literal string here.
3524  
3525 =back
3526  
3527 =head2 Example
3528  
3529 The standard modules File::Path and Text::Wrap are imported to your program.
3530  
3531 <?USE NAME="File::Path">
3532 <?USE NAME="Text::Wrap">
3533  
3534 =head1 COMMAND <?VAR>
3535  
3536 =head2 Type
3537  
3538 Variables and Scoping
3539  
3540 =head2 Syntax
3541  
3542 <?VAR NAME=variable
3543 [ MY ]
3544 [ DEFAULT=value ]
3545 [ NOQUOTE ]>
3546 ...
3547 <?/VAR>
3548  
3549 =head2 Description
3550  
3551 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.
3552  
3553 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.
3554  
3555 =head2 Parameter
3556  
3557 =over 8
3558  
3559 =item B<NAME>
3560  
3561 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.
3562  
3563 These are some examples for creating variables using <?VAR>.
3564  
3565 <?VAR NAME=$skalar>a string<?/VAR>
3566 <?VAR NAME=@liste>(1,2,3,4)<?/VAR>
3567 <?VAR NAME=%hash>( 1 => 'a', 2 => 'b' )<?/VAR>
3568  
3569 =item B<DEFAULT>
3570  
3571 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.
3572  
3573 Setting the DEFAULT parameter is only supported for scalar variables.
3574  
3575 You can use this feature to provide default values for input parameters this way.
3576  
3577 <?VAR NAME=$event DEFAULT="show">$event<?/VAR>
3578  
3579 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.
3580  
3581 <?PERL>
3582 $event ||= 'show';
3583 <?/PERL>
3584  
3585 =item B<NOQUOTE>
3586  
3587 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.
3588  
3589 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.
3590  
3591 This is an example of using NOQUOTE for an non string expression.
3592  
3593 <?VAR MY NAME=$element_cnt NOQUOTE>
3594 scalar(@liste)
3595 <?/VAR>
3596  
3597 =item B<MY>
3598  
3599 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.
3600  
3601 =back
3602  
3603 =head2 Example
3604  
3605 Please refer to the examples in the parameter sections above.
3606  
3607 =head1 COMMAND <?WHILE>
3608  
3609 =head2 Type
3610  
3611 Control Structure
3612  
3613 =head2 Syntax
3614  
3615 <?WHILE COND=condition >
3616 ...
3617 <?/WHILE>
3618  
3619 =head2 Description
3620  
3621 This realizes a loop, where the condition is checked first before entering the loop block.
3622  
3623 =head2 Parameter
3624  
3625 =over 8
3626  
3627 =item B<COND>
3628  
3629 As long as this Perl condition is true, the <?WHILE> block will be repeated.
3630  
3631 =back
3632  
3633 =head2 Example
3634  
3635 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.
3636  
3637 <TABLE>
3638 <?VAR MY NAME=$i>0<?/VAR>
3639 <?WHILE COND="$i++ < scalar(@lastname)">
3640 <TR>
3641 <TD>$lastname[$i]</TD>
3642 <TD>$firstname[$i]</TD>
3643 </TR>
3644 <?/WHILE>
3645 </TABLE>
3646  
3647 =for pdf-manual
3648  
3649 =head1 SEE ALSO
3650  
3651 CGI::CIPP (3pm), Apache::CIPP (3pm), new.spirit
3652  
3653 =head1 AUTHOR
3654  
3655 Jörn Reder <joern@dimedis.de>
3656  
3657 =head1 COPYRIGHT
3658  
3659 Copyright (C) 1997-2002 Jörn Reder, All Rights Reserved.
3660 Copyright (C) 1997-2002 dimedis GmbH, All Rights Reserved.
3661  
3662 This documentation is free; you can redistribute it
3663 and/or modify it under the same terms as Perl itself.