MvCALL#

MvCALL uses the HTTP/1.1 protocol to emulate a browser and contact a remote or local host. HTML, XML, SGML and others pages can be requested from or posted to the remote server. 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 available to contain the returned data and the object properties.

Syntax

<MvCALL ACTION = "string: {  expression } | literal"
        METHOD = "GET|POST|HEAD|XML|RAW|OPTIONS|PUT|DELETE|TRACE|CONNECT|PATCH|LINK|UNLINK"
        CONTENT-TYPE = "string: {  expression } | literal"
        FIELDS = "{ expression } | variable list"
        FILES = "{ expression } | literal"
        CERTFILE = "{ expression } | literal"
        CERTTYPE = "{ expression } | literal"
        CERTPASS = "{ expression } | literal"
        CERTVALUE = "{ expression } | literal"
        TIMEOUT = "{ expression } | literal"
        HEADERS = "{ expression } | literal"
        FLAGS = "noparse">

        <MvCALLSTOP>
        <MvCALLCONTINUE>

</MvCALL>

Attributes#

Attribute	Description
`ACTION`	(Required) Specifies the fully qualified URL to be contacted, starting with `http`.
`METHOD`	(Required) One of: `GET`, `POST`, `HEAD`, `XML`, `RAW`, `OPTIONS`, `PUT`, `DELETE`, `TRACE`, `CONNECT`, `PATCH`, `LINK`, `UNLINK`. In most cases, use `GET` for simple page retrieval and `POST` when transmitting field data.
`CONTENT-TYPE`	(Optional) Used when `METHOD` is `XML`, `RAW`, or `POST` (v5.32+). • If not specified and `METHOD` is `XML` or `POST`, defaults to `text/xml`. • If not specified and `METHOD` is `RAW`, defaults to `text/plain`. • When posting JSON (`POST` + `application/json`), the POSTed data is parsed into `s.json_data` (JSON object) and raw into `s.content_data`.
`FIELDS`	(Optional) Comma-delimited list of variable/value pairs sent in the request body when using `POST`.
`FILES`	(Optional) Comma-delimited list of variables whose values are filenames (relative to the data directory) to upload. `METHOD` must be `POST` or `PUT`.
`CERTFILE`	(Optional) Path (under data directory) to a certificate or bundle.
`CERTTYPE`	(Optional) Either `PEM` or `ASN1`.
`CERTPASS`	(Optional) Passphrase to decrypt encrypted PEM files.
`CERTVALUE`	(Optional) Include a certificate directly in code instead of via `CERTFILE`.
`TIMEOUT`	(Optional) Overrides `MvCONFIG_CALL_TIMEOUT` if smaller.
`HEADERS`	(Optional) Raw header text appended after auto-generated headers but before the request body.
`FLAGS`	(Optional) `"noparse"` disables parsing of returned data; all content goes into `s.callvalue`.

The <MvCALL>…</MvCALL> loop terminates when the entire document has been received or when an <MvCALLSTOP> is encountered. <MvCALLCONTINUE> skips to the next iteration.

The system variable s.miva_sslavailable indicates if HTTPS (OpenSSL) is supported.

Methods#

HTTP (RFC 2616) defines methods to indicate the desired action on the resource. MivaScript supports all standard methods plus newer ones:

GET: Retrieve data. Query parameters appended to ACTION as ?name=value&….
POST: Send data in the request body (FIELDS). Often used for form submission.
HEAD: Same as GET but without the response body. Useful for headers only.
XML: POST with XML payload; see CONTENT-TYPE.
RAW: Send FIELDS content unformatted (no names, =, &). Defaults to text/plain.
OPTIONS: Query server-supported methods.
PUT: Store enclosed entity under the URI; create or replace.
DELETE: Remove the specified resource.
TRACE: Echo back the received request for debugging.
CONNECT: Establish a tunnel (e.g., HTTPS through proxy).
PATCH: Apply partial modifications.
LINK / UNLINK: Manage relationships between resources.

Requesting a Document#

