{websage.i SET SERVICE serviceName}
{websage.i SET STYLE styleName}
/* optional, if not using the primary style */
{websage.i SET FONT fontName}
/* optional, if not using the primary font */
{websage.i SET FUNCTION functionName}
X = {websage.i VALIDATE_LOGIN_ID}
/* and test the results and handle it */
.....
In order to do anything useful, you are eventually going to need to write text out to the client/browser. The identifier to support this is {&WRITE}. {&WRITE} preceeds a list of expressions that will be sent to the client browser. Each expression is seperated from the next by a space. You can have as many expressions as you want per line, though the total number of characters on a line can't exceed your -inp limit (usually 8192 characters).
You should break the line up with physical line breaks as well as line breaks in the actual written text/HTML. While a browser will easily handle a single continuous line of nearly any length and properly format it, it's very difficult from a debugging standpoint to use the "View Source" feature of most browsers if the source is on one big line. The {&SKIP} synbol can be inserted as logical places in the list of written expressions and has no affect on the final, formatted HTML - just the source.
A sample of writting HTML is:
{&WRITE}
{html.i PAGE_HEADER "'My Page'"} {&SKIP}
{html.i BODY_START} {&SKIP}
{html.i PARA_START} {&SKIP}
{html.i BOLD "'Here I am!'"} {&SKIP}
{html.i BODY_END} {&SKIP}
{html.i PAGE_FOOTER} {&SKIP}.
An older form of {&WRITE}
is {&OUT}. {&OUT} is deprecated and has performance
problems. All {&OUT} uses should be changed to {&WRITE}.
You'll note that {&OUT} lines use a plain SKIP to break
up lines and when converting to {&WRITE}, you'll need to convert
all SKIP's to {&SKIP}.
SET SERVICE servicename
Sets the service name for the application. You must call this AFTER the RESET_CONTEXT
call and before you make any other calls. 'servicename' is the name of the applications
service. When you set a service, the primary style for that service is automatically
loaded and the primary font for the style is automatically loaded.
SET STYLE stylename
Sets the style name to be used for all further HTML tag invocations. By default,
the primary style is automatically selected when the service name is specified.
Changes to the stylename persist through the transaction until another SET STYLE
call is made.
SET FONT name
Sets the font to be used for most font orietend operations. The passed font
name must be defined as a known font for the currently set style. If the passed
font name is not know, WebSage will revert to the primary font for the current style.
SET FUNCTION functionname
Sets the function (or program) being executed. This should be done immediatly
after the SET SERVICE call. The functionname becomes a discriminator for future
calls that are function specific. Each major part of the service/application
should have a seperate functionname.
SET TARGET_KEY theKey
Sets the key that is associated with the current login session. The key is often
a unique identifier of the person or thing that the current session is focused
on (i.e. a student ID for a student based app).
(returns CHARACTER) GET SERVICE
Returns the name of the currently loaded service. If no service has been selected,
it returns ?
(returns LOGICAL) GET SERVICE_ONLINE
Returns TRUE if currently selected service is considered online and available.
Returns FALSE if the service is considered off-line or if no service has been
selected yet.
(returns CHARACTER) GET STYLE
Returns the name of the currently set style. There is always a style loaded
after a call to SET SERVICE, so this will never return a blank or ?.
(returns CHARACTER) GET FONT
Returns the name of the currently set font. There is always a font loaded after
a call to SET SERVICE or SET STYLE, so this will never return a blank or ?.
(returns CHARACTER) GET LOGIN_ID
Returns the current unique session login identifier. This identifier has no
meaning othe than being guaranteed unique. This is only valid after a call to
CREATE_LOGIN or VALIDATE_LOGIN_ID.
(returns CHARACTER) GET SESSION_ID
Returns the current unique session identifier. This identifier has no meaning
other than being guaranteed unique. This is only valid after a call to CREATE_LOGIN
or VALIDATE_LOGIN_ID.
(returns CHARACTER) GET NEW_SESSION_ID
Returns a new session ID for qualifying a fresh login session. This should only
be used before the login process and would later be passed to CREATE_LOGIN.
Once a session is logged in, use GET SESSION_ID to find that sessions identifier.
(returns CHARACTER) GET TARGET_KEY
Returns the target key value associated with this session. This key value usually
related to the "target" of the application (i.e. a student ID in a student application).
It's available only after a call to CREATE_LOGIN or VALIDATE_LOGIN_ID.
(returns CHARACTER) GET FUNCTION
Returns the function name, as set last by SET FUNCTION.
(returns CHARACTER) GET LOCAL_PATH
Returns the actual, O/S level path to the root of the WEB server directory tree.
Using this function, you can turn any URL/Web directory/path into an absolute
path which can then be used for operations in PROGRESS (like SEARCH, INPUT FROM,
OUTPUT TO, etc). You should never embed or send a reference to the web client
with this path in it as the client will not be able to access a file at this
location (since the location is hidden under the web server). You would typically
concatenate the results of this with the results of another call like GET IMAGE_PATH
and possibly a file spec. Unlike the other PATH related services, this will
return a path that does not end in a slash (/) (which is exactly what you'd
want if you are concatenating this with other paths).
(returns CHARACTER) GET BASE_PATH
Returns the path of the 'root' of this services directory tree. Note that the
tree is entirely within the Web servers space, not in the WebSage application
space. This is only available after the SET SERVICE call has been done. The
returned string will always be terminated with a directory slash (/), allowing
simple file/directory concatenation.
(returns CHARACTER) GET IMAGE_PATH
Returns the path to the service/application images directory. This directory/path
is in the Web Server space, not in the WebSage application space. This is available
only after a call to SET SERVICE. The returned string will always be terminated
with a directory slash (/).
(returns CHARACTER) GET HTML_PATH
Returns the path to the service/applications static HTML pages diretory. The
directory/path is in the Web Server space, not in the applications/WebSage space.
This is only available after a call to SET SERVICE. The returned string will
always be terminted with a diretory slash (/).
(returns CHARACTER) GET DISTRICT_PATH
Returns the path to the service/applications district specific HTML and images
dirretory. The directory/path is in the Web Server space, not in the applications/WebSage
space. This is only available after a call to SET SERVICE. The returned string
will always be terminted with a diretory slash (/).
(returns CHARACTER) GET PROG_PATH
Returns the path to the root of the applications program space. This directory
path, unlike the others, is in the WebSage/application space, NOT in the Web
Server space. This is only available after a call to SET SERVICE. The Returned
string will always be terminated with a directory slash (/).
(returns CHARACTER) GET CUSTOM_HTML
htmlfile
This will take the passed HTML file and return the file qualified with either
the DISTRICT_PATH or the HTML_PATH prefixed on it. The DISTRICT_PATH is checked
for the files existance first. If it doesn't exist there, then the HTML_PATH
is checked. If it doesn't exist in either place, the unmodified htmlfile is
passed back as the result.
(returns CHARACTER) GET CUSTOM_IMAGE
imagefile
This will take the passed image file and return the file qualified with either
the DISTRICT_PATH or the IMAGE_PATH prefixed on it. The DISTRICT_PATH is checked
for the files existance first. If it doesn't exist there, then the IMAGE_PATH
is checked. If it doesn't exist in either place, the unmodified htmlfile is
passed back as the result.
(returns CHARACTER) CREATE_LOGIN
sessionID
Will cause a new login session to be created with the specified session ID.
If the session ID has been used before, the attempt to login will fail. You
MUST set the TARGET_KEY before calling this function. If any previous
login/session was active, it is replaced with this completely new login. You
should execute this function only one per login/session. If a new login is created
successfully, OK is returned.
(returns CHARACTER) VALIDATE_LOGIN_ID
[loginid]
This will attempt to reload a login/session configuration based on a login/session
identifier. 'loginid' is optional. If not supplied, the WebSage services will attempt
to auto-extract that value from the form variables (this is the preferred method
to login). If you do supply a 'loginid', it is used instead. If the supplied
loginid is invalid (does not describe a known user), INVALID is returned. If
the loginid describes a session that has expired from inactivity, then EXPIRED
is returned. Otherwise, if the loginid is valid OK is returned.
(returns CHARACTER) TERMINATE_LOGIN_ID
[loginid]
This call will terminate the a login session. Any further attempt to use the
login session will result in an error. 'loginid' is optional. If not supplied,
the WebSage services will attempt to auto-extract the value from the form variables.
This is the prefered method to terminate a login.
SET SERVICE_ATTR attrname
attrvalue
Set a service level attribute with the passed name and value. The attribute
is available to any executing program under the current service name. This is
used mostly so that services can read run-time configuration data in, though
rarely they may actually save other info. Remeber that attributes affect all
instances of the given service.
SET FUNCTION_ATTR attrname
attrvalue
Set a function/program level attribute with the passed name and value. The attribute
is available to any program which has the same SET FUNCTION name. This is used
mostly so that Programs can read run-time configuration data in, though rarely
they may actually save other info. Remeber that attributes affect all instances
of the given function.
SET TARGET_ATTR attrname attrvalue
[function]
Set a target level attribute with the passed name and value. The attribute is
available to any program which has the same SET TARGET_KEY value. This is used
mostly so that data about a specific target (i.e. employee, student) can be
maintained. Unlike the SERVICE_ATTR and FUNCTION_ATTR, these are frequently
read and written. Remember that these attributes affect all instances that are
using or will use the same target key. If an optional "function" parameter is
specified, the attribute will be specific to that passed function. Otherwise,
the attribute is expected to be part of the currently set function.
SET LOGIN_ATTR attrname attrvalue
[function]
Set a login/session level attribute with the passed name and value. The attribute
is generally only available to the session that creates it and is deleted when
that session is terminated. The primary use of LOGIN_ATTRs is maintaining information
about the current session between pages. If an optional "function" parameter
is specified, the attribute will be specific to that passed function. Otherwise,
the attribute is expected to be part of the currently set function.
(returns CHARACTER) GET SERVICE_ATTR
attrname
Returns a service level attribute value. If the attribute doesn't exist, an
empty string is return. See SET SERVICE_ATTR for more info on this attribute
type.
(returns CHARACTER) GET FUNCTION_ATTR
attrname
Returns a function level attribute value. If the attribute doesn't exist, an
empty string is return. See SET FUNCTION_ATTR for more info on this attribute
type.
(returns CHARACTER) GET TARGET_ATTR
attrname [function]
Returns a target level attribute value. If the attribute doesn't exist, an empty
string is return. See SET TARGET_ATTR for more info on this attribute type.
If an optional "function" parameter is specified, the attribute will be specific
to that passed function. Otherwise, the attribute is expected to be part of
the currently set function.
(returns CHARACTER) GET LOGIN_ATTR
attrname [function]
Returns a login/session level attribute value. If the attribute doesn't exist,
an empty string is return. See SET LOGIN_ATTR for more info on this attribute
type. If an optional "function" parameter is specified, the attribute will be
specific to that passed function. Otherwise, the attribute is expected to be
part of the currently set function.