<MvCALL>

   Also See:   MvCALLCONTINUE MvCALLSTOP  

Report a language bug  |  Report a documentation error
Uses the HTTP/1.0 protocol to emulate a browser and contact a remote or local host. HTML, XML, and SGML pages can be requested from or posted to the remote serve. Page data is returned one tag at a time inside the <MvCALL> loop.
Syntax 
<MvCALL ACTION = "string: {  expression } | literal"
        METHOD = "GET|POST|HEAD|XML|RAW|OPTIONS|PUT|DELETE|TRACE|CONNECT"
        CONTENT-TYPE = "string: {  expression } | literal"
        FIELDS = "{ expression } | variable list"
        FILES = "{ expression } | literal"
        CERTFILE = "{ expression } | literal"
        CERTTYPE = "{ expression } | literal"
        CERTPASS = "{ expression } | literal"
        TIMEOUT = "{ expression } | literal"
        HEADERS = "{ expression } | literal">

        <MvCALLSTOP>
        <MvCALLCONTINUE> 
</MvCALL>
  • Closed Tag

Uses the HTTP/1.0 protocol to emulate a browser and contact a remote or local host. HTML, XML, and SGML pages can be requested from or posted to the remote serve. Page data is returned one tag at a time inside the <MvCALL> loop.

When <MvCALL> receives a document, it iterates once for each object (text or tag) that it receives. Several special variables (described below) are created to contain the data and the object properties.

NOTE: Additional documentation needs to be added for FILES, CERTFILE, CERTTYPE, TIMEOUT & HEADERS.

Attributes

  • ACTION: Required, specifies the fully qualified URL to be contacted, starting with http.
  • METHOD: Required GET | POST | HEAD | XML | RAW | OPTIONS | PUT | DELETE | TRACE | CONNECT. In most cases use GET for simple page  retrieval and use POST when when transmitting field data.
  • CONTENT-TYPE: Optional, attribute available when the METHOD is XML or RAW.
    If not specified and METHOD is XML, POST will have content type "text/xml."
    If not specified and METHOD is RAW, will have content type "text/plain.
    The values of the variables listed in the FIELDS attribute will then be passed in the header.
  • FIELDS: Optional, comma delimited list of variables value pairs sent to the URL when POST is used as the method.
  • FILES: Optional, contains variables whose values are filenames that will be uploaded to the URL specified  in ACTION.
  • CERTFILE: Optional, resolves to a location in the data directory containing a certificate or set of certificates.
  • CERTTYPE: Optional, must be either "PEM" or "ASN1".
  • CERTPASS: allows PEM-format certificates and/or private keys to be stored encrypted on disk. Ifspecified, the value of CERTPASS is used to decrypt the certificate and/or private key in the file specified by CERTFILE.
  • TIMEOUT: Optional, this value is used if it is smaller than the configured MvCONFIG_CALL_TIMEOUT value.
  • HEADERS: Optional, the value in this attribute will be placed after the Empresa-generated HTTP headers, but before the CRLF separating the HTTP headers and the body of the HTTP request.

The <MvCALL>...</MvCALL> loop terminates when the entire document has been received, or when an <MvCALLSTOP> (optional) is encountered. If <MvCALLCONTINUE> is encountered, processing start back at the top continuing with the next item.

The system variable s.miva_sslavailable will allow the programmer to determine if OpenSSL is available for use by MvCALL, otherwise <MvCALL> can not support the HTTPS (secure HTTP) protocol.

Requesting a Document

To request a document, set the ACTION attribute to the URL or IP address of the document and set the METHOD attribute to 'GET'. The FIELDS attribute is not required. This example loads external content from another web server into the variable l.return.

Example:

<MvCALL ACTION="http://www.content_server.com/incude/xfiles_cast.html" METHOD="GET">
    <MvASSIGN NAME = "l.return" VALUE = "{ l.return $ s.callvalue }">
</MvCALL>

Return Objects

<MvCALL> retrieves the document as a sequence of tags and text objects. <MvCALL> passes each object to the program one at a time within each loop Consider the following HTML code:

<P>When in <B>Rome</B> do as the <I>Romans</I> do.</P>

<MvCALL> will split this code into 11 object:

<P>
When in
<B>
Rome
</B>
do as the
<I>
Romans
</I>
do.
</P>

Object Properties

Each object returned will have different properties based on the type of object returned, tag or text. The properties are specified in system variables below.

In both cases these variables are returned:

  • s.callvalue: contains the value of the object.
  • s.callobjecttype: contains 'tag" of the value is a start or ending html tag, otherwise it will contain the value "text".

