Interpreter
Much of the power of Active4D lies in its language. Unlike 4D's semi-dynamic HTML tags, which are a transmogrified
subset
of the 4D language, Active4D's language is a
superset
of 4D's language. In other words, with Active4D you just write 4D code. In fact, in most cases you can write and test code in 4D and then paste it into a text editor to use with Active4D.
Active4D's interpreter is actually quite a bit stricter than 4D's, in that syntax errors and nonsensical constructions that 4D blithely ignores (but the compiler catches, of course) are considered errors and abort execution.
Active4D extends 4D's language in some important ways. In addition to defining new operators, you can also define methods and libraries of methods. These are covered in See Methods
Flow of Execution
The Active4D interpreter is essentially a text processor. It parses a text input (which might be a file or a block of text) and writes to a
response buffer
. The text input may have any mixture of HTML and embedded Active4D source code. When execution begins, the response buffer is empty.
Embedding Source Code
Active4D source is separated from HTML by one of three tag pairs:
|
Begin tag
|
End tag
|
|
<%
|
%>
|
|
<?
|
?>
|
|
<!--Active4D
|
-->
|
Although any of the tags are valid, the corresponding end tag must be used with its beginning tag.
In the case of the first two tag pairs, there is no need for white space between the tags and the Active4D source. In the case of the third pair, which is actually a specialized HTML comment, you must leave at least one whitespace character between the tags and the Active4D code it encloses.
-
I recommend you use <% %>, as most visual HTML editors automatically recognize them as embedded script tags. This is because Microsoft's Active Server Pages (ASP), the world's most popular embedded scripting language, uses these tags.
|
Here is an example of Active4D source code embedded in the three different types of tag pairs.
|
<% write("hello") %> `OK
<?write("hello")?> `OK with no space around these tags
<!--Active4D write("hello") --> `OK
<% write("hello") ?> `Error: can't mix tags
<!--Active4Dwrite("hello")--> `Error: need space around these tags
|
Like 4D, Active4D is line-based; the end of a line or the end of a code block marks the end of a statement. However, you may have as much whitespace as you like between the Active4D tags and the actual source.
Input Parsing
Let's look at an extremely simple example which will illustrate how Active4D parses and executes a script. Suppose we execute a file which has the following contents:
|
<html>
I was here at <% write(Current time) %> on <% write(Current date )%>
<html>
|
Active4D begins execution by scanning for a source code begin tag. As it scans, the text is appended to the response buffer. When the first "<%" in the above example is reached, the response buffer contains:
Once a source code tag is found, Active4D skips past the tag and goes into execution mode. In execution mode, Active4D continues to parses the text, but instead of passing the text through to the response buffer, it resolves the text into executable tokens and then executes the tokens.
It would be pretty useless if you could not write dynamically generated text to the response buffer within your source code, so Active4D provides a
write
command to do just that. The
write
command takes a value of any type, converts it to text, and appends the result to the response buffer.
In the example above, the
write
command is the first token. The
write
command handler is given control, which proceeds to evaluate the parenthesized expression following the command. In this case the expression is the 4D command
Current time
, which is converted to text as if passed to the
String
command. The text is appended to the response buffer, and the interpreter then continues parsing.
The next token is "%>", which is a source code end tag. Active4D skips to the end of the tag and switches back to scan mode. At this point the response buffer contains:
|
<html>
I was here at 19:27:13
|
The interpreter scans up to the next source code begin tag, appending to the response buffer. At the start of the next source code block, the response buffer contains:
|
<html>
I was here at 19:27:13 on
|
The interpreter then executes the second source code block as it did the first, after which the response buffer contains:
|
<html>
I was here at 19:27:13 on 10/19/2001
|
The interpreter scans to the end of the file and returns control to the caller. At that point the response buffer contains:
|
<html>
I was here at 19:27:13 on 10/19/2001
</html>
|
If the interpreter was invoked by Active4D's web server, the web server generates the HTTP headers necessary to describe the response to the client. Finally, control returns to 4D, and the shell sends the generated headers and response body to the client browser, which displays the text:
I was here at 19:27:13 on 10/19/2001
The client cannot see the source code because it is stripped out before being sent back from the server.
Language Syntax
For the most part Active4D's language (henceforward just "Active4D") has the same syntax as 4D's language. However, there are a few important differences and enhancements.
Source Code Structure
Because Active4D source code is plain text, you are free to use whatever indentation style you wish -- the 4D method editor is not there to do it for you. Typically you will want to use tabs in your text editor to perform indentation of control structures. For example:
|
<% write("hello") %>
<%
write("hello") `This is exactly equivalent to the previous block
%>
<%
if ($sort_ascending = "1") `Note the space around the =
order by([customers];[customers]lastname;>)
else
order by([customers];[customers]lastname;<)
end if
%>
|
You can have any number of Active4D code blocks within an HTML page. In addition, it is not necessary to complete control structures within the block in which they are declared. This powerful feature allows constructs like this:
|
<% for($i;1;3) `I'm starting the loop here... %>
Active4D rocks!<br>
<% end for %>
`Here is the output
Active4D rocks!
Active4D rocks!
Active4D rocks!
|
Using this feature with
If/Else/End if,
you can conditionally show entire tables, form items, etc.
-
Just because your source is embedded inside your web pages in text form does
not
make it inherently insecure. To understand why, please see See Security
|
Case Sensitivity
Like 4D, Active4D is not case sensitive, so you can just as easily write "first record" as "FIRST RECORD". But whereas the 4D method editor would change "first record" to "FIRST RECORD" when it parsed the line, in Active4D it will remain "first record" because you will be using an external text editor.
Case-insensitivity extends to table and field names, method names, and variable names.
Expression-based
One difference between 4D's language and Active4D is that Active4D is expression-based, like C/C++/Java. In other words, everything is an expression, including an assignment. So the assignment:
actually evaluates to the value of $i after the assignment, namely 10. This allows you to do convenient tricks like this:
|
first record([contacts])
while (($name:=[contacts]lastname) = "a@")
writebr($name)
next record([contacts])
end while
|
Comments
Active4D supports regular 4D comments (indicated by
`
), either on a separate line or at the end of the line, with no limit on their length. You may also use the characters "//" as a synonym for
`
to indicate a 4D-style single-line comment.
In addition, Active4D supports
block comments
. Unlike 4D comments, block comments may be embedded within a line or may span multiple lines.
Block comments begin with the character sequence "/*" and end with the character sequence "*/". For those of you who know other languages, this is the standard syntax for block comments in C/C++ and Java.
Here are some commenting examples:
|
/*
This is a multi-line comment that will be rather lengthy. By using block
comments I can format it easily and it is easier to read.
*/
`A plain old 4D-style single-line comment
// A new-style single-line comment
writebr("hello") // Also can be used at the end of a line
/*---------------------------------------------------------------------
MyLibraryMethod($inFoo; $inBar) -> Text
$inFoo Longint A foo
$inBar Longint A bar
RESULT Text A foobar
-----------------------------------------------------------------------*/
writebr("Block comments can even be " + /* wow! */ "embedded!")
/*
writebr("Using block comments...")
writebr("is a quick and easy way...")
writebr("to comment out a block of code")
*/
|
Identifiers
Identifiers in Active4D follow the same rules as in 4D, both in terms of valid characters and maximum length (31 characters excluding any prefix).
Active4D maintains its own local variables which are indicated by a leading dollar sign, as in 4D. You can also access existing 4D process and interprocess variables (using "<>", not the Macintosh diamond character), as well as any fields in the database. Last but not least, all 4D named constants (4DK#) are recognized, including ones which you may have installed in your database structure.
Data Types
Active4D can operate on all 4D data types except for 2D arrays. Data types may be implicitly converted according to the same rules 4D uses, or explicitly converted using commands such as
String
and
Num
.
Compiler Declarations
All compiler declarations are supported, but you may only use them on local variables. By predeclaring local variables with compiler declarations, you can achieve better type safety in your code.
For example:
|
c_longint($long)
$long := 7
$long := 13.27
`Without the compiler declaration, $long would become a real = 13.27.
`Because it was declared a longint, its value is now 13.
$long := "foobar" `this generates an incompatible argument error
|
Active4D imitates 4D's interpreted behavior exactly in regards to variables that have been declared in compiler declarations. Once a variable has had its type fixed by a compiler declaration there are two ways it can be changed:
-
With another compiler declaration. If the new type is not assignment-compatible with the old type, the variable will be set to a null value. Otherwise a type conversion is done.
-
By passing it as a parameter to a command that sets the parameter value inline, such as
GET PICTURE PROPERTIES
.
Array Support
All array types except 2D arrays are now fully supported in Active4D. This includes picture and pointer arrays. You may declare and use local arrays in Active4D just as you would in 4D.
Pointer support
Active4D supports pointers to process and interprocess variables, tables, and fields. You may create and dereference pointers to any of these entities within Active4D.
As in 4D, you may not create a pointer to a local variable. However, Active4D allows you to pass local variables
by reference
to its own methods, which is effectively the same as using a pointer (but easier). For information on pass by reference, see See Methods
Literals
Active4D recognizes string, number date and time literals in all the standard formats except scientific notation. If the current platform charset is
Shift_JIS
or
GB2312
, string literals are assumed to be in
Shift_JIS
or
GB2312
and are parsed accordingly.
-
Time literals must use '?' as the delimiter.
|
There is one major extension to string literals in Active4D. Strings literals support backslash-prefixed embedded control characters:
|
Backslash combination
|
Resolves to
|
|
\n
|
Char(Line feed)
|
|
\r
|
Char(Carriage return)
|
|
\t
|
Char(Tab)
|
|
\"
|
Char(Double quote)
|
|
\\
|
\
|
|
\<char>
|
<char>
|
Here is an example of using backslashes in a literal, with the equivalent 4D code. You decide which is easier to write and read.
|
write("This is line 1.\r\"It's cool!\", you say.")
Output:
This is line 1.
"It's cool!", you say.
`4D code to do the same
"This is line 1."+Char(13)+Char(34)+"It's cool!"+Char(34)+", you say."
|
User-defined constants
In addition to supporting all installed 4DK# constants, Active4D allows you to define named constants at runtime using the
define
command. For more information on the
define
command, see See define.
Typing of Values
Typing of local variables in Active4D follows the same rules as 4D. If a local variable has not been declared with a compiler directive, it is variant: its type changes on the fly according to the type of value assigned to it. Once it has been declared within a compiler declaration, it follows the rules outlined in See Compiler Declarations above.
On the other hand, 4D variables and fields are always considered invariant. You cannot assign a value to them that would change their type.
For all variables and fields, Active4D will generate an error and abort execution if a referenced variable or field is undefined.
Operators
Active4D implements all of 4D's operators (with the exception of some picture operators), including array indexing and character references. Character references must use the syntax
[[N]]
, where
N
is a number from 1 to the length of the text being referenced.
Active4D operators have the same restrictions on the data types they will accept as 4D does. Active4D will abort with an error if an attempt is made to divide or modulo by zero.
New Active4D Operators
Active4D adds many operators from C/C++/Java which make writing code faster and easier to read. Here are the new operators:
|
++
|
prefix and postfix increment
|
|
--
|
prefix and postfix decrement
|
|
+=
|
add and assign
|
|
-=
|
subtract and assign
|
|
*=
|
multiply and assign
|
|
%=
|
modulo divide and assign
|
|
/=
|
divide and assign
|
|
\=
|
integer divide and assign
|
|
^=
|
exponentiate and assign
|
|
|=
|
bitwise inclusive OR and assign
|
|
&=
|
bitwise AND and assign
|
|
<<=
|
bitwise shift left and assign
|
|
>>=
|
bitwise shift right and assign
|
Here are some examples of their usage:
|
$i:=3 `I think $i=3 now
$j:=++$i `increments the value of $i before the assignment, $j=4
$k:=$i++ `increments $i after the assignment, $k=4, $i=5
$i*=3 `multiplies $i by 3 and assigns, $i=15
$i+=3 `adds 3 to $i and assigns, $i=18
$i>>=1 `bit shifts $i one bit and assigns, $i=9
|
In other words, any expression:
|
<assignable> <op>= <value>
|
is equivalent to:
|
<assignable> := <assignable> <op> <value>
|
Any of these operators will work with array elements. So, for example, you can increment the fifth element of an array by using the ++ operator:
|
$myArray{5}++ OR ++$myArray{5}
|
Picture Operators
Active4D supports horizontal and vertical concatenation for pictures. Thus the operators that may be use with pictures are:
|
+
|
horizontally concatenate
|
|
/
|
vertically concatenate
|
|
+=
|
horizontally concatenate and assign
|
|
/=
|
vertically concatenate and assign
|
Enhanced Operators
The + operator has been enhanced in Active4D to auto-convert arguments to the right to text if the argument to the left is text.
For example:
|
$s := "I was here at " + Current time + " on " + Current date
|
Notice there is no need to explicitly convert
Current date
and
Current time
to strings.
Remember that the argument to the left of the + must be text for this trick to work, so the following statement would not work, because the + operator would try to add ", " to the date returned by
Current date
:
|
$s := Current date + ", " + Current time + ": I was here"
|
In this case, you would have to "prime the pot" by converting
Current date
to a string:
|
$s := string(Current date) + ", " + Current time + ": I was here"
|
Control Structures
All of 4D's control structures and flow of control keywords are supported, with four notable additions:
for each/end for each
,
break
,
return
,
exit
and
continue
. If you are familiar with other languages that use these keywords, they work exactly as they do in those languages. If are aren't familiar with those languages, here's how they work.
for each/end for each
This looping control structure is the easiest way to iterate over a collection. For more information on collections, see See Collections and See Iterators.
break
If you are within any kind of loop (
For, While, Repeat
), the
break
keyword (used on a line by itself) will transfer execution to the first line of code after the end of the loop. The loop variable used by a
For
loop will not be changed. If you use
break
outside of a loop it will generate an error.
return
This keyword (used on a line by itself) transfers execution to the first line of code after the current code block. If you are within an Active4D method, execution will continue at the first line of code after the line that called the method. It can also take a parenthesized expression to return as the result of the method.
continue
If you are within any kind of loop (
For, While, Repeat
), the
continue
keyword (used on a line by itself) will transfer execution directly to the top of the loop. The loop variable in a
For
loop will be incremented according to the
For
clause. If you use
continue
outside of a loop it will generate an error.
exit
This keyword, used on a line by itself, immediately aborts all execution without generating an error. This is primarily useful for debugging, when you want to dump the internal state before a certain point and then stop. This keyword is also useful if you have detected an error condition from which you cannot recover and you want to immediately stop execution.
Examples
Here are some examples of how to use the new keywords:
|
`Using break to terminate an infinite loop
$i:=0
while(true) `You could never do this in 4D!
if (++$i > 10)
break `The closest loop, in this case the while loop, will be exited
end if
write($i) `This will NOT be executed once break is executed
end while
`Here's the Active4D way of breaking out of a for loop
for ($i;1;size of array($names))
if ($names{$i} = "g@")
break
end if
writebr($names{$i}) `This will not get executed after break is executed
end for
`Here's the 4D way
for ($i;1;size of array($names))
if ($names{$i} = "g@")
$i:=size of array($names)+1
else
writebr($names{$i})
end if
end for
`Using continue in a for loop
for ($i;1;size of array($names))
if ($names{$i}="s@")
continue `Immediately goes to next iteration of loop
end if
writebr($names{$i})
`Do lots of other stuff here. The effect of continue above is to skip this
end for
|
Working with Paths
In the course of programming a web site with Active4D, you will often need to specify file path. If you have done any work with paths in 4D, you know what a pain it can be, especially when dealing with multiple platforms.
URL-Style Paths
All commands that take a path in Active4D -- including Active4D's implementation of standard commands like
Open document
-- can take a URL-style path, which uses `/' as the directory separator. This allows you to program in a platform-neutral way, without having to worry about the native directory separator.
Absolute vs. Relative Paths
A path can be
absolute
or
relative
. What that means depends on the command using the path. Standard 4D document commands and Active4D's own commands treat paths differently.
4D document commands
-
As with 4D, in Active4D absolute paths are relative to the computer, allowing you to access any volume mounted on the host machine (including network volumes). Remember, however, that by default Active4D restricts document command access to the web root directory. You must use the "safe doc dirs" option in
Active4D.ini
to gain access to directories outside the web root directory. For more information, see See The "safe doc dirs" Config Option.
-
As with 4D, relative paths are relative to the default directory, which is the database directory under Server/Standalone or the application directory under Client.
Active4D commands
-
Active4D commands are designed for use within the context of a web page. Thus their "world," so to speak, is limited to the web root directory.
-
Absolute paths used with Active4D commands are relative to the web root directory. Thus if the root directory is:
-
/Server/db/web
-
the path
-
/accounting/default.a4d
-
is actually the path
-
/Server/db/web/accounting/default.a4d
-
Relative paths used with Active4D commands are relative to the directory of the currently executing file.
Path Utilities
Active4D provides a many utility commands for working with paths. For example, if you need to use a 4D document command on a file within the web root directory, the
get root
command returns the full path to the current root. In addition, there are commands to extract the filename from a path, the extension from a filename, and the directory from a path.
For more on these commands, see See System Documents.
-
Unlike Active4D v1, version 2 adds a trailing `/' to any directory paths returned by Active4D commands such as
get root
.
|
Path Limits
The maximum length of a path, including the root directory, is 255 characters. The maximum length of any component of a path is 63 characters.
You must ensure that your path lengths are within these limits, or Active4D will not be able to find your files.
Including Other Files
One of the most powerful features of Active4D is its ability to include other files during execution. To include a file, you use the
include
command, passing a relative or absolute URL-style path. Since
include
is an Active4D command, absolute paths are relative to the root, and relative paths are relative to the currently executing file.
If found, the included file is interpreted as if it were part of the source file. The scope of the included file is whatever the scope was where the
include
command appeared.
This means that any local variables declared before the include are available in the scope of the include file's code, and any local variables declared in the include file are available to the source file when the include file is finished executing.
Included files may in turn include other files, ad infinitum (or until stack space or memory runs out). Before including a file, Active4D checks to see if the include is a circular reference and aborts execution if it is.
-
You may also use the
include into
command, which allows you to include a file and place the output into a variable.
|
Uses of Included Files
There are many uses of included files. Some common ones are:
-
Factoring out common page elements, such as headers and footers. When the included file is modified, all pages that include it automatically update.
-
Separating functional sections of a page into separate files. This allows you to create a page design that consists of an overall framework, within which you "plug in" various pieces. By using includes, you can edit the pieces separately without affecting the overall design. This technique is analogous to splitting a large method into several smaller methods.
-
Conditionally building a page. You may put an
include
statement within an
If/Else/Endif
or
Case/Endcase
construct to conditionally include various files. This allows you to use the same page to display different output based on one or more criteria.
-
Using
include into
to build an HTML page to send via email.
Including only once
You can also include files using the
require
command. The
require
command works like
include
, but it guarantees that any given file will only be executed once via
require
within a single execution of the interpreter.
The
require
command is primarily useful for creating files of global constants, variables and methods that only need to be loaded once per Active4D session. All files that reference these globals can
require
the globals file and you don't have to worry about the overhead of executing the file or the problem of defining named constants twice, which is an error.
Calling 4D Methods
Although you can call 4D methods within Active4D, this ties you to the database structure, which is exactly what Active4D is designed to avoid. If possible, you should define and use methods within Active4D. For more information on defining methods in Active4D, see See Methods
-
There is a bug in 4D 6.5.7 and earlier that prevents 4D methods from being called from a process directly created by 4D's built in web server. This bug does not exist in 6.5.8+ or 6.7.
|
Nonetheless, should you need to, you can call any 4D method within Active4D using the exact same syntax you would within 4D.
Parameter Passing
When calling a 4D method from Active4D, you pass parameters just as you would within 4D. Strings are converted to
Text
and
Longints
are converted to
Reals
before being passed. You may return any type of value from the method.
-
If you are passing textual parameters to a 4D method from Active4D, the parameter in 4D must be declared C_TEXT. If you are passing numeric parameters, they must be declared C_REAL. Otherwise a runtime error may occur in a compiled database.
|
Active4D has no way of matching parameters passed to a 4D method with the actual parameters declared in that method. It is up to you to make absolutely sure that the number and type of parameters declared in the 4D method are compatible with what you pass to it. If the 4D method expects some parameters to be optional, you may of course not pass those.
In an interpreted database, if the method parameters are not assignment-compatible, 4D will initialize the parameter to a null value. In a compiled database, however, if the parameter types do not match exactly, a runtime error will be generated, which will effectively bring your application to a halt in a very unfriendly way. You do not want this to happen.
Indirect Method Calls (aka Poor Man's method pointers)
In addition to calling 4D methods as you would within 4D, by directly referencing the method name, you can also indirectly call a method by name using the
Call 4D method
command.
The syntax of this command is as follows:
|
Call 4D method(inMethodName {;inParam1 {;inParamN}})
|
The method name may be any valid expression that returns text. This powerful feature allows you to dynamically determine which of several methods you call, as long as their parameter lists are compatible. This is (sort of) the equivalent of a method pointer in other programming languages.
As with ordinary method calls, the method called by
Call 4D method
may return a value.
If the 4D method returns a value, you may ignore it if you have no use for it. You need not assign it to a dummy variable as you would in 4D. On the other hand, if the 4D method returns no value, attempting to use the result of such a method will result in an error.
Collections
Active4D adds a new data type to the language:
collections
. A collection is a group of
key/value pairs
which are stored in memory. The keys are strings (with a maximum length of 255) and the values may be any 4D data type, including arrays. The key/value pair is also referred to as an
item
.
In classic programming terms, a collection is also known as an associative array, a dictionary, a symbol table or a map. In 4D terms, you can conceptually think of a collection as two parallel arrays, with keys being in one array and the values in the other. Of course, you can't do this in 4D because 4D arrays can only contain a single type, and a collection value may be of any type.
Active4D provides a full suite of commands for creating your own collections. In addition, Active4D uses collections to store HTTP headers, query parameters, form variables, cookies, global variables, and sessions.
For more information on the collection commands, see See Collections.
Collection Handles
Collections are referred to by a
Longint
handle, much like an ObjectTools object handle or a 4D hierarchical list handle.
Active4D maintains an internal list of user-created collections. All collection commands that take a collection handle check the handle against this list and generate an error if the handle is not valid. Thus you are prevented from crashing the server by passing in a bogus handle.
Local vs. Global Collections
Collections can be either
local
or
global
. A local collection is automatically deleted when a script finishes executing. A global collection remains in memory throughout the life of the server.
Local collections are like local variables -- you use them for temporary storage within a single script. You should
always
use a local variable to store a local collection handle.
Global collections are like interprocess variables -- you store application-wide data in them. Typically you will create global collections in the
On Application Start
method and clear them in the
On Application End
method.
Using Collections
Collections come in two basic varieties:
read-only
and
read-write
. You can perform the following operations with read-only collections:
-
Get a collection value given a key. If the value is an array, you may retrieve an element of the array directly. Key matching is case-insensitive.
-
Get all keys into a 4D array.
-
Get all values into a 4D array if it is known they are all of the same type.
-
Get the count of key/value pairs in the collection.
Read-write collections add the following operations:
-
Set a collection value given a key. If the value is an array, you may set an element of the array directly.
-
Delete a collection item given a key. If the key contains a wildcard, all matching items are deleted.
In addition to these basic operations, some of the specialized collections defined by Active4D provide other operations as well. These operations are covered in the relevant command reference sections.
Referencing Collection Values
Active4D extends the syntax of the
{}
indexing operators to allow indexing a collection by keys. The syntax of this way of indexing is as follows:
where
collection
is either a collection handle or collection iterator, and
key
is a text expression. If an item in the collection exists with the given key, the result of this expression is the item's value, and it may be treated in all respects as a variable of that type. If no item exists in the collection with the given key, the result of the expression is an empty string.
Because the result of the expression is treated as the value it resolves to, you can use collections as a natural part of the language. For example:
|
`Set a counter in our session
session{"counter"} := 0
`Now increment the counter
++session{"counter"}
`Store a form variable in the session
session{"username"} := form variables{"f_username"}
`Embed an array in a collection
array string(255; $people; 0)
set array($people; "Tom", "Dick", "Harry")
$c := new collection
$c{"people"} := $people `puts a copy of $people array in collection
for ($i; 1; size of array($c{"people"}))
writebr("Hi " + $c{"people"}{$i})
end for
append to array($c{"people"}; "Louise")
|
Note in the example above that you put a copy of an array into a collection by directly assigning the array to a collection item, like this:
|
collectionRef{key} := arrayVar
|
You can even embed collections in collections (by storing their handles) to any depth and reference their items by adding more indexes, like this:
|
$foo := $c{"level1"}{"level2"}{"level3"}{"the_key"}
|
Iterating Over a Collection
Very often you may need to iterate over every item in a collection. There are two ways to do so in Active4D.
The first (and easiest) way to iterate over a collection is to use the
for each/end for each
loop control structure. For more information on
for each
, see See Iterators.
The second way to iterate over a collection is through an
iterator
. Every collection provides a command which returns an iterator for the collection. You use this iterator to traverse the items in the collection.
In addition, some collections allow you to get an iterator for a specific item given the item's key. If no item with the given key exists, you are given an
empty iterator.
An empty iterator is a special iterator that has the following properties:
-
The iterator itself (a
Longint
) is zero
-
is an iterator
will return
false
-
get item key
will return an empty string
-
get item value
will return an empty string
-
get item type
will return
Is Undefined
(5)
You can identify an empty iterator either by testing equal to zero, by calling
is an iterator
, by testing for an empty key, or by testing the item type.
For more information on iterators, see See Iterators.
HTTP Data Access
When Active4D is used as the web server, the interpreter has full access to both the HTTP request and the response data. This data is critical when developing high-powered web sites. The commands necessary to access this information are covered in See Command Reference
Request Data
As was discussed in See HTTP Server an HTTP request consists of several headers and an optional body, in addition to the requested URL itself.
The data encapsulated in an HTTP request includes:
-
Query string parameters
-
Form Variables
-
Cookies
-
HTTP headers
-
Uploaded files
In addition, information about the host environment is passed in to Active4D.
-
It is important to note that all of this data is encoded is some way or another. Without Active4D, to extract any meaningful information you would have to:
-
Understand the detailed HTTP specification and format for each type of data.
-
Write the code to parse and extract the data, making sure to follow the rules you learned in Step 1.
-
URL-decode the data which, according to the HTTP specification, should be URL-encoded.
-
Convert from the URL-decoded data from the ISO-8859-1 character set to the Mac Roman character set.
-
Figure out where and how to store the data in a meaningful way.
-
Write many methods to access that data in a simple way.
If you have never gone through this process, here's a little tip: the time it takes to do Step 1 alone will cost you more than the price of Active4D!
Fortunately Active4D does all of the above for you. You never have to deal with the particulars of the HTTP specification, which allows you to focus on the problem at hand -- building a great web site.
Auto Variable Creation
The primary way in which you "pass" parameters from one page to another in a web site is through form variables and query string parameters. Active4D places those parameters in easy-to-access collections.
For example, if the user posts a form which contains a field called "f_name" and you want to access the contents of that field, you can simply use the command:
|
get form variable("f_name")
|
Likewise, to access a query string parameter called "recnum", you could use:
|
get query param("recnum")
|
This is simple enough, but Active4D gives you an even easier way: auto-variable creation.
By default, the interpreter automatically creates a local text variable for every form variable and query string parameter in the HTTP request. If there are multiple form variables or query parameters with the same name -- which is the normal occurrence if more than one item is selected from a multiple choice form list -- a text array is created which contains all of the values.
For example:
-
If a form is posted with a field called "f_name" and the user enters the text "John Doe", Active4D will create a local text variable
$f_name
whose contents is the text "John Doe".
-
If a form with a multiple-choice list called "f_experience_level" is posted with the selected items "Beginner" and "Advanced", Active4D will create a local text array
$f_experience_level
with two elements that contain the text of the selected items.
This feature allows you to conveniently access form variables and query string parameters as if they were "passed" to your script as named method parameters.
Testing Form Buttons
If a submit button is clicked on a form, the browser posts the button's form name and value. Buttons which appear on a form but are not clicked are not included in the posted form data.
Frequently you need to test a posted form to see which button was clicked. For example, your form may have "Search", "Previous" and "Next" buttons. There are two ways to test which button was clicked. The first way is to check the form variables collection. If a button was clicked, it will be in the collection and its value will be returned. If the button was not clicked, it will not be in the collection and an empty string will be returned. Using this technique, your code would look something like this:
|
Case of
:(get form variable("f_search") # "")
`Do the search
:(get form variable("f_previous") # "")
`Go to the previous group of records
:(get form variable("f_next") # "")
`Go to the next group of records
End case
|
Because Active4D only creates local variables for fields that are posted, a variable will only be created for the button that was clicked. Thus you can also use the
defined
command to test which button was clicked, like this:
|
Case of
:(defined($f_search))
`Do the search
:(defined($f_previous))
`Go to the previous group of records
:(defined($f_next))
`Go to the next group of records
End case
|
Response Data
You control the response body indirectly with the
write
command and its peers. In addition, Active4D gives you dedicated commands for setting the response headers.
The data encapsulated in an HTTP response includes:
-
Cache control
-
Character set
-
Content type
-
Cookies
-
Expires date
-
Other headers
Some HTTP response headers are simple in their format. Others require a specific format which you must follow. As with the request headers, without Active4D you would have to know the HTTP specification for each format. For those headers that require special formatting, Active4D gives you simple commands that relieve you of having to know the HTTP specification.
Working with Character Sets
Text comes into Active4D from several sources:
String literals
-
These may be in the native platform charset (if you are using a text editor) or ISO-8859-1 (if you are using an HTML editor).
Database
-
4D uses the Macintosh Roman charset internally and expects text to be in this charset.
HTTP requests
-
Query string parameters and form variables are URL encoded and may be in any charset.
Files
-
Text files may be in any charset. It is up to you to know which one.
Text can go out from Active4D to several destinations:
Web browser
-
Text sent to the browser via the
write
commands should be in the target HTML charset, usually ISO-8859-1 (Latin1). In addition, you may need to HTML-encode reserved characters such as `<'.
Database
-
4D expects the Macintosh Roman charset.
Files
-
You can use whatever charset you want.
Clearly, it would be a real pain -- not to mention error-prone -- if you had to remember to do all of the character set conversions yourself. Fortunately, Active4D allows you to configure the various charsets and then takes care of most of these conversions for you.
Internally Active4D uses the Macintosh Roman charset, since that is what 4D expects. The character sets you configure determines which charset Active4D converts
from
on input and which charset it converts
to
on output.
Platform Character Set
The platform charset determines what charset Active4D converts
from
when parsing string literals. When converting from a Roman language charset, characters are converted to Macintosh Roman. When converting from a non-Roman charset, no conversion is performed.
For example, if you are using BBEdit on the Mac to write your embedded scripts, string literals would be in Macintosh Roman. On the other hand, if you are writing your scripts with Dreamweaver, string literals would be in the charset of the page you creating.
You can set the platform charset with the "platform charset" config option in
Active4D.ini
. The possible options are "mac", "win", "latin1", "ISO-8859-1", "shift_jis" or "gb2312". Note that "latin1" and "ISO-8859-1" are equivalent. You may also use the
set platform charset
command.
On a Roman language system, the default platform charset is the native charset for the platform on which Active4D is running ("mac" or "win"). On a Japanese language system, the default platform charset is "shift_jis". On a Chinese language system, the default platform charset is "gb2312".
Output Character Set
The output charset determines what charset Active4D converts
to
when text is written to the response buffer. If the output charset is a Roman language charset, it is assumed text is always converted
from
Macintosh Roman. If the output charsest is a multibyte charset, no conversions are performed.
You can set the output charset with the "output charset" config option in
Active4D.ini
. The possible options are the same as for the platform character set. You may also use the
set output charset
command.
The default output charset on Roman language systems is
ISO-8859-1
, which is the default charset for HTML. The default output charset on Japanese language systems is
Shift_JIS
. The default output charset on Chinese language systems is
GB2312
.
Output Encoding
The output encoding determines how Active4D converts special characters to HTML character entities when text is written to the response buffer. Output encoding is performed
before
the output character set conversion, since the encoding tables are based on the Mac Roman character set.
You can set the output encoding with the "output encoding" config option in
Active4D.ini
. You specify one or more bit flags to indicate which characters to encode. More than one flag can be specified by separating them by `+' and any number of spaces. The bit flags are "none", "quotes", "tags", "ampersand", "extended", "html" and "all" (without the quotes). Note that "extended" and "html" are synonymous.
You may also use the
set output encoding
command at runtime. For more information on output encoding, see See set output encoding.
The default output encoding on Roman language systems is "html". The default output encoding on Japanese language systems is "none".
HTTP Request Decoding
When parsing an HTTP request, the headers are left as is. This is not a problem, since all headers except cookies will be in US ASCII and the character set is not an issue.
Query string parameters and form variables are automatically URL decoded, and the name portion of their name/value pairs is converted from ISO-8859-1 to Macintosh Roman.
If the platform charset is a Roman charset, query string parameter and form variable
values
are converted from ISO-8859-1 to Macintosh Roman. If the platform charset is a multibyte charset (like Shift_JIS), no conversion is performed.
Working with Files
Active4D cannot know the source platform of a file or its charset. It's up to you to know the charset used by a file, then convert to the appropriate character set when saving to the database or writing to the browser.
You can convert between character sets using
Win to Mac
,
ISO to Mac
and
Mac to ISO
.
Error Handling
Active4D goes to considerable lengths to catch errors and display meaningful error messages. If any errors occur during the execution of an Active4D program, execution is immediately aborted and the error handler takes over.
For complete information on error handling within Active4D, see See Error Handling
Script Timeout
Despite our best intentions, sometimes our scripts may do bad things like going into infinite loops or waiting an inordinate amount of time for a shared resource.
Every script is given a set amount of time to execute. Before executing each line, Active4D checks to see if the timeout has been reached, and if so it generates an error and aborts execution.
You may set the script timeout with the "script timeout" config option in
Active4D.ini
. The value set with this option is the
minimum
script timeout in seconds and is the default value for all subsequent script executions.
The actual timeout can be set higher within Active4D with the
set script timeout
command. This command will affect the
next
execution of Active4D, not the one in which the command is used, and in no case can it be set lower than the minimum value set in
Active4D.ini
.
Reference Manual
