CIPP

 view release on metacpan or  search on metacpan

lib/CIPP/Manual.pm  view on Meta::CPAN

=over 8

=item <?CATCH>

Execution of a block if a particular exception was thrown in a preceding TRY block.

=item <?LOG>

Write a entry in a logfile.

=item <?THROW>

Explicite creation of an exception.

=item <?TRY>

Secured execution of a block. Any exceptions thrown in the encapsulated block are caught.

=back

=head2 SQL

=over 8

=item <?AUTOCOMMIT>

Control of transaction behaviour

=item <?COMMIT>

Commit a transaction

=item <?DBQUOTE>

Quoting of a variable for usage in a SQL statement

=item <?GETDBHANDLE>

Returns the internal DBI database handle

=item <?ROLLBACK>

Rollback a transaction

=item <?SQL>

Execution of a SQL statement

=back

=head2 URL- and Form Handling

=over 8

=item <?GETURL>

Creation of a CIPP object URL

=item <?HIDDENFIELDS>

Producing a number of hidden formular fields

=item <?HTMLQUOTE>

HTML encoding of a variable

=item <?URLENCODE>

URL encoding of a variable

=back

=head2 HTML Tag Replacements

=over 8

=item <?A>

Replaces <A> tag

=item <?FORM>

Replaces <FORM> tag

=item <?FRAME>

Replaces <FRAME> tag

=item <?IMG>

Replaces <IMG> tag

=item <?INPUT>

Replaces <INPUT> tag, with sticky feature

=item <?OPTION>

Replaces <OPTION> tag, with sticky feature

=item <?SELECT>

Replaces <SELECT> Tag, with sticky feature

=item <?TEXTAREA>

Replaces <TEXTAREA> tag

=back

=head2 Interface

=over 8

=item <?GETPARAM>

Recieving a non declared CGI input parameter

=item <?GETPARAMLIST>

Returns a list of all CGI input parameter names

lib/CIPP/Manual.pm  view on Meta::CPAN

=item B<COND>

Takes the Perl condition.

=back

=head2 Example

Larry and Linus get personal greeting messages:

  <?IF COND="$name eq 'Larry'">
    Hi Larry, you're welcome!
  <?ELSIF COND="$name eq 'Linus'">
    Hi Linus, you're velkomma!
  <?ELSE>
    Hi Stranger!
  <?/IF>

=head1 COMMAND <?EXIT>

=head2 Type

Control Structure

=head2 Syntax

 <?EXIT>

=head2 Description

<?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 nec...

=head2 Note

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. 

=head2 Example

Exit the program if the user doesn't know the preconfigured secret:

  <?INTERFACE INPUT="$secret">

  <?IF COND="$secret ne $conf::the_ultimate_secret">
    <p>
    You don't know the secret. Go away!
    </p>
    <?EXIT>
  <?/IF>

  You're welcome, secret keeper!

=head1 COMMAND <?FETCHUPLOAD>

=head2 Type

Interface

=head2 Syntax

 <?FETCHUPLOAD FILENAME=server_side_filename
               VAR=upload_formular_variable
             [ THROW=exception ] >

=head2 Description

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.

=head2 Parameter

=over 8

=item B<FILENAME>

This is the fully qualified filename where the file should be stored.

=item B<VAR>

This is the variable which holds the value of the correspondent HTML file upload field (mostly declared with <?INTERFACE> or fetched with <?GETPARAM>).

=item B<THROW>

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".

=back

=head2 Note

The client side file upload will only function proper if you set the encoding type of the HTML form to ENCTYPE="multipart/form-data". Otherwise you will get a exception, that the file could not be fetched.

There is another quirk you should notice. The variable which corresponds to the <INPUT NAME> option in the file upload form is a GLOB reference (due to the internal implementation of the CGI module, which CIPP uses). That means, if you use that varia...

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) com...

The solution is to create a new variable assigned from the value of the file upload variable enforced to be in string context using double quotes.

  <?INTERFACE INPUT="$upfilename">
  <?MY $client_filename>
  <?PERL> $client_filename = "$upfilename" <?/PERL>

=head2 Example

First we provide a HTML form with the file upload field.

  <?FORM METHOD="POST" ACTION="/image/save.cgi"
         ENCTYPE="multipart/form-data">

  Fileupload:
  <INPUT TYPE=FILE NAME="upfilename" SIZE=45>
  <P>
  <INPUT TYPE="reset">
  <INPUT TYPE="submit" NAME="submit" VALUE="Upload">

  <?/FORM>

The /image/save.cgi program has the following code to store the file in the filesystem.

  <?FETCHUPLOAD FILENAME="/tmp/upload.tmp"
                VAR="upfilename"
                THROW=my_upload>

=head1 COMMAND <?FOREACH>

lib/CIPP/Manual.pm  view on Meta::CPAN

=head2 Type

SQL

=head2 Syntax

 <?ROLLBACK [ DB=database_name ]
            [ DBH=database_handle ]
            [ THROW=exception ] >

=head2 Description