Use s.callobjecttype within the loop to decide how to process the object.

This example skips the tags and just returns the text.

Example:

<MvCALL ACTION = "g.url" METHOD = "GET">
    <MvIF EXPR = "{ s.callobjecttype EQ 'tag'}">
        <MvCALLCONTINUE>
    </MvIF>

    <MvASSIGN NAME = "l.text" VALUE = "{ l.text $ s.callvalue $ ' '}">
</MvCALL>

Text values returned in s.callvalue will contain the actual string of text and white space. Sequences of white space between tags (such as new lines, spaces, and tabs) will be preserved.

If the object type is 'tag' and tag is a start-tag, <MvCALL> then further separates the tag into attribute/value pairs.

If the object type is 'text' each of these will be set to null.

The following properties are available for each tag:

  • s.callvalue: the whole tag, including angle brackets, tag name, and any attributes and attribute values.
  • s.callobjectelement: the tag name, for example 'IMG' for an <IMG> tag, '/TABLE' for a </TABLE> tag.
  • s.callobjectnumattributes: the number of attributes specified for the tag.
  • s.callobjectattributeN: if attributes have been specified for the tag, variables callobjectattribute1, callobjectattribute2, ... will be created, containing the names of the attributes as they appear in sequence.
  • s.callobjectvalueN: if attributes have been specified for the tag, variables callobjectvalue1, callobjectvalue2, ... will be created, containing the values of the attributes as they appear in sequence.

The variables s.callobjectattributeN and s.callobjectvalueN are also available as arrays s.callobjectattribute[N] and s.callobjectvalue[N].

Consider the following example:

<IMG SRC="donkeys.gif" ALT="The Donkey Farm" HEIGHT="100" WIDTH="200">

<MvCALL> will set the following variables for this 'tag' object: Note: All values, string and numeric, are returned without quotes.

  • s.callvalue = the entire tag
  • s.callobjectelement = IMG
  • s.callobjectnumattributes = 4
  • s.callobjectattribute1 = SRC
  • s.callobjectvalue1 = donkeys.gif
  • s.callobjectattribute2 = ALT
  • s.callobjectvalue2 = The Donkey Farm
  • s.callobjectattribute3 = HEIGHT
  • s.callobjectvalue3 = 100
  • s.callobjectattribute4 = WIDTH
  • s.callobjectvalue4 = 200

Sometimes an attribute will be specified without an attribute name, as in:

<TABLE BORDER>

In this case, the attribute name and the attribute value are considered to be the same. In this example, callobjectattribute1 and callobjectvalue1 will each have the value BORDER.

This example retrieves all the image path location from a web page.

Example:

<MvCALL ACTION = "g.url" METHOD = "GET">
    <MvIF EXPR = "{ s.callobjecttype EQ 'tag' AND tolower(s.callobjectelement) = 'img'}">
        <MvASSIGN NAME="l.posn" VALUE="{ 1 }">
        <MvWHILE EXPR="{ l.posn LE s.callobjectnumattributes }">
            <MvIF EXPR="{ tolower(s.callobjectattribute[l.posn]) EQ 'src' }">
                <MvASSIGN NAME="l.ndx" VALUE="{ l.ndx + 1 }">
                <MvASSIGN NAME="images" INDEX="{ l.ndx }" VALUE="{ s.callobjectvalue[l.posn] }">
                <MvWHILESTOP>
            </MvIF>
            <MvASSIGN NAME="l.posn" VALUE="{ l.posn + 1 }">
        </MvWHILE>
    </MvIF>
</MvCALL>

Headers

When it retrieves a document, <MvCALL> also receives HTTP header information sent by the server. This information is stored in the following variables:

  • s.callnumberofheaders: contains the number of headers that have been retrieved. The number and content of headers depends on the server software that is serving the document. The value of callnumberofheaders will not change during the iterations of the <MvCALL> loop through a particular document.
  • s.callreturnheaderN: The headers received are placed into a separate variables callreturnheader1, callreturnheader2, and so forth. The values of these variables do not change during the iterations of the <MvCALL> loop through a particular document.

The variables s.callreturnheaderN is also available as arrays s.callreturnheader[N].

The following is an example of header data:

  • s.callnumberofheaders = 6
  • s.callreturnheader1 = HTTP/1.0 200 OK
  • s.callreturnheader2 = Date: Fri., 17 Jan 1997 01:23:24 GMT
  • s.callreturnheader3 = Server: Apache/1.1b0a
  • s.callreturnheader4 = Content-type: text/html
  • s.callreturnheader5 = Content-length: 390
  • s.callreturnheader6 = Last-modified: Thu, 16 Jan 1997 23:40:10 GMT

