Quick Reference>Caravan Language Reference
Introduction Installation Beginning Admin Quick Ref FTP Server SMTP Server Database Security
Statements Objects String Parsing Events Queues Samples Special names Error Handling Accessories   Back
Caravan Business Server>Help>Quick Reference>Caravan Language Reference
Syntax Compilation of Syntax
Text
General:

Caravan Code:
=============
In caravan templates code inside caravan tags is caravan code, the text outside
is text/html. The follwing examples are equivalent.
example 1:



Hello world<hr><caravan>"Date:";time t; t(mm);"/";t(dd);"/";t(yy)</caravan><br>



example 2:
<caravan>
  " \n"
  " \n"
  "Hello world<hr>Date:";time t; t(mm);"/";t(dd);"/";t(yy);"<br>"
  " \n"
  " \n"
</caravan>

Cut and paste one of the above into the file 'helloworld.html' in caravan templates folder and invoke
from browser: "127.0.0.1/helloworld.html". See "Getting Started".


Comments
========
Text following two forward slashes '//' is comment -- ignored by compiler.
Statements need to be terminated by ';' if followed by statement  or comment on the same line .
        Syntax:
        // This is a comment
        var x;var y;      // this is a comment

Caravan names and statements are not case sensitive.


Multiple Statements in one line
================================
example :
<CARAVAN>
  "Date:";time t; t(mm);"/";t(dd);"/";t(yy);//use semi-colon to separate satements on same line
</CARAVAN>


Statements:
===========
      String output:
                  Constant strings and variable data can be sent to the output stream just by expression:
                  Output stream is by default the tcpip connection to the client. Can change default
                  output stream by 'output' statememt -- see 'output'
                  example:
                              "Hello world"
                              t(date);// t is of type 'time'

      Iteration:
      Object Loop:
        Creates an object of type loop;
      loop <loopname> (loopmaxcount)
            statements
            break
      repeat <loopname> [fixed-looplimit] ;// fixed-looplimit is optional
      Count ; current iteration count;
      Break ; come out of loop

        Flow control:
        Conditional statements:
      Syntax If-Else:
             if <condition>
               <statement>;
             else
               <statement>;
             endif

             if <condition>
               <statement>;
             endif

             if <condition1>
               <statement>;
             elseif <condition2>
               <statement>;
             elseif <conditionN>
               <statement>;
             endif
            
             condtions :
                   (rhs expression) (conditional symbol) (lhs exp)
                conditional symbols
            = ; equals
                <>; not equals
            > ; greater than
            >= ;greater than or equal
            <;less than
            <=;less than or equal
            =~; matches pattern
      
            ex:
            if f(x)=~"*.pdf"
            if domain="admin"
         Terminate:
                The execution normally terminates after last statement.
                To terminate execution 'over' key word can also be used.
                if domain<>"authorized"
                   over;
                endif


label and goto
==============
       goto <labelname>
       label <labelname>


Objects
=========
Most caravan objects are declared as :
        <objecttype> <objectname>       // var x;  time t; ftp a;                
Properties of caravan objects are accessed as:
        <objectname>(<property>)                // user x; x(username)  

        <objectname>(<property>)=<value1>
        <objectname>(<property>)=<value2>
        <objectname>(<property>)=<valueN>
        Caravan properties can have multiple values:
        <objectname>(<property>(00)) ;// returns array size;
        <objectname>(<property>(0NN)) ;// N is a digit 0-9
        


VAR -- general purpose object
=========
        Basic data types : string, numeric and real are supported implicitly.
        
        var <objectname>
        <objectname>(<property>)

        <objectname>(<property>)=<value>;       //<value> is either a quoted string
or a property of an object;
        <objectname>(<property>)=<value1>
        <objectname>(<property>)=<value2>
        <objectname>(<property>)=<valueN>
        <objectname>(<property>(00))
        <objectname>(<property>(0NN)) ;// N is a digit 0-9
        
        ex:
                    var x;
                    x(valA)="2.3" ;//
                    x(valB)="string"
                    x(valC)="2"
        
                    x(valA)+x(VALC) = "4.3"
                    x(valA)+x(valb) =  "2.3string"
                    x(valA)*x(valb) is void

        var x={value}X{template}:{property,...property};// parsed object -- see parsing
        var x=fileobject(file); creates object from a mime document
        x(); outputs the object in mime format -- "multipart/form-data"

        Use of delim:
        ==============

                    x(delim)=" "
                    x(value)="1 2 3 4 5 6 7 8 9";// splits string at space character
        
                    x(value(00)) ;// array total
                    x(value(01)); array index 01
                    x(value(02)); array index 02