The <?ROLLBACK> command concludes the actual transaction and cancels all changes to the database.

Using <?ROLLBACK> in <?AUTOCOMMIT ON> mode is not possible and will result in a runtime exception.

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.

=head2 Parameter

=over 8

=item B<DB>

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 ...

If DB is ommited the project default database is used.

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.

=item B<DBH>

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.

=item B<THROW>

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.

If the underlying database is not capable of transactions (e.g. MySQL) execution of this command will throw an exception.

=back

=head2 Example

We insert a row into a database table and rollback the change immediately. We throw a user defined exeption, if the rollback fails, maybe the database is not capable of transactions.

  <?SQL SQL="insert into foo (num, str)
             values (42, 'bar');">
  <?/SQL>
  <?ROLLBACK THROW="ROLLBACK_Exception">

=head1 COMMAND <?SAVEFILE>

=head2 Type

Interface

=head2 Syntax

 <?SAVEFILE FILENAME=server_side_filename
            VAR=upload_formular_variable
            [ SYMBOLIC ]
            [ THROW=exception ] >

=head2 Description

This command is deprecated. Use <?FETCHUPLOAD> instead.

This command saves a file which was uploaded by a client in the webservers filesystem.

=head2 Parameter

=over 8

=item B<FILENAME>

This is the fully qualified filename where the file will be stored.

=item B<VAR>

This is the identifier you used in the HTML form for the filename on client side, the value of the <INPUT NAME> parameter) .

=item B<SYMBOLIC>

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.

=item B<THROW>

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.

=back

=head2 Note

The client side file upload will only function proper if you set the encoding type of the HTML form to ENCTYPE="multipart/form-data". Otherwise you will get a exception, that the file could not be fetched.

There is another quirk you should notice. The variable which corresponds to the <INPUT NAME> option in the file upload form is a GLOB reference (due to the internal implementation of the CGI module, which CIPP uses). That means, if you use that varia...

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) com...

The solution is to create a new variable assigned from the value of the file upload variable enforced to be in string context using double quotes.

<?INTERFACE INPUT="$upfilename">

<?MY $client_filename>

<?PERL> $client_filename = "$upfilename" <?/PERL>

=head2 Example

First we provide a HTML form with the file upload field.

  <?FORM METHOD="POST" ACTION="/image/save.cgi"
         ENCTYPE="multipart/form-data">
Fileupload:

  <INPUT TYPE=FILE NAME="upfilename" SIZE=45><BR>
  <INPUT TYPE="reset">
  <INPUT TYPE="submit" NAME="submit" VALUE="Upload">
  </FORM>

The /image/save.cgi program has the following code to store the file in the filesystem.

  <?SAVEFILE FILENAME="/tmp/upload.tmp"
             VAR="upfilename"
             THROW=my_upload>

The same procedure using the RUNTIME parameter.

  <?VAR MY=$field_name>upfilename<?/VAR>
  <?SAVEFILE FILENAME="/tmp/upload.tmp"
             SYMBOLIC
             VAR="$field_name"
             THROW=upload>

=head1 COMMAND <?SELECT>

=head2 Type

HTML Tag Replacement

=head2 Syntax

 <?SELECT [ NAME=parameter_name ]
          [ MULTIPLE ] [ STICKY ]
          [ additional_<SELECT>_parameters ... ] >
 ...
 <?/SELECT>
 

=head2 Description

This command generates a selection widget providing preservation of the selection state (similar to the STICKY feature of the <?INPUT> command).

=head2 Parameter

=over 8

=item B<NAME>

The name of the formular widget.

=item B<MULTIPLE>

If this is set, a multi selection list will be generated, instead of a single selection popup widget.

=item B<STICKY>

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...

=item B<additional_SELECT_parameters>

All additional parameters are taken over without changes into the produced <SELECT> tag.

=back

=head2 Note

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 ...

=head2 Example

This is a complete CIPP program, which provides a mulitple selection list and preservers its state over subsequent executions of the program.

  <?INCINTERFACE OPTIONAL="@list">

  <?FORM ACTION="sticky.cgi">

  <?SELECT NAME="list" MULTIPLE STICKY>
  <?OPTION VALUE="1">value 1<?/OPTION>
  <?OPTION VALUE="2">value 2<?/OPTION>
  <?OPTION VALUE="3">value 3<?/OPTION>
  <?/SELECT>

  <?INPUT TYPE="submit" VALUE="send">

  <?/FORM>

=head1 COMMAND <?SQL>

=head2 Type

SQL

=head2 Syntax

 <?SQL SQL=sql_statement
       [ VAR=list_of_variables_for_the_result ]
       [ PARAMS=input_parameter ]
       [ WINSTART=start_row ]
       [ WINSIZE=number_of_rows_to_fetch ]
       [ COND=fetch_condition ]
       [ RESULT=sql_return_code ]
       [ DB=database_name ]
       [ DBH=database_handle ]
       [ THROW=exception ]
       [ MY ]
       [ PROFILE=profile_label ] >
 ...
 <?/SQL>