Videotex Server Page Specification

The Carapace Videotex Server uses a page specification to define the layout of data on the Videotex page -- click here for an example.

A page specification is built from the following elements:

page name the page name uniquely identifies this page amongst all pages for the Videotex service

input fields defines the input fields, treating the Videotex page as a form to hold the user's input

pre-processing defines the pre-processor run when before this page is generated -- for example, this could access a remote server etc.

output data contains the sequence of commands which generate the data to be sent down the Videotex client

validation defines page-specific validation to perform on the user-supplied data

post-processing defines the post-processing function which takes the attribute-value list of field data entered by the Videotex user and takes whatever action is appropriate -- e.g. store in a database.
The name of the next page to process by the Server is returned.

inputFields

The inputFields page element defines all the input fields. An input field is defined as follows:

field name - name used for the field e.g. abtaNumber, destination
row - screen row number to hold this field
column - screen column to hold the start of this field
length - length of the field
action - validation expression for the field data when received from the user
depth - depth of the field (i.e. no. of rows)
dataType - type of data held in the field
prompt - expression to generate the prompt for the field

pre-processing

Defines the pre-processor trigger run before this page is generated -- for example, this could access a remote server to setup the data for the page.

If the pre-processor is a Symbol then it must be the name of a Carapace script trigger function.

Any other non-() value is taken to be an expression to evaluate in a restricted environment.

outputData

The outputData page element holds the list of page commands which generate the Videotex to be sent to the user. Each page command is itself a list where the command is the first element and any required arguments follow.

validation

Defines page-specific validation to perform on the user-supplied data.

If the validation expression is a Symbol then it must bbe the name of a Carapace script trigger function. In addition, this trigger function must return a String.

Any other non-() value is taken to be an expression to evaluate in the restricted environment.

If the resultant string is not empty, it is treated as an error message to display to the user and the Server does not leave the current page.

post-processing

Defines the post-processor run when the user has completed this page -- for example, this could access a remote server or store the values in a database etc.

If the post-processor expression is a Symbol then it must bbe the name of a Carapace script trigger function. In addition, this trigger function must return a String which is the name of the next page to display.

Any other non-() value is taken to be an expression to evaluate in the restricted environment. This evaluation must return a String.

Page Commands

The following page commands are understood by the Carapace Videotex Server:

up move the cursor up by the supplied no. of rows

down move the cursor down by the supplied no. of rows

left move the cursor left by the supplied no. of characters

right move the cursor right by the supplied no. of characters

text output the supplied text to the user

blockText output the supplied block of text to the user -- the width of the block and any display attributes can also be supplied

moveTo move to the supplied screen co-ordinate

home move the cursor to the initial row and column without changing the screen contents

attribute send the supplied display attribute

attributes send the supplied display attributes

mosaic send the supplied mosaic graphic

table present a table of values

up command

Move the cursor up by the supplied no. of rows -- the default no. of rows is 1.

E.g.:

    (up)
    (up 4)

down command

Move the cursor down by the supplied no. of rows -- the default no. of rows is 1.

E.g.:

    (down)
    (down 4)

left command

Move the cursor by the supplied no. of characters to the left -- the default no. of characters is 1.

E.g.:

    (left)
    (left 4)

right command

Move the cursor by the supplied no. of characters to the right -- the default no. of characters is 1.

E.g.:

    (right)
    (right 4)

text command

Output the supplied text to the user.

E.g.:

    (text "Enter your password")

    (text (pageData.get "userName"))

The second example above illustrates the output of the userName as filled in by a pre-processor function.

blockText command

Output the supplied block of text to the user -- the width of the block and any display attributes can also be supplied. Multiple text strings can be supplied.

E.g.:

    (blockText 20 fgRed fgToBg fgBlue  
        "This is a large amount of text which the"
        "server will split into lines of less than"
        "20 characters and display on the screen using"
        "the supplied attributes for each row"
    )

The second example above illustrates the output of the userName as filled in by a pre-processor function.

moveTo command

Move to the supplied screen co-ordinate.

E.g.:

    (moveTo 3 4)

home command

Move the cursor to the initial row and column without changing the screen contents.

E.g.:

    (home)

attribute command

Send the supplied display attribute. The supplied attribute must be one of the following:

fgRed
fgGreen
fgYellow
fgBlue
fgMagenta
fgCyan
fgWhite
flashOn
flashOff
singleHeight
doubleHeight
mosaicRed
mosaicGreen
mosaicYellow
mosaicBlue
mosaicMagenta
mosaicCyan
mosaicWhite
bgBlack
bgFromFg
mosaicOn
mosaicOff

E.g.:

    (attribute fgRed)

attributes command

Send the supplied display attributes -- click here for the allowed attribute values.

mosaic command

Send the supplied mosaic graphic -- the graphic is defined by a binary string where "abcdef" represents the following picture:

    ab
    cd
    ef

