Introduction
PowerWeb Server++ Macro Syntax
PowerWeb Server++ Macro Reference
Begin
Tells the browser that HTML3 will be used.
Config
Customises error messages and date and number formatting.
Copyright
Outputs the PowerWeb copyright notice.
Create
Creates a new PowerWeb variable.
Destroy
Destroys an existing PowerWeb variable.
Dir
Display an FTP-like directory listing.
Echo
Outputs form parameters, the contents of CGI variables, PowerWeb configuration settings, or runtime variables.
Elif
Implements the next condition in the equivalent of a C language switch...case command.
Else
Outputs the block if the condition in the If command was FALSE.
End
Closes off the HTML body and document.
Endif or /if
Defines the ending point of an If/Else/Endif conditional block.
Exec
Executes an API, Rexx, or CGI script or an operating system program.
FSize
Outputs the size of a file.
FLastMod
Outputs the date and time of last modification of a file.
If
Defines the start of a conditional block.
Include
Include another file into the current document.
Input
Displays a populated input field.
List
Displays a table suitable for editing a list of items.
Redirect
Redirect the client's browser to another URL.
Set
Defines a new value for a variable.
Table
Displays a table suitable for editing multiple records and fields.
PowerWeb Server++ Macros have access to the PowerWeb Server++ internals that manage requests, connections, services, configuration and performance information, across all protocols, not just HTTP.
This level of power and richness of functionality cannot be found on any other Web server today.
PowerWeb Server++ Macros can:
Serve Different Documents According to the Client's Browser or Host Name
Validate Form Data Entry Without Writing CGI Programs
Process Forms Without Writing CGI Programs
Use Templates to Simplify Document Creation
Can Boldly Take You Where Noone Has Been Before!
An example with a start and end tag:
<!--#if @connection:/RemoteHost?"*.widget.com" -->An example with a single tag:
This server is not allowed to show you this document.
<!--#/if -->
<!--#echo format=escaped var=request:/header/in/referer -->Here "echo" is the macro name, while "format" and "var" are attributes.
These variables can be accessed from PowerWeb Macros as well as API hooks, and support both read and write access, according to the permission settings assigned to them.
The following logical "Drives" are defined within PowerWeb Server++:
Examples:Config: This is the Configuration database drive. All the server configuration settings, performance statistics and security rules are stored here. You may like to Browse Your Configuration Settings to familiarise yourself with what is available.
Server: This is a dynamic drive that refers to the current Server being used to service the current request. It is therefore an alias of one of the "Config:/Servers/" directories, and allows easy access to the settings of the current server.
Connection: All settings specific to the current Connection, such as the authenticated user name, remote host name, TCP/IP status, etc are stored here.
Request: Within a single user Connection, there may be many Requests. For example, within an FTP Server, each command sent to the Server is treated as a Request within the current Connection. Each Request has its own directory system that contains all settings and details specific to that Request. Settings which are common across all Requests are stored on the Connection drive.
Argument: When an API hook is called, it is passed a set of Arguments specific to the type of API hook. For example, a Decode Hook is given arguments of the data block, the encryption method, and the variable in which to place the decrypted data. All these Arguments are stored in the Argument drive for easy access. Full multi-threading is supported through each API Hook having its own private Argument drive.
Parameter: When an API hook is called, it can be passed a set of constant Parameters that further tell it what action to take. These Parameters are defined in the Configuration settings and an alias to these is stored in the Parameter drive.
Config:/Version
The version number of the software in use.
Server:/Stats/Clients
The number of clients currently using this server.
Request:/Header/Out/Content-type
The MIME content type of the reply to the current HTTP request.
<!doctype html public "-//IETF//DTD HTML 3.0//EN"><html>which informs the browser that the document will make use of HTML 3.0 tags, as well as declaring the start of the document.
Attributes:
errmsg = (text)
The (text) defines the new error message to display when a macro encounters an error, such as a syntax error or a variable not found error.
timefmt = (format)
A format string to use when display dates with the FLastMod macro. This format string is compatible with the C runtime library strftime function, allowing the following special sub-format specifications:a
abbreviated weekday name
A
full weekday name
b
abbreviated month name
B
full month name
d
day
H
24 hour
I
12 hour
m
month
M
minute
S
second
w
weekday 0-6, Sunday=0
x
date representation
X
time representation
y
2 digit year
Y
4 digit year
%
percent
sizefmt = (format)
A format string to use when display dates with the FSize macro. The allowed formats are "bytes" and "abbrev". "Bytes" shows the size as a comma-thousands-separated count of bytes, and "abbrev" shows the size as a number of "K" (kilobytes), "M" (megabytes) or "G" (gigabytes).
Company = (text)
The name of the company.
Mail = (text)
The e-mail address of the contact at the company.
URL = (text)
The Web Home Page for the company.
Attributes:
Parent = (variable)
The directory in which to create the variable. If no parent is given, then "request:/argument" is assumed.
Name = (text)
The name of the variable to create.
Type = (type)
The type of variable to create, with the default being "text".It Can Be One Of:
Text
A sequence of printable characters ending in a null (0) character. The maximum length is 2 gigabytes, subject to virtual memory constraints.
Integer
A 4-byte (32 bit) signed integer.
Float
An 8-byte (double precision) signed floating point number.
Binary
A sequence of bytes that may contain embedded null (0) characters. The maximum length is 2 gigabytes, subject to virtual memory constraints.
List
A directory of other variables. There is no limit to the number of hierarchy levels.
Value = (text)
The initial value to assign to the variable. If this attribute is absent, the variable is given a null value.
Live = (yes/no)
Whether to create the variable in the live configuration, or in the parallel copy used for editing purposes.
Attributes:
(path)
The full path to the variable to be deleted.
This PowerWeb Macro is more powerful in that you have full control over what files are displayed, as well as their format and surrounding text above and below the directory listing.
Attributes:
file = (wildcard pattern)
The files that you wish to see listed.
virtual = (wildcard pattern)
The virtual URLs on your site that you wish to see listed.
Fancy = (yes/no)
Default is TRUE.
IncludeDirectories = (yes/no)
Default is FALSE.
IconsAreLinks = (yes/no)
Default is FALSE.
ScanHTMLTitles = (yes/no)
Default is FALSE.
SuppressDescription = (yes/no)
Default is TRUE.
SuppressLastModified = (yes/no)
Default is FALSE.
SuppressSize = (yes/no)
Default is FALSE.
Attributes:
Var = (path or CGI variable)
The full path of the PowerWeb Server++ variable to be displayed, or the name of an NCSA CGI variable. Usage of CGI variables is discouraged because of their higher overhead and lesser functionality.
NotFound = (text)
The text to display if the variable is not found.
Format = (text)
The only format currently supported is "escaped" which allows the variable to be used within a generated URL.
Attrib = (type)
Specifies that variables in any following conditional attributes will be evaluated according to the given attribute type.Valid Attribute Types Are:
Value
The value of the variable.
Size
The size of the variable, 0 if it is empty.
Name
The name of the variable.
Path
The full directory path name of the variable.
Live = (yes/no)
If Live is YES, it specifies that the currently active live configuration is to be used, otherwise the copy of the configuration that is currently being edited is used. The default is YES.
</body></html>which informs the browser that the document is complete.
Attributes:
cmd = (executable program)
Executes an operating system executable program or built-in command, which takes no keyboard input. The program output is displayed in the document.
cgi = (CGI script)
The CGI script is a URL specifying the CGI program to run. Any headers output by the CGI script are ignored, because the headers of the current document take precedence.
api = (module!function)
The API script is a URL specifying the API library module and function to run. Refer to the API reference manual for more information.
rexx = (module)
The Rexx script is a URL specifying the Rexx command module to run. The Rexx script has full access to the PowerWeb APIs, so it can query or set variables, perform validation, output customised text, etc. Refer to the API reference manual for more information.
Attributes:
file = (filename)
The filename path is relative to the current directory of the original HTML document.
virtual = (local URL)
The URL specified must be local to the current server and is specified in the same way as a normal local document hyperlink reference within an HTML document.
Attributes:
file = (filename)
The filename path is relative to the current directory of the original HTML document.
virtual = (local URL)
The URL specified must be local to the current server and is specified in the same way as a normal local document hyperlink reference within an HTML document.
The structure of IF/ELIF/ELSE/ENDIF is as follows:
<!--#if (conditions 1) -->The If and Elif macros contain conditional attributes which are evaluated to TRUE or FALSE to determine whether to include the block of HTML into the document.
HTML to output if the "if" conditions are true.
<!--#elif (conditions 2) -->
HTML to output if the "elif" conditions are true.
<!--#elif (conditions 3) -->
HTML to output if the next "elif" conditions are true.
<!--#else -->
HTML to output if the "if" and all the "elif" conditions are false.
<!--#endif -->
Optional attribute attributes can be included to refine the evaluation of the conditional attributes.
Specification Attributes:
Conditional Attributes:And
The conditions that follow are combined with AND. The first condition that evaluates FALSE, causes the entire IF condition to evaluate FALSE.
Or
The conditions that follow are combined with OR. The first condition that evaluates TRUE, causes the entire IF condition to evaluate TRUE.
Attrib = (type)
Specifies that variables in any following conditional attributes will be evaluated according to the given attribute type.Valid Attribute Types Are:
Value
The value of the variable.
Size
The size of the variable, 0 if it is empty.
Name
The name of the variable.
Path
The full directory path name of the variable.
Live = (yes/no)
If Live is YES, it specifies that the currently active live configuration is to be used, otherwise the copy of the configuration that is currently being edited is used. The default is YES.
All conditional attributes can start with an optional '!' character which reverses the condition.
Examples:Defined = (variable)
Evaluates to TRUE if the specified variable exists.
Empty = (variable)
Evaluates to TRUE if the specified variable does not exist, or if its contents are empty or NULL.
Var = (variable)
Evaluates to TRUE if the specified variable exists and its contents evaluate to TRUE.
@(variable) (condition) (value)
Evaluates the expression where (variable) can be any PowerWeb variable, (value) can be a constant or a reference to any PowerWeb variable, and (condition) is one of:=
Tests for equality.
<
Tests less than.
>
Tests greater than.
?
Tests whether the (value) can be found by a text search within the (variable). If (value) contains any wildcard characters (? or *), then a regular expression match is performed.
File = (wildcard pattern)
Evaluates to TRUE if any file exists on your site that matches the specified wildcard pattern.
Virtual = (wildcard pattern)
Evaluates to TRUE if any local URL exists on your site that matches the specified wildcard pattern.
0
Evaluates to FALSE.
1
Evaluates to TRUE.
Test for Correctly Filled-in Forms
<!--#if or empty=LastName empty=FirstName -->
You did not fill in the FirstName or LastName field on the form.
<!--#endif -->Tests whether the form fields FirstName and LastName were entered, and, if not, includes an error message in the document returned to the user.
Take Different Actions According to Form Fields
<!--#if @Pizza=Pepperoni -->
You ordered a Pepperoni pizza.
<!--#elif @Pizza=Hawaiian -->
You ordered our house speciality, the Hawaiian pizza.
<!--#else -->
There is no pizza named <!--#echo var=Pizza --> on our menu.
<!--#endif -->Displays which pizza the user ordered, with an error message if the user ordered a pizza which is not on the menu.
Return Different Documents or Messages According to Domain or IP Address
<!--#if @connection:/RemoteAddress?"12.34.56.*" -->
You are on our private network.
<!--#elif @connection:/RemoteHost?"*.widget.com" -->
You are on the widget.com domain.
<!--#else -->
This server is not allowed to show you this document.
<!--#endif -->This example illustrates how you can return different documents or messages according to the domain or IP address from which the user accesses your server. Access control rules within the server configuration can also be used to prevent unauthorised access.
Attributes:
file = (filename)
The filename path is relative to the current directory of the original HTML document.
virtual = (local URL)
The URL specified must be local to the current server and is specified in the same way as a normal local document hyperlink reference within an HTML document.
Attributes:
var = (directory)
The name of a PowerWeb Server++ variable directory which contains the list of allowed options.
name = (text)
The name to give to the HTML input field.
type = (text)
The type of data entry field to use, currently only listboxes and comboboxes are supported.
size = (number)
This is the number of data items to display without scrolling. A value of 1 results in a combobox, and a larger number results in a listbox which uses scrollbars only if the number of options exceeds the value given here.
live = (yes/no)
Whether to look for the directory in the live configuration, or in the parallel copy used for editing purposes.
Attributes:
var = (directory)
The name of a PowerWeb Server++ variable directory which contains the list of variables to edit.
mode = (text)
The mode determines whether the table is read-only or editable. Use "input" for an editable table, and "browse" for a read-only table.
live = (yes/no)
Whether to look for the directory in the live configuration, or in the parallel copy used for editing purposes.
Attributes:
virtual = (url)
The full URL to redirect the client's browser to.
Attributes:
(path) = (value)
The attribute name specifies the full path to the variable to be modified. The attribute value gives the new value to be assigned into the variable.
Attributes:
var = (directory)
The name of a PowerWeb Server++ variable directory which contains the list of variables to edit.
free = (number)
The Free attribute determines how many blank records are presented for creating new records at the end of the table. A value of 0 prevents the creation of new records.
mode = (text)
The mode determines whether the table is read-only or editable. Use "input" for an editable table, and "browse" for a read-only table.
live = (yes/no)
Whether to look for the directory in the live configuration, or in the parallel copy used for editing purposes.
colX = (text)
Defines the contents of the column numbered X in the table. If the (text) includes a colon, then all text prior to the colon is used as a column heading, and the remaining text defines the name of the field in the record to display.
colX_edit = (text)
Defines whether column X may be edited and whether it must be filled in when creating new records.Legitimate Edit Modes Are:
No
The column is read-only.
Yes
The column is always allowed to be edited.
Auto
Determines whether the column is editable according to the variable's permission settings.
Required
The column is always allowed to be edited and must be filled in before a new record will be accepted.
OneOf
The column is always allowed to be edited and it, or another column also marked OneOf, must be filled in before a new record will be accepted.
Link
The column is read-only in this table, but hyperlinks to another data entry screen for editing.
colX_width = (text)
Defines the number of characters to specify as the input field width in column X.