The Basics

What Is CloudWriter

CloudWriter is infrastructure technology for producing dynamic web pages that contain data that is computed or is retrieved from a database.

"Scripts" or "programs" written using the CloudWriter language (CloudScript) are stored on the web server and are called up just like any other server file with the extension .htm or .html. The extension for CloudScript is .cw.

When the script is called up it is interpreted by the CloudWriter processor. Typically, execution of the CloudScript produces text which will be returned to the web server. The web server will then return the text to your web browser. Voila! You have a dynamic web page.

What Does the CloudScript Language Look Like

If you are familiar with C++ or with Java, you are well on your way to understanding CloudWriter. Here are most of the differences between CloudWriter and C++. If you understand these differences, you are well on your way to writing CloudWriter programs.

The Differences from C++:

Programs comprise either "scripts" or "full programs".
Scripts are executable statements.
Full programs are declarations of classes, objects and global functions.
Variables do not need to have their type declared.
Variables can hold values of different types.
There is a special type called array.
There is a special type called table that is an associative table.
Function arguments can be different types, dynamically, at runtime.
Function and class declarations are not needed at compile-time.
The "switch" statement supports non-integer types, including strings.
"case" labels can be expressions.
"Active" data members:
* "monitored" data members. A pair of member functions can be defined that are called when a data member is accessed.
* - "simulated" data members. A pair of member functions can be
defined that are called using the syntax for data member access.
Reading and writing array elements are treated distinctly and multiple subscripts are supported.
Safe variable argument lists. The variable arguments are passed as a dynamic array whose elements, of course, include their type.
The "%" operator for real numbers is equivalent to the fmod function.
Unsigned integers are not supported. These types can be used, but they are treated as signed.
The "private" class member access is not supported. CloudWriter supports "public", "protected", and "public_read".
Special lexical processing is done for programs or scripts that contain <$ ... $> and embedded CloudWriter expressions: <$ ... <? expr?> ... $>.
Classes may be defined at runtime; this feature is used to implement the runtime definitions of database, table and column classes and members.

Database Access

CloudWriter includes an embedded high-performance, low-administration relational database management system called CloudStore. The rdbms is a multi-user, thread-safe product that may be accessed in many ways:

from CloudWriter using the database, table, and column base classes
from CloudWriter using derived classes generated at runtime from the names of the tables and columns in the database
from CloudWriter using a streamlined version of ODBC
from C++ programs on the server using the special classes
from C++ and other programs on the server using ODBC
from Java programs using JDBC

The Simplest Way to Access the Database

Without a doubt, the simplest way to access the database is to use the function DatabaseTables. Here is an example of its use:

DatabaseTables ("database.db", "table0", "table1", "table2");

This has the effect of declaring at runtime the new classes table0, table1, and table2! Now, you can access the columns in those tables like so:

tablename.columnname

You can assign a new value to the column:

tablename.columnname = newvalue;

So, a program snippet that would "publish" a table from the database might look like:

DatabaseTables ("database.db", "table0");  // open the database and table0

TableBegin;

for (table0.FirstRow; table0.NextRow;)

	// call a function to put out three columns

	TableRow(table0.column0, table0.column1, table0.column2);

TableEnd;

For more on database access, see Database Access.

Outputting to Client

You can output to Client in several different ways:

You can use the predefined Client object, Client, and the << operator.
You can include inline HTML surrounded by <$ and $>.
You can use the Include function.

The Client Object

A Client object example:

x = "Hello, World.";

Client << x << "<br>";

Client << 123.45;  // outputs the character representation of the number.

Client << table0.name // outputs the name of table0

Using <$ and $>

When the special lexemes <$ and $> are recognized by the CloudWriter processor, the text between the <$ and $> are taken to be literal HTML (embedded HTML) that should be sent to the browser. Example:

<$Hello, World.$>

is equivalent to writing:

Client << "Hello, World.";

The typical use is for larger sequences of HTML.

When embedded HTML needs to be merged with content generated by the CloudWriter script, surround the CloudWriter expression with <? and ?>. Example:

<$The answer is: <?answer?>.$>

Using the Include function

When the HTML you want to emit is more conveniently stored in an external file, such as one built using programs like FrontPage and Dreamweaver, use the Include function.

The Include function has the form:

Include(filename, args ...);

Here's what happens:

The file is read in.
If the file has a special extension (not .htm or .html) it is processed by the appropriate special processor defined for your web server; for example, .asp files will be processed by asp.dll and .shtml and .shtm files will be processed by ssinc.dll.
If there are more than 3 arguments to the Include function, the 2nd and 3rd arguments are taken to be begin and end delimiters; the fourth and following arguments are additional data. The contents of the file are scanned and and string between the begin and end delimiters is interpreted as an CloudWriter expression and evaluated. The value of the expression replaces the delimiters and the expression. The expression may reference global variables or arguments to the Include function. These arguments are referred to as arg[0], arg[1], etc. arg[0] is the scriptname, arg[1] is the left delimiter. arg[2] is the right delimiter. Usually, your include file will only contain references to arg[3], arg[4] ...
If the file has the .cw extension, the program will be executed and and resulting HTML merged with the calling program's HTML.

Running a CloudScript Program

You run a CloudScript program by referring to it in an URL. Example:

http://www.cloudwriter.com/program1.cw

If there are arguments, they appear in the usual place:

http://home.domain.com/prog.cw?arg1=5&arg2=abcdef & ... etc

In the case above, the CloudScript prog.cw will be processed. The global variables arg1 and arg2 will be defined prior to execution of the "script". NOTE: a script contains only executable statements; no declarations.

If there is an argument called "eppfunction", the referenced file will be treated as a "full program" with a set of global function, class, and object declarations. The value of eppfunction will be taken as the function to call and that function will be called with 0 or 1 arguments.

If query variables are defined (all the stuff after the "?" in the URL), they will be defined as global variables. Also, all the variables will be placed in a table called "_QueryValues". Thus, you could refer to eppfunction as _QueryValues["eppfunction"];

If you just want to see the source for a CW program, just supply the argument ListSelf.

If you don't want to execute the program, just supply the argument NoRun.

So, if I want to see the source for example.cw, the URL would look like

example.cw?ListSelf&NoRun

John Elkins (john@vermontdatabase.com) 16 Sep 2002