Load a document via GET

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

<MvEVAL EXPR="{ l.return }">

Test URL validity without fatal errors

<MIVA MvCALL_ERROR="nonfatal, nodisplay">
  <MvCALL METHOD="GET" ACTION="{ l.url }" FLAGS="noparse"></MvCALL>
<MIVA MvCALL_ERROR="fatal, display">

<MvIF EXPR="{ g.MvCALL_Error }">
   <MvFUNCTIONRETURN VALUE="{ Error('Invalid url.', g.MvCALL_Error) }">
</MvIF>

Return Objects#

<MvCALL> splits the document into text and tag objects. For example, When in Rome do as the Romans do. yields:


When in

Rome

do as the

Romans

do.

Object Properties#

For each object, these variables are set:

s.callvalue – the raw tag or text.
s.callobjecttype – "tag" if a tag, else "text".

When s.callobjecttype is "tag", additional tag properties are set:

s.callobjectelement – tag name (e.g., IMG, /TABLE).
s.callobjectnumattributes – number of attributes.
s.callobjectattributeN – name of the Nth attribute.
s.callobjectvalueN – value of the Nth attribute.

Attributes also available as arrays: s.callobjectattribute[N], s.callobjectvalue[N].

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

s.callvalue                = <IMG SRC="donkeys.gif" ALT="The Donkey Farm" HEIGHT="100" WIDTH="200">
s.callobjectelement        = IMG
s.callobjectnumattributes  = 4
s.callobjectattribute1     = SRC
s.callobjectvalue1         = donkeys.gif
… etc.

If an attribute appears without a value (e.g., <TABLE BORDER>), its name and value are identical.

Extracting Image URLs

<MvCALL ACTION="{ g.url }" METHOD="GET">
  <MvIF EXPR="{ s.callobjecttype EQ 'tag' AND tolower(s.callobjectelement) EQ '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#

HTTP response headers are stored in:

s.callnumberofheaders – number of headers.
s.callreturnheaderN – the Nth header line.

Also available as s.callreturnheader[N].

Example:

s.callnumberofheaders = 6
s.callreturnheader1   = HTTP/1.0 200 OK
s.callreturnheader2   = Date: Fri., 17 Jan 1997 01:23:24 GMT
… etc.

Limitations#

Does not validate well-formed HTML/SGML/XML.
Does not resolve entities.
Treats namespace prefixes as part of tag names.

Submitting Data#

There are two primary ways to submit data via MvCALL: GET and POST. The receiving program (CGI, PERL, PHP, ASP, JAVA, MivaScript) must handle the chosen method.

Using GET#

Data appended to ACTION as query string: ?name=value&…. Encode special characters with encodeattribute().

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

Or value-list syntax:

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

Using POST#

Data sent in the HTTP body via FIELDS

<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">
    <MvEVAL EXPR="{ s.callvalue }">
</MvCALL>

Using RAW#

Transmit unformatted data (no names or separators); defaults to text/plain unless overridden:

<MvCAPTURE VARIABLE="l.json" STANDARDOUTPUTLEVEL="text, compresswhitespace">
{
  "contacts": [
    { "email": "something@example.com", "first_name": "John", "last_name": "Doe" },
    …
  ]
}
</MvCAPTURE>

<MvCALL METHOD="RAW"
        ACTION="https://some.example.com/api/"
        CONTENT-TYPE="application/json"
        HEADERS="{ 'Authorization: xxxxxxx' $ asciichar(13) $ asciichar(10) }"
        FIELDS="l.json">
  <MvEVAL EXPR="{ s.callvalue }">
</MvCALL>

Running System Commands#

MivaScript does not permit direct system commands for security (sandboxing). To run shell commands, create an external CGI program (PHP, PERL, shell, etc.) and invoke it via <MvCALL>.

Examples#

Inject correct relative URLs tag

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

Display raw HTML source

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

Tip

Many more examples can be found by downloading the FREE Miva Merchant Limited Source Kit (LSK) and searching the .mv files for “MvCALL”.