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 call two call backs to your Miva Script programs to process the uploaded files.

Transmitting Files via HTTP

Sending a file via MvCALL

Send the files whose name 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 of the upload process 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 in more detail below. Both functions will be called by Empresa once for each uploaded file saved as temporary files. Each file can be skipped, upload entirety or partially, saved, or allow it to be deleted without saving. You may perform any other desired processing within these functions.

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) to be uploaded.

Sending a file via a FORM

This form enables an end-user to choose a file on the local network 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, which will generally be implemented as POST), and the ENCTYPE attribute must be set to 'multipart/form-data'. The <INPUT TYPE="FILE"> element creates a form object.

The user browsing a page containing this object can use it to enter or choose a file on the local network. When the form is submitted, the file is uploaded to the server specified by the ACTION, but the results of the upload process depend on how the specified script (uploadscript.mv in this example) processes the data it receives. This script must contain definitions for the two functions Miva_ValidateFileUpload() and Miva_ProcessFileUpload() described below; both of these functions will be called once for each uploaded file, and can skip the file, upload it in its entirety, or upload it partially, and then can save the file, allow it to be deleted without saving, and perform any other desired processing.

Note: For this kind of upload, the field parameter (the first argument passed to Miva_ValidateFileUpload() and Miva_ProcessFileUpload()) is the NAME of the <INPUT> object used to specify the file.

In general, browsers do not permit files specified with http://-style URLs to be uploaded using this method. Instead, local network drive paths (such as c:\...) should be specified. Some browsers do not allow a default VALUE for <INPUT TYPE="FILE"> fields.

Receiving Files

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

These functions are required in your receiving program: Note: The specific parameter names used here are arbitrary.

<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 Miva Script program must contain the following function which will be called by Empresa to validate the upload:

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

This function will be called automatically by Empresa (you do not need an explicit call to this function). It will be called with three arguments, The Empresa variable (field name) containing the filename, the filename value itself, and the MIME type (content_type) of the file on the uploading server. The actions of this function can be whatever you want, but the function must eventually return one of three values:

Note: The field parameter (the first argument passed to Miva_ValidateFileUpload() and Miva_ProcessFileUpload() is the name of the variable containing the filename.

• -1: skip this file--don't upload it at all.
• 0 (zero): upload the whole file, no matter how long it is.
• Any positive integer N: upload only the first N bytes of the file.

How you arrive at this return value is up to you: for example, if you want to upload all files in their entirety, the body of the function could consist of only:

<MvFUNCRETURN VALUE="0">

This example skips GIF images but upload all other files:

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

To upload only up to 1000 bytes of any file:

<MvFUNCRETURN VALUE="1000">

Processing the Upload:

The recipient script must contain the following function, which processes the upload:  Note: The specific parameter names used here are arbitrary.

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


</MvFUNCTION>

This function will be called automatically by Empresa (you do not need an explicitly call to this function).

• The Miva variable (field name) containing the filename.
• The filename value itself.
• The upload status: this will be one of the strings 'SKIPPED', 'COMPLETE', or 'PARTIAL', and indicates whether the file was skipped (not uploaded at all), uploaded completely, or partially uploaded.
• A temporary file (temp_file) where the uploaded file will be stored. This file will be deleted as soon as Miva_ProcessFileUpload() terminates.
• The MIME type (content_type) of the file, on the uploading server.
• The size of the original file (un-truncated)

The actions of this function can be whatever you want, but probably the most important thing you would do in this function would be to make a copy of the temporary file (temp_file). For example:

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

Make sure the tempfiles are deleted. Since some servers do not remove their temp files, make sure you delete the temp files, where present.

These two examples show minimum scripts to receive and save 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>