## PowerWeb Macros

### No CGI Required! - Works with ALL Web Browsers!

PowerWeb Server++ Macros let you create dynamic documents with unprecedented ease and power, without having to program in CGI or any other complex programming language. PowerWeb Macros are an extension to the HTML tags, and work with all Web browsers.

## Table of Contents

> Introduction

> PowerWeb Server++ Macro Syntax

> PowerWeb Server++ Variables

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

## Introduction

PowerWeb Macros allow the HTML document author to create dynamic documents that closely integrate with the PowerWeb++ server, without coding in CGI.

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!

## PowerWeb Server++ Macro Syntax

The syntax of PowerWeb Macros is based on the familiar HTML tag syntax, while remaining compatible with current and future versions of HTML.

### PowerWeb Macro Mime Type

All documents that contain PowerWeb Macros should be assigned a Mime type of text/x-server-parsed-html. A simple way of ensuring this is to use the Macro Security Template instead of the Default Security Template. This template automatically defines all .htm, .html, .inc and .nxt files as containing PowerWeb Macros.

### Understanding PowerWeb Macros

In PowerWeb Macro documents, tags define the start and end of macros. Most PowerWeb Macros are identified in a document as a single tag which gives the macro name and attributes. A few macros, such as conditional blocks, require a start and an end tag. Single and start tags are delimited by `<!--#` and `-->`, and end tags are delimited by `<!--#/` and `-->`.

An example with a start and end tag:

> `<!--#if @connection:/RemoteHost?"*.widget.com" -->
> This server is not allowed to show you this document.
> <!--#/if -->`

An example with a single tag:

> `<!--#echo format=escaped var=request:/header/in/referer -->`

Here "echo" is the macro name, while "format" and "var" are attributes.

### Macro Names

The macro name immediately follows the tag open delimiter. An element name consist of a series of letters. Names are not case sensitive. For example, IF is equivalent to if.

### Attributes

In a single or start tag, white space and attributes are allowed between the macro name and the closing delimiter. An attribute typically consists of an attribute name, an equal sign, and a value (although some attributes may be just a name). White space is allowed around the equal sign. The value may be contained within quotes.

## PowerWeb Server++ Variables

PowerWeb Server++ variables are organised into several logical "Drives", each of which consists of a hierarchy of "Directories" which in turn contain "Settings" variables.

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

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

Examples:

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

## PowerWeb Server++ Macro Reference

This section is an alphabetically listed reference manual for each of the PowerWeb Server++ Macros.

### Begin

Outputs the following HTML code:

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

### Config

The Config macro allows for overriding the default error message, the default date and time format, and the default file size format.

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

### Copyright

Outputs a copyright message including links to the company's Web Home Page and e-mail contact address. Attributes:

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

### Create

Create a new PowerWeb Server++ variable. If the variable already exists, it is overwritten, unless write permission has been denied.

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.

### Destroy

Removes an existing PowerWeb Server++ variable. The variable must have delete permission set for this macro to succeed.

Attributes:

> (path)
> The full path to the variable to be deleted.

### Dir

Outputs a directory listing in the same format as the dynamic directory indexing facility which is accessed when a user specifies a directory on your site, without mentioning a document name.

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.

### Echo

Displays the contents of a PowerWeb Server++ variable, or a CGI variable (for backwards compatibility).

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.

### Elif

The Elif macro is only used in conjunction with IF and ENDIF.
Read the documentation on IF for more details.

### Else

The Else macro is only used in conjunction with IF and ENDIF.
Read the documentation on IF for more details.

### End

Outputs the following HTML code:

> `</body></html>`

which informs the browser that the document is complete.

### Endif or /if

The Endif macro is only used in conjunction with IF.
Read the documentation on IF for more details.

### Exec

The Exec macro executes an API, Rexx or CGI Script or Operating-system Executable Program and includes its output within the HTML document.

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.

### FSize

Outputs the size of a file or document, using the current size format specification (which can be changed by the Config macro). This macro is typically used in conjunction with an HTTP or FTP link to download a file.

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.

### FLastMod

Outputs the date and/or time of the last modification of a file or document, using the current date and time format specification (which can be changed by the Config macro). This macro is typically used in conjunction with an HTTP or FTP link to download a file.

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.

### If

The If macro defines the start of a conditional block. The block is ended by an Endif or /If macro, and can optionally contain multiple Elif macros and a single Else macro.

The structure of IF/ELIF/ELSE/ENDIF is as follows:

> `<!--#if (conditions 1) -->
> 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 -->
> `

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.

Optional attribute attributes can be included to refine the evaluation of the conditional attributes.

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

Conditional Attributes:

All conditional attributes can start with an optional '!' character which reverses the condition.

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

Examples:

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

### Include

The Include macro substitutes the contents of the specified file or document into the current document. This macro is extremely useful when used in conjunction with the IF macro because it allows conditional display of documents according to a variety of conditions, such as the name or host machine of a user, or the contents of a form that has been submitted.

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.

### Input

Displays a data entry field which is automatically populated with a list of valid data items.

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.

### List

The List macro presents an HTML table that is suitable for editing a list of PowerWeb Server++ variables all contained in the same directory.

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.

### Redirect

Redirects the client's browser to a specified URL, which may be on any site. This PowerWeb Macro is useful within conditional blocks to display documents according to conditions. If the documents are local to your site, the use of the #Include PowerWeb Macro is more efficient.

Attributes:

> virtual = (url)
> The full URL to redirect the client's browser to.

### Set

Defines a new value for an existing PowerWeb Server++ variable. The variable must have write permission set for this macro to succeed.

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.

### Table

The Table macro presents an HTML table that is suitable for editing a list of PowerWeb Server++ variables all of the same type. The editable table supports deletion, creation, modification and re-sequencing.

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.