File Uploading#

Miva Script supports two forms of file uploading: sending a file from one host to another, and receiving a file from an end-user. The Empresa engine can also receive the files and provides two callbacks to your Miva Script programs to process the uploaded files.

Transmitting Files via HTTP#

Sending a file via MvCALL#

Send the files whose names are given by filevar1,filevar2,... (relative to the Miva data directory) to the host and script specified by ACTION, where the upload will be processed by the specified script.

<MvCALL ACTION="http://www.recipient.com/uploadscript.mvc"
        METHOD="POST"
        FILES="filevar1,filevar2,...">

The FILES attribute specifies a list of one or more variables whose values are the names of files to be uploaded; these filenames must be relative to your Miva data directory. The METHOD must be POST or PUT, which will generally be implemented as POST.

The files are uploaded to the server specified by ACTION, but the results depend on how the specified script processes the data it receives. Miva Script programs processing the upload must contain two user-defined functions, Miva_ValidateFileUpload() and Miva_ProcessFileUpload(), described below. Both functions will be called by Empresa once for each uploaded file saved as temporary files. Each file can be skipped, uploaded in entirety or partially, saved, or deleted without saving.

You can also send data to the recipient script using the FIELDS attribute of <MvCALL> at the same time that you send the file(s).

Sending a file via a FORM#

This form enables an end-user to choose a file on the local machine and send it to the host and script specified by ACTION, where the upload will be processed by the specified script.

<form ACTION="http://www.recipient.com/uploadscript.mvc"
      METHOD="POST"
      ENCTYPE="multipart/form-data">
  <input TYPE="FILE" NAME="some_name">
  <input TYPE="SUBMIT">
</form>

The METHOD must be POST (or PUT), and the ENCTYPE attribute must be multipart/form-data. The <input TYPE="FILE"> element creates a form field for file selection. When the form is submitted, the file is uploaded to the server specified by ACTION, but the processing depends on the server-side script’s implementation, which must define Miva_ValidateFileUpload() and Miva_ProcessFileUpload() as described below.

Tip

For this kind of upload, the field parameter (the first argument passed to Miva_ValidateFileUpload() and Miva_ProcessFileUpload()) is the NAME of the <input> element used to select the file.

Receiving Files#

Files can be uploaded to any CGI script that supports file upload. If the receiving script is a Miva Script program, it must contain two user-defined functions: one to validate the upload and one to process the uploaded file. If either function is missing or has the wrong parameters, the upload will fail.

Required Functions#

<MvFUNCTION NAME="Miva_ValidateFileUpload"
            PARAMETERS="field, filename, content_type">

<MvFUNCTION NAME="Miva_ProcessFileUpload"
            PARAMETERS="field,filename,status,tempfile,content_type,size">

Validate the Upload#

The recipient script must define this function, which Empresa calls automatically to validate each file:

<MvFUNCTION NAME="Miva_ValidateFileUpload"
            PARAMETERS="field, filename, content_type">
    ... validation code ...
    <MvFUNCRETURN VALUE="{ return_code }">
</MvFUNCTION>

Parameters:

field: The Miva variable (field name) containing the filename
filename: The filename value itself
content_type: The MIME type of the file on the uploading server

Return values:

-1: Skip this file — don’t upload it at all
0: Upload the whole file, no matter how long it is
Any positive integer N: Upload only the first N bytes of the file

Skip GIF images

<MvIF EXPR="{ content_type EQ 'image/gif' }">
    <MvFUNCRETURN VALUE="-1">
<MvELSE>
    <MvFUNCRETURN VALUE="0">
</MvIF>

Processing the Upload#

The recipient script must also define this function, which Empresa calls automatically after validation to process each uploaded file:

<MvFUNCTION NAME="Miva_ProcessFileUpload"
            PARAMETERS="field, filename, status, tempfile, content_type, size">
    ... processing code ...
</MvFUNCTION>

Parameters:

field: The Miva variable (field name) containing the filename
filename: The filename value itself
status: Upload status (SKIPPED, COMPLETE, or PARTIAL)
tempfile: Path to a temporary file where the upload is stored (deleted once the function ends)
content_type: The MIME type of the file on the uploading server
size: The size of the original file (un-truncated)

Within this function, you typically copy the temporary file to a permanent location. For example:

<MvASSIGN NAME="save_it"
          VALUE="{ frename(tempfile, permfile) }">

Make sure to delete any temporary files if your server does not remove them automatically.

Complete Example#

Below is a minimum script that validates and saves an uploaded file:

<MvFUNCTION NAME="Miva_ValidateFileUpload"
            PARAMETERS="field,filename,content_type">
    <MvIF EXPR="{ len(l.filename) AND (l.filename GT '') }">
        <MvFUNCRETURN VALUE="{ 0 }">
    <MvELSE>
        <MvASSIGN NAME="g.message"
                  VALUE="{ g.message $ 'You must specify a file name.' }">
        <MvFUNCRETURN VALUE="{ -1 }">
    </MvIF>
</MvFUNCTION>

<MvFUNCTION NAME="Miva_ProcessFileUpload"
            PARAMETERS="field, filename, status, tempfile, content_type, size">
    <MvCOMMENT>Replace every backslash with a pipe</MvCOMMENT>
    <MvASSIGN NAME="l.oldfilename"
              VALUE="{ glosub(glosub(l.filename, '\\', '|'),' ','_') }">

    <MvCOMMENT>Calculate how many pipe-delimited tokens exist.</MvCOMMENT>
    <MvASSIGN NAME="l.tokencount"
              VALUE="{ (len(l.oldfilename)-len(glosub(l.oldfilename,'|','')))+1 }">

    <MvCOMMENT>The last token is the filename.</MvCOMMENT>
    <MvASSIGN NAME="l.newfilename"
              VALUE="{ gettoken(l.oldfilename,'|',l.tokencount) }">

    <MvASSIGN NAME="l.ok"
              VALUE="{ fcopy(l.tempfile, l.newfilename) }">
</MvFUNCTION>