Limitations

  • <MvCALL> does not provide a true HTML, SGML, or XML parser, so it has some limitations:
  • It does not check whether a document is valid or well-formed
  • It does not resolve internal or external entities
  • It treats XML namespace prefixes a part of the tag (most of the time this is not a problem)

More Examples

Displaying a page from another website site will not resolve any relative links or images. One workaround for this is to put a <BASE> tag in the page being accessed, giving its absolute URL. Another is to put the appropriate <BASE> tag in the output stream that Miva sends to the browser:

Example:

<MvCALL ACTION="{ l.url }" METHOD="GET">
    <MvIF EXPR="{s.callobjecttype EQ 'tag' AND tolower(s.callobjectelement) EQ '/head'}">
        <MvEVAL EXPR="{ '<base href=' $ l.url_root $ ' />' }">
    </MvIF>

    <MvEVAL EXPR="{s.callvalue}">

</MvCALL>

This example retrieves a web page and displays the raw HTML source code.

Example:

<pre>
<MvCALL ACTION="{ l.url }" METHOD="GET">
     <MvEVAL EXPR="{ encodeentities(s.callvalue) }">
    </MvCALL>
</pre>

Submitting Data

There are two ways to use <MvCALL> to submit data to a CGI program on a server or to another MivaScript program on the same server. These are the GET and POST methods, and are used in the same way as with an HTML form. The receiving program may be written in another other web languages such as, PERL, PHP, ASP, JAVA which must know which method is being used and be set up to process data accordingly. Your calling program only needs to know what values to send and what method to use.

Using GET

Set the METHOD attribute to 'GET'. The URL specified by ACTION must have the data that is submitted, appended to the string. The data is separated from the URL by a '?' character, and consists of a sequence of 'name=value' pairs separated by ampersands, '&'.

For example:

http://www.my_isp.com/cgi-bin/prog1?animal1=fish&animal2=dinosaur

If the data contains any special characters, such as space, '=', '~', '&', and '+', each field must be URL-encoded. Use the encodeattribute() function to encode each value. The submitted data will be available to the receiving program via the QUERY_STRING CGI environment variable.

Here is an example using GET. Notice in the first example, the URL string is formatted exactly like the href attribute in a link. With GET, you can also use the value list syntax for passing arguments to a program: as show in the second example.

Example:

<MvCALL ACTION="http://www.my_isp.com/cgi-bin/prog1?animal1=fish&animal2=dinosaur"
        METHOD="GET">
... process return values ...
</MvCALL>

OR

<MvCALL ACTION="http://www.my_isp.com/prog3.mv?fish+dinosaur"
        METHOD="GET">
...
</MvCALL>

This first method operate exactly like a link in a web page. <a href="http://www.my_isp.com/cgi-bin/prog1?animal1=fish&animal2=dinosaur">Chick here</a>

Using POST

If you use the POST method to submit data, the data is not sent to the server appended to the URL, but rather in the HTTP headers. The format in which the data is received is the same as when GET is used. That is, a sequence of 'name=value' pairs separated by ampersands, '&'. For most application the POST method is preferred.

Instead of obtaining the data from the QUERY_STRING variable, the program receiving the data must read it from its standard input.

To use this method, set the METHOD attribute of <MvCALL> to 'POST'. The FIELDS attribute should comma delimited contain a list of variables whose names, together with their values, are sent to the URL specified with the ACTION attribute.

This example perform the same post but transmits the field variables directly instead of embedding them within the URL. As explained above use the s.callvalue variable to evaluate the response from the server. This very basic code simply displays the document that the CGI program sends back.

Example:

<MvASSIGN NAME="l.animal1" VALUE="fish">
<MvASSIGN NAME="l.animal2" VALUE="dinosaur">

<MvCALL ACTION="http://www.my_isp.com/cgi-bin/prog2"
        METHOD="POST"
        FIELDS="l.animal1,l.animal2">
    ... process the response ---
    <MvEVAL EXPR="{s.callvalue}">
</MvCALL>

Running System Commands

Miva adheres to the principle of 'site sandboxing', which means that it will not interfere with the server or other users on the server. For this reason Miva Script does not allow system commands (such as UNIX shell commands) to be run directly from Miva. If you need to run system commands, you may be able to write a CGI program (using PHP, PERL, shell, or another language) that can execute system commands, and use <MvCALL> to call that CGI program.

+ Add a note
User Annotations: MvCALL