table command

Display a formatted table of data at the supplied position. A format for the fields within each row is supplied -- this defines the field with, justification (left or right), whether to pad with zeroes or spaces and whether the value is integer, real or string. Optional foreground and background colours for the fields can also be supplied.

The table syntax is as follows:

    (table  nRows  rowFormat  data)

where:

nRows is an Integer giving the number of rows to display
rowFormat is a String which defines the layout of each row -- this is a comma-separated sequence of field format strings where the field format defines:
1. layout
2. foreground (text) colour -- optional
3. background colour -- optional
data is an expression which returns a List of row data where each row data is itself a List of String, Integer or Real values.

For example, consider the following table statement:

    (table 5 
           "%12s,Red;%10s,Blue" 
           (::db.sql "select firstName, lastName from user")
    )

Here, the ::db variable is assumed to be a Db database connection. The row format is a sequence of field format strings each separated by semi-colons.

Each field format is obeys one of the following patterns:

dataFormat
dataFormat,foregroundColour
dataFormat,foregroundColour,backgroundColour

The colours are taken from the following list: Red, Green, Yellow, Blue, Magenta, Cyan, White

The data format is constructed as follows:

percentage sign %
(optional) plus/minus sign to indicate justfication:

+ right justified -- the default

- left justified
integer giving the field length -- if this number has a leading zero, the formatted output will be zero padded, otherwise a space character is used
letter which defines the data type as follows:

d integer -- printed as a decimal

x integer -- printed in hex with lower case letters

X integer -- printed in hex with upper case letters

f floating point number (real)

s string

The following are valid String data formats:

    %8s
    %-12s

The following are valid Integer data formats:

    %08d
    %-4x

Trigger Functions

All trigger functions for the Videotex server take the following arguments:

page VideotexServerPage the definition of the current page

environment HashTable an environment for this session presented to each page function

pageData HashTable an empty table into which this function can put the initial field values to be presented to the user

helper Object a helper object which persists for the lifetime of the Videotex session

Evaluation Environment

Expressions which are evaluated -- e.g. in page or field validation, page triggers etc. -- are done so in a very restricted environment. This environment has the following variables defined:

expr Object the expression to evaluate

page VideotexServerPage definition of the current Videotex page

environment HashTable an environment for this session presented to each page function

pageData HashTable table of values presented to or extracted from the user

helper Object a helper object which persists for the lifetime of the Videotex session

Initialisation & Termination

The following script functions can be defined to create and destroy a 'helper' object for the Videotex session -- for example, this could be a connection to a remote system:

    # initialise the connection
    (function Object vtServerInitialise ( (config HashTable) ) )

    # terminate the connection
    (function NIL vtServerTerminate ( (helper Object) (config HashTable) ) )

The value returned by vtServerInitialise is made available in each evaluation environment as the helper.

Contents Current topic: videotex Related topics: Carapace Hub

page name	the page name uniquely identifies this page amongst all pages for the Videotex service
input fields	defines the input fields, treating the Videotex page as a form to hold the user's input
pre-processing	defines the pre-processor run when before this page is generated -- for example, this could access a remote server etc.
output data	contains the sequence of commands which generate the data to be sent down the Videotex client
validation	defines page-specific validation to perform on the user-supplied data
post-processing	defines the post-processing function which takes the attribute-value list of field data entered by the Videotex user and takes whatever action is appropriate -- e.g. store in a database. The name of the next page to process by the Server is returned.

`up`	move the cursor up by the supplied no. of rows
`down`	move the cursor down by the supplied no. of rows
`left`	move the cursor left by the supplied no. of characters
`right`	move the cursor right by the supplied no. of characters
`text`	output the supplied text to the user
`blockText`	output the supplied block of text to the user -- the width of the block and any display attributes can also be supplied
`moveTo`	move to the supplied screen co-ordinate
`home`	move the cursor to the initial row and column without changing the screen contents
`attribute`	send the supplied display attribute
`attributes`	send the supplied display attributes
`mosaic`	send the supplied mosaic graphic
`table`	present a table of values

`d`	integer -- printed as a decimal
`x`	integer -- printed in hex with lower case letters
`X`	integer -- printed in hex with upper case letters
`f`	floating point number (real)
`s`	string

`page`	`VideotexServerPage`	the definition of the current page
`environment`	`HashTable`	an environment for this session presented to each page function
`pageData`	`HashTable`	an empty table into which this function can put the initial field values to be presented to the user
`helper`	`Object`	a helper object which persists for the lifetime of the Videotex session

`expr`	`Object`	the expression to evaluate
`page`	`VideotexServerPage`	definition of the current Videotex page
`environment`	`HashTable`	an environment for this session presented to each page function
`pageData`	`HashTable`	table of values presented to or extracted from the user
`helper`	`Object`	a helper object which persists for the lifetime of the Videotex session

`+`	right justified -- the default
`-`	left justified