FORM
=====
  It is used for communication.
  Form object is similar to <VAR> -- it can be used to represent a general object
  in the same way. In addition a form object can post or put itself to an http  server using
  http protocol.  For this purpose it has some properties
  that needs to be set. It has a 'post' method which can be used to post it explicitly -- in
  this case the current thread does the work needed to connect, and post the form.
  If it is not sent explicity by calling the post or put method,
  then during the delete operation it transforms itself into
  a thread to independently post itself before being garbage collected.

  A form can also be sent using the HTTP-PUT using the 'put' method. This has to be done
  explicitly. This method is preferable in file transfer applications because it avoids
  MIME creation and parsing steps which reduce the throughput.
  
    
  Typename: form
  Syntax:
      form <objname>;
  Method:
      form(post);
          Send using http POST protocol in mime format.This is the default Method.
        form(put);
          Send using HTTP PUT. Payload (a single file)has to be assigned to 'content'.


        Both methods can be used to dispatch information. For structured
        data or to send more than one file 'post' is prefered.Where single
        file transfers are required 'PUT' is faster.

        Multiple files cannot be send using 'PUT'.In addition, other
        properties are send in the http request header, and the HTTP RFC requires
        that the property names start with the seq "x-". See example.

        An object with name '_reply' is created by the post/put operation. This
        can be examined to see the status of the operation and  the reply
        from the server, if any.

  Settable Properties:
      form(_server); http server
      form(_port); http port
      form(_action);remote server action url for post.
        form(content);file payload for needed for put.

      _reply(content);// remote server's response.
        _reply(error);// errors
        
        Error values:

      //*******
      form(_url) ; // same as _action
      form(_connection) ; close or keep-alive as per http 1.1
      form(_serverport);// same as _port
      //*******

      e.g

      form x={value}X{template}:{property,...property}
      form x=fileobject(file); creates object from a mime document
      x(); outputs the object into mime document
        Examples of 'post' and 'put':
        Example 'post':
          form myform
          myform(content-length)=myfile(size)
          myform(content)=myfile(file);// see file object
      //all of the following is required for 'post'
          myform(_server)="172.167.2.34";// ip address or fully qualified host name
          myform(_action)="getfile.html";// has no use in 'put'
          myform(_port)="80";// port 80 is not assumed by default.
          myform(_connection)="close" ;// close tcpip link after dispatch, "keep-alive" is
                                       // default
          myform(post);// send the form to server

        Example 'put'
          form myform
          myform(x-content-length)=myfile(size);// content-length is a reserved header in http
          myform(content)=myfile(file);// see file object
      //all of the following is required for 'post'
          myform(_server)="172.167.2.34";// ip address or fully qualified host name
          myform(_port)="80";// port 80 is not assumed by default.
          myform(_connection)="close" ;// close tcpip link after dispatch, "keep-alive" is
                                       // default
          myform(put);// send the form to server
          if _reply(error)
             "Could not send because of ";_reply(error); "ERROR"
          else
             "Remote server says:";_reply(content);
          endif

        If the remote server is a caravan server both methods are supported. Some
        servers may not support http put.

        See ALSO: Caravan support for accepting http post/put.


TIME
=======
Represents time.
Type Name : time
syntax:
        time <objname>
Method:
Read-Write Properties:
        Current(time);
        Current(year)
        Current(month)
        Current(day)
        Current(date)
        Current(hour)
        Current(minute)
        Current(second)
Readonly Properties:    
        Current(yy)
        Current(mm)
        Current(dd)

Setting the time value;
Time t
t(time)=current(time); sets the time
t(date)="23"
t(month)="apr"; t(month)="4"
t(year)="2000"
t(year)+="1"; // advance time by one year;
t(second)="0"
t(minute)="0"
t(hour)="0"
t(hour)+="24";// advance time by one day
t(date)+="30";// advance time by 30 days;
t(second)-=current(time);// get difference in seconds
example:
   // to show time in dd/mm/yy hour:minute
   t(dd);"/";t(mm);"/";t(yy);" ";t(hour);":";t(minute)
