<!--
 -  
 -  This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
 -  project.
 -  
 -  Copyright (C) 1998-2018 OpenLink Software
 -  
 -  This project is free software; you can redistribute it and/or modify it
 -  under the terms of the GNU General Public License as published by the
 -  Free Software Foundation; only version 2 of the License, dated June 1991.
 -  
 -  This program is distributed in the hope that it will be useful, but
 -  WITHOUT ANY WARRANTY; without even the implied warranty of
 -  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 -  General Public License for more details.
 -  
 -  You should have received a copy of the GNU General Public License along
 -  with this program; if not, write to the Free Software Foundation, Inc.,
 -  51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 -  
 -  
-->
<?xml version="1.0" encoding="ISO-8859-1"?>
<refentry id="VS-B-3">
  <refmeta>
    <refentrytitle>Basic VSP Programming</refentrytitle>
    <refmiscinfo>tutorial</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>Accessing Data in the Request</refname>
    <refpurpose>How to access form data.</refpurpose>
  </refnamediv>

<refsect1 id="VS-B-3a">
<title>Preliminaries</title>
<itemizedlist mark="bullet">
    <listitem>Data supplied to a VSP is normally posted from a form.</listitem>
    <listitem>Pressing a form submit button causes the browser to pass the data to the server.</listitem>
    <listitem>The form data may be encoded in two forms: www-url-encoded or multipart/form-data.</listitem>
</itemizedlist>
</refsect1>

<refsect1 id="VS-B-3b">
<title>Processing of the form data in VSPs.</title>
<itemizedlist mark="bullet">
  <listitem><para>When the request arrives, the web server parses the request and creates three input arguments for VSP processing:</para>
  <orderedlist>
    <listitem>path - array with path elements of the requested URL path. Ie. if the request is "http://foo.bar/a/b/c" then "path" argument will be a vector ('a','b','c').</listitem>
    <listitem>params - array with name and value pairs of the passed form parameters</listitem>
    <listitem>lines - the vector of HTTP request header lines</listitem>
  </orderedlist></listitem>
  <listitem>The form data is held in the "params" argument.</listitem>
  <listitem><para>The value of a named parameter can be extracted from the "params" array in two ways:</para>
    <orderedlist>
      <listitem><para>Using the get_keyword function:</para>
         <programlisting>declare x varchar;
x := get_keyword('fieldname', params, 'default value');</programlisting></listitem>
      <listitem><para>Using the {?'variable_name'} VSP shortcut.</para>
         <programlisting>x := {?'fieldname'};</programlisting></listitem>
    </orderedlist></listitem>
</itemizedlist>
</refsect1>

<refsect1 id="VS-B-3c">
<title>Form example - A Simple Calculator.</title>
<para>The user can enter two numbers, and choose a desired operation.
Pressing the "=" button causes the form to be sent to the server. The VSP execution will show the result of
the calculation. This example uses the get_keyword function to retrieve the parameters.</para>
</refsect1>

<refsect1 id="VS-B-3d">
<title>Form example - Insert table data</title>
<para>The second example demonstrates inserting the user entered form data into a table.
This example uses the {?''} shortcuts for accessing the form data. The data in the table will be shown
below the form, ordered by date. You must run the sample SQL first to create the table.</para>
</refsect1>

<refsect1 id="VS-B-3e">
<title>Note</title>
<para>Note that both examples do not handle the SQL errors.
The handling of SQL errors in VSPs will be described in section "VS-B-6".
</para>
</refsect1>
</refentry>