<MvCALL>

August 2017 -- Added new section named Methods:
This new section will try to clarify and expand on all the new methods added over the last few years. A few more examples have been added as well. PLEASE, post your own examples in the User Annotations section at the bottom of this page.

IMPORTANT: Many more examples can be found by downloading the FREE Miva Merchant Limited Source Kit (LSK) and searching the .mv files for "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 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 available to contain the returned data and the object properties.

Attributes

• ACTION: Required, specifies the fully qualified URL to be contacted, starting with http.
• METHOD: Required "GET | POST | HEAD | XML | RAW | OPTIONS | PUT | DELETE | DELETE | TRACE | CONNECT | PATCH | LINK | UNLINK". 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, RAW  or POST (v 5.32 see below)
  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.
  POST content type of "application/json" supported as of v5.32. The POSTed data will be parsed and stored in the s.json_data variable as a JSON object. The raw POSTed data will populate the s.content_data variable.
• 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. The specified METHOD must be 'POST' or 'PUT'.
• 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. If specified, the value of CERTPASS is used to decrypt the certificate and/or private key in the file specified by CERTFILE.
• CERTVALUE: allow inclusion of a certificate directly in the code, as opposed to being the contents of a file pointed to by the CERTFILE attribute.
• 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.
• FLAGS: Optional, "noparse" which will disable parsing of the returned data. The data will populate the s.callvalue variable. This is ideal if you do not need to iterate HTML / XML elements.

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

Methods

HTTP (Hypertext Transfer Protocol) defines methods to indicate the desired action to be performed on the identified resource. What this resource represents, whether pre-existing data or data that is generated dynamically, depends on the implementation of the server. Often, the resource corresponds to a file or the output of an executable residing on the server. All general-purpose HTTP servers are required to implement at least the GET and HEAD methods, and, whenever possible, also the OPTIONS method.

The HTTP/1.0 specification defined the GET, POST and HEAD methods. The HTTP/1.1 specification added 5 new methods: OPTIONS, PUT, DELETE, TRACE and CONNECT. By being specified in these documents their semantics are well known and can be depended on. Any client can use any method and the server can be configured to support any combination of methods. If a method is unknown to an intermediate it will be treated as an unsafe and non-idempotent method.

There is no limit to the number of HTTP methods that can be defined and this allows for future methods to be specified without breaking existing infrastructure. Miva Script now supports the PATCH method and the LINK and UNLINK methods.

• GET: This method requests a representation of the specified resource. Requests using GET should only retrieve data and should have no other effect. This is the same as clicking a normal link in a web browser or using a form method="GET". In MvCALL, variables are transmitted as part of the ACTION URI as &varname=varvalue pairs.
• POST: The POST method requests that a web server identified by the URI accept the data enclosed in the body of the request message. It is most often used when submitting a completed web form. In MvCALL the POST method is associated with FIELDS variables that contain variable/value pairs.
• HEAD: The HEAD method asks for a response identical to that of a GET request, but without the response body. This is useful for retrieving meta-information written in response headers, without having to transport the entire content. The head method is often used for testing hyperlinks, accessibility and for determining if a document has been recently modifed.
• XML: Allows XML formatted data to be transmitted within the FIELDS variable. Examples can be found in the file named pay_ut.mv Limited Source Kit. Also see the CONTENT-TYPE attribute.
• RAW: IN MvCALL, METHOD = "RAW" takes the values of the FIELDS, and transmits data without any names, equal signs, or ampersands. Unless specified in the CONTENT-TYPE attribute, data is transmitted as text/plain.
• OPTIONS: This method returns the HTTP methods that the server supports for the specified URL. This can be used to check the functionality of a web server by requesting '*' instead of a specific resource.
• PUT: The PUT method requests that the enclosed entity be stored under the supplied URI. If the URI refers to an already existing resource, it is modified; if the URI does not point to an existing resource, then the server can create the resource with that URI.
• DELETE: The DELETE method deletes the specified resource.
• TRACE: The TRACE method echoes the received request so that a client can see what (if any) changes or additions have been made by intermediate servers.
• CONNECT: The CONNECT method converts the request connection to a transparent TCP/IP tunnel, usually to facilitate SSL-encrypted communication (HTTPS) through an unencrypted HTTP proxy. See HTTP CONNECT tunneling.
• PATCH: The PATCH method applies partial modifications to a resource.
• LINK: The LINK method is used to establish one or more relationships between an existing resource identified by the request URI and other resources.
• UNLINK: The UNLINK method is used to remove one or more relationships between the existing resource identified by the request URI and other resources.

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.

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

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

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

Simple MvCall Example: This example skips the tags and just returns the text.
<MvCALL ACTION = "g.url" METHOD = "GET">
    <MvIF EXPR = "{ s.callobjecttype EQ 'tag'}">
        <MvCALLCONTINUE>
    </MvIF>

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

Advanced Example: This example prevents runtime errors, transmits xml data stored in l.request_xml_string, and captures the results in l.return
<MIVA MvCALL_Error = "nonfatal, nodisplay">
	<MvCAPTURE VARIABLE = "l.return">
		<MvCALL METHOD = "XML"
			ACTION = "{ l.transaction_url }"
			FIELDS = "l.request_xml_string">
			<MvEVAL EXPR = "{ s.callvalue }">
		</MvCALL>
	</MvCAPTURE>
<MIVA MvCALL_Error = "fatal, display">

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.

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

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

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

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

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

Using RAW

The RAW method transmits data unformatted without any names, equal signs, or ampersands. Unless specified in the CONTENT-TYPE attribute, data is transmitted as text/plain.

In the example below json data is created and transmitted for processing.

<MvCAPTURE VARIABLE = "l.json" STANDARDOUTPUTLEVEL = "text, compresswhitespace">
{
	"contacts": [{
		"email": "something@example.com",
		"first_name": "John",
		"last_name": "Doe"
	}, {
		"email": "something@example.com",
		"first_name": "Bob",
		"last_name": "Roe"
	}, {
		"email": "something@example.com",
		"first_name": "Jim",
		"last_name": "Trunks"
	}]
}
</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

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.