Note:
Time is represented by a 32 bit value in unix time format -- seconds since 1st January, 1970.



MAIL
========
Used for sending mail. This object can connect to smtp server and dispatch itself using smtp protocol.
Supports smtp extensions : PIPELINING, CHUNKING and BINARY MIME. On delete, either explicit or
implicit, it  enters the the 'smtp' queue. A user created eventhandler is needed to disaptch the
mails. The code for this eventhandler is quite simple and is given elsewhere, in this manual.

  Syntax:
      mail mymail;
  Methods:
  Properties:
      mymail(to)="email address"
      mymail(cc)="copy to address"
      mymail(subject)="Subject line"
      mymail(text)="text or file"
      mymail(attachment)=f1(file);      mymail(attachment)=f2(file); // multiple files can be attached
      mymail(post);
      mymail(error)
      //*********
      mymail(smtpgateway);// connects the given smtp server skipping the DNS.
      //*********



FILE
=======
   Syntax:
      file x="filename"  //or
      file x=file         //or
      file x=url;         // or this
   Methods:
   Properties:
      x(file)            //To access contents of the file
      x(filename)      // To access name of the file
      x(size)            // Size of the file
      x(urlname)      
      x(date)            // To access creation date of the file.
      x(time)
      x(file)=file
      x(replace)

      //random access

      file(blocksize) // set
      file(blockno) // set
      file(block) //  get



FOLDER
=========
  Syntax:
      folder x=path
  Properties:
      x(minsize)
      x(filespec)="*.exe"
      x(maxsize)
      x(type)
      x(datefrom)
      x(dateto)
      x(startat)
      x(filename)
      x(fullname)
      x(extension)
      x(time)
      x(size)
      x(path)
      x(count)
      x(reset)
      x(folder)
      x(file)


FTP
===
   Default port=21
   The ftp object is similar to a folder object.
   It connects to an ftp server using the uri given in declaration.
   Syntax:      
      ftp x="server"; // port is assumed to be '80', needs login and pswd to be set.
            x(user)="anonymous"
            x(pswd)="user@domain.com"
        ftp x="anonymous:user@domain.com@serever:nn";// nn is port number.
   Properties:

   See folder for for additional properties.


QUEUE:
=====
   Caravan can create fifo (first in first out) queues using the queue object.
   When an item is inserted into the queue, corresponding event handler is triggered.
   Entering an item in queue is akin to creating an event. Each queue has a name and
   each item may have an additional property called 'type' which can be used to further
   channelise the queues. Items with same priority are handled in fifo basis. The queue
   object is used for creating, viewing and manipulating the queues. Event handlers
   are just caravan code containg the eventhandler declaration.
  
   Syntax:
      Queue <queue name>(<queue name>)
      Queue <queue name>(<queue name>,<queue type>)  
      Queue <queue name>(<queue name>,*)  
      Queue <queue name>(<queue name>,?)  

      example:
            queue x(smtp)
            queue x(smtp,yahoo.com)
   Properties:
        Priority:
             Priority is a number which is used to order the items in queue. The higher
             the number , higher the priority. Default value is '0'.
        type : The type of the queue item. This property is used to create a multi-threaded
               eventhandler - one type for each type running the same code.
        item : is the information neeaded to handle the event. It can be of type string, or file.
               queue x(myq)
               x(item)=tbl(recordno);// only the record no is in queue.
               x(item)=tbl();// whole record is inserted
               x(item)=myvar();// whole object is inserted
        wait:  Time in seconds. For this many seconds the item disappears from queue -- letting other
               items to go ahead. Eventhandler cannot see items until wait is over.
        queueid: id of the current item;
            total:Total items in queue.
   Methods:
        next: next item in the queue
        select: can selects entries based on its item value. works only when item is "string".
        deleteitem: deletes item. aborts actives objects like form mail etc. before deletion.


Eventhandler declaration:
=============
There is a special way to declare a queue object, using the key word 'eventhandler'
instead of the 'queue'. This makes the code following the declaration an event handler for
handling such events as contained in the declaration. The code preceding the declaration is
used to do any inititalisation if required. It also creates a queue object with a special name
_event.

Syntax:
eventhandler(name,type);// for a prticular type and name
eventhandler(name);//for all types with same name
eventhandler(name,?);// per channel for each type


TABLE
=========
   Object:
      Var xyz
      table xyz=DatabaseName.Tablename
   Methods:
   Properties:
      xyz(recordno)
      xyz(nextrecord)
      xyz(selected)
      xyz(tableinfo);      // table structure saved in xml format. Read or write once to create a table dynamically
      xyz(insert)
      xyz(delete)
      xyz(modify)
      xyz(fields)      // fields of the table
      xyz(selectall)      // reset all previous selection

   Select Statements:

      select from       -----------multiple conditions are ANDed together

      select from
       ---------- multiple conditions are ORed together

      select from
      ---------selects all and  orders by <fieldname>

        select from mytable where origin is unique;// only select where this field has unique values.

   Use fixed words to assign variables
            var sql   or form()
            sql(propertyname)
            select from


   Search Statements
        select from mytable where subject like "urgent";// where value is a constant
        select from mytable where subject like "{mytoken}";// where value is variable
        select from mytable where subject like poly*;// search for substring (usually slow performance)
        select from mytable where subject like "my token"
        select from mytable where subject like "{token}"


   Creating a new Table

      <caravan>
            file mytablinfo="d:\directory\myfile.xml"      // existing xml file containing new table structure
            table newtable=xxxx.yyyy;                  // since its a new table this will create an empty table object.
            newtable(tableinfo)=mytableinfo(file);            // will create the db and table if they dont already exist
      </caravan>


   Can have search within a search. Just needs to give multiple select statements.



XML OBJECT
==========
  Object:
      object x=xml-file or url
  Methods:
  Properties:
      x(_node)
      x(_root)
      x(_next)
      x(_previous)
      x(_name)
      x(_error)
      x(_attribute) or x(_attribute)
      x(nodename.nodename.nodename.nodename(0nn))


USER
====
   Object:
      user x
   Methods:
   Properties:
      x(uid)
      x(userid)
      x(username)
      x(password)
      x(link)
      x(domain)
      x(total)
      x(add)
      x(delete)



Running External Applications
=============================
  Syntax:
      cmd <objname>=<program-name>([parameters]);  

      ex.
       cmd x=pkzip.exe(args)
  Properties:
      x(success)
      x(rc)
      x(output)



Filter
========
      filter url // filter as url
      filter ignorecase
      filter assignments // filter active during assignments
      filter "filtername" // resusable filter
      filter on
      filter off
      filter "string"="replacement-string"
      filter var(string)=var(replacement-string)



Schedule
========
   Syntax:
      Schedule = (<timespec>=<value>,...,<value>&......&<timespec>=<value>,..,<value>[&count=nnn])

    ex.
      schedule = (day=mon) // every monday once
      schedule = (minute=all) // every minute
      schedule = (minute=all&count=1) // only once a minute after startup
      schedule = (hour=1) // every day once
      Schedule =(minute=0,15,30,45); //four times every hour
      Schedule =(hour=10) ; //ten o clock every day
      Schedule =(date=1&month=1); //on 1st jan at  0000 hrs every year
      Schedule=(minute=1); //schedule the  task to run every hour



Domain
==========
       domain <domainname>|<domainname>|....|<domainname>




process termination
===================
       over


redirecting browser
====================
       redirect "<url>"


break out of loop
=================
      break


Delay/Sleep statement
======================
      sleep nnn  //(nnn=seconds)



include statement
==================
      include htmltemplate.html




output
======
      As HTML:
            <caravan>
                  "This is dynamic data :";objectname(propertyname);"<br>" // emits the value to output stream
            </caravan>

      output <outputstream>;
      append <outputstream>;// appends to existing file

            ex.
              output "con";// data is now going to the console. Mainly used for debugging
              output "lpt1"
              output "c:\caravan\doc\mylog.txt"  // output to a file
              output tmp(log)

      close output   // closes output



arithmatic:
============
      addition +
      substraction -
      multiply *
      divide /
      mod %
      concatenation +


persistence / Session / Global variables
===============================================

Objects can be made persistent across multiple requests within a session.
Also in schedulers and event handlers.
      ex.
      time LoginTime
      LoginTime(persistent)="true";// creates a time object which can be throughout the users' session.
      LoginTime(persistent)="null";// reset the persistent property or remove
      delete LoginTime;// delete the object explicitly



Decimal numbers / Real numbers
===================================
No syntax. Only Examples
      Example 1:
            // The resulting value is in x(myval) and is precise to three decimal points (same as the original precision).
            Var x
            x(myval)="10.123"
            x(myval(01))*="12"  

      Example 2:
            // The resulting value is an integer (458) stored in x(myval).
            var x
            x(myval)="10";
            x(myval(01))*="45.899"

      Example 3:
            //One can control the precision of the calulation by startiing with number which has the required precision as :
            var x
            x(myval)="0.000";
            x(myval(01))+=some(othervalue)
            x(myval(01))/="45.899"



String Manipulation/ Pattern Matching
======================================
      <objectname><[property(01)]> += Some other variable  // adding 2 strings
      <objectname><[property(01)]> -= Some other variable  // subtracting numbers


      if <string>=~<pattern>
            ex:
            if myfile(filename)=~"`*`.pdf"
            if myfile(filename)=~mypattern(val)

      var <objname>={<string>}X{<pattern>}:{pname1,..pnameN}
            ex.
                  var x={"test.data 1230 bytes"}X{"`*`%`*`%*"}:{filename,size}
                        x(filename);// "test.data"
                        x(size);// "1230"

      For example "*.*" matches any string which has '.' in it. Similarly "?.*"  matches string with one and only character before '.'.

      Pattern matching symbols and their usage is illustrated below:

            * ; matches any character multiple times
                     example:
                       *ing  = "walking", "running" etc.
            ? ; matches any character once
                ?ut = "cut", "put", "but" etc..
            %; matches space ' ' and tab
                *%*="hello world", "this is string", "1. Bombay" etc.
            $ ; matches any lowercase
                $*="abcd", "a" etc.
            # ; matches any digit
                #.## = "1.23","1.66" etc.
            @ ; matches any upper case
                @@@ = "GOD"
            & ; matches any alphabet
                &&& = "God"
            ^ ; matches white space including line feeds
                *^="hello world\n"
            ~ ; matches next chararacter or symbol multiple times
               ~%@~$ = "World", "        World" etc.
                ` ; marks the starting and ending of substring which is to be captured;
               ~%`@~$` ="World", "       World"  and captures "World"
            \ ; escapes next character from being treated as a special symbol
               \~* ="~anything", \###="#12"
            Other characters are matched exactly (not case sensitive)
               "A*" = "apple", "Apple" etc.


special files:
==============

ERROR404.html: handler for  document-not-found condition

mailuser.html : hook to smtp server for checking valid recipients

mailaction.html : handler for incoming mail

url for handling httpput is set in configuration.



special object names:
=================
_event; queue object which triggered the eventhandler


request:// header information in http request

gives the request environment


request(uri)
request(content-length)
request(user-agent)
request(accept)
request(location)
request(tmp)
request(documents)
request(address)
request(content);// file submitted by put.


_response:// header information in http response
sets the http-response properties

_response(content-type)
_response(cache-control)
_response(xyz)


form:// object respresentation of form posted by client as url-encoded or multipart/form-data


Directory structure of Caravan
================================
    Folder say
      Caravan
    Sub folders
         db
         doc
         templates
         tmp
         bin


Configuration file
====================
      httpd.cnf
      
      Settings in cnf file:
            MIME extensions
            Location
            Caravan-http
            ftp
            templates
            documents
            dbhome
            datacache
            bin
            home
            NameServer
            SMTP
            Domain
            BinaryFile
            sessionTimeout
            tmp
            time


Encoding Caravan Script
=========================
      Use an exe file given with Caravan
      encode filename(s) output filename
            


API support:
===========

Caravan Default login
=====================

      Username  =  your name
      password  = password

            OR
      username = admin
      password = password

   Change the default password, to access inbuilt html files of Caravan and database.


Caravan Inbuilt HTML files:
===========================
      Caravan.html
      DBMS.HTML
          Field types
            String
            Numeric
            Time
            Image
            Text
            Relation -> <Tablename>


         Flags
            L (local), M (Mandatory), U (Unique), B (Binary)
         Default Value

      Createuser.html
      login.html
      logout.html
      password.html
      edit_tmpl.html


HTML Form tag Declaration
==========================
<FORM action="HTML page name" encType="multipart/form-data" method=post name="Form name">

Sample
Quick Reference
Home       Back