Possibilities - Stupid QAL Tricks 2/92

Contact:   eSoft, Inc. (Makers of TBBS)
           15200 E. Girard Ave., Suite 3000
           Aurora, CO  80014
           (303) 699-6565      Voice
           (303) 699-6872      Fax
           (303) 699-8222      BBS
           support@esoft.com   E-Mail

STUPID QAL TRICKS 2/92
----------------------

*** From February 1992 Possibilities Newsletter ***
*** Copyright 1992 by eSoft, Inc.  All Rights Reserved ***

Stupid QAL Tricks
by Alan Bryant

One of the most significant and useful new features of the new TBBS 2.2 
release is the Question and Answer Language, or QAL.  This keyword based 
script language for developing questionnaires is a major advancement over 
what it replaced:  QAEDIT, the questionnaire editor which has been part of 
TBBS since its inception over 10 years ago.  Each month this column
describes ways you can use QAL to do things you may not have though possible 
with TBBS. 

Since this is the first QAL column, let's begin with a review of what is new 
in QAL as contrasted with the QAEDIT questionnaires TBBS has had for years. 
Some of the major new capabilities QAL provides include:

  o Greater flexibility in user presentation

  o Input field types for format checking of input

  o Variables for input storage and comparison

  o Full formatting of survey output file

  o Ability to change many common user settings

  o Full-screen ANSI/VT-100 input screen "forms" 

There are many additional QAL features and they all add up to an incredibly 
powerful questionnaire capability for surveys and voting functions.  Now 
let's get on with how to solve problems with QAL.

Storing Information to the Userlog

In the past TBBS users employed many third-party utilities such as EILEEN to 
take information gathered in questionnaires and store it to the userlog 
notes field.  With QAL questionnaires can store user input directly to the 
caller's userlog record.  The advantages are clear ... the updates happen 
instantly (instead of waiting until an external event is run at a later 
time).  You can also design the QAL script to store just the information you 
need in just the format you want it stored.

This functionality is based around the QAL CHANGE: command.  The CHANGE: 
command allows the QAL script to modify any one of several fields in the 
caller's userlog record.  The CHANGE: command acts only on the record of the 
user who is responding to the questionnaire.  In other words a QAL 
questionnaire cannot change another user's record.

Let's study an example of storing a product serial number to the NOTES field 
of the userlog.  You could easily modify this questionnaire script to store 
virtually any short information you wish.

Q&A: SERIAL
CLEAR:
BLOCK: ANSI
GET:
Hello, and welcome to the Foobar, Inc. Support Bulletin Board.

We need to have your product type and serial number on file in order 
to provide support services to you through this system.

What is your product type? ~
TYPE=STRING LENGTH=20 MIN=5 VAR=A

GET:
What is your product serial number? ~
TYPE=STRING LENGTH=10 MIN=8 VAR=B
ENDBLOCK:

CHANGE: NOTES="%A% - %B%"
ENDQ&A:

Let's examine how this simple QAL script works.  The GET: command accepts 
user input after explaining what is being asked for (the trailing tilde 
character (~) causes the cursor not to advance to the next line).  The 
product type input is stored in variable "A" and the serial number is stored 
in variable "B".  Note: The BLOCK: ANSI / ENDBLOCK: causes this input to be 
done in a full screen mode if the caller's terminal program can handle ANSI 
sequences, and automatically revert to a line-by-line mode if the caller's 
terminal will not handle ANSI.  This feature of QAL allows you to easily 
create dual purpose input structures.

Once they have been input and placed in the variables "A" and "B", the 
CHANGE: command then stores the user's values directly to the NOTES field of 
the caller's userlog record.  This is possible because the CHANGE: NOTES 
command accepts a string, so quotation marks are used to indicate the 
boundaries of the string.  Since insertion parameters are always expanded in 
any text string in a QAL questionnaire, %A% and %B% expand to the user's 
input values as stored in variables "A" and "B".

For example, if a user typed "WindowMaster" as the product type, and 
"12345678" as the serial number, then the following would be stored to the 
NOTES field:

WindowMaster - 12345678

Note the spaces and a hyphen which came from our quote string to see how you 
can format data in the QAL script itself.  The string stored to the NOTES 
field could be formatted any way you wish, as long as it's not too large for 
the field itself.  The NOTES field can accept a maximum of 63 characters.

The use of insertion parameters to create formatted output strings based on 
user input is one of the most powerful capabilities QAL provides.  As you 
read this column over the next few months you will see this capability used 
over and over in many powerful ways.

Forcing Change of Expired Password

Another new feature of TBBS 2.2 is the ability to set time intervals for the 
expiration of users' passwords.  Setting this up causes TBBS to display a 
warning at logon telling the user to change their password.  But what if you 
want users to be FORCED to enter a new password once it's expired?  Enter 
QAL!

This QAL example shows the use of insertion parameters within your QAL 
script.  In this case, we're using %PWDEXP% the parameter which returns an 
indicator of whether or not the user's password has expired.  Its flow is 
similar to our previous example of storing information to the NOTES field.

This questionnaire needs to be run automatically sometime after logon.  
Although you could put it many places on your system, to ensure its running 
you can add an auto-executing menu entry on your top-level menu.  (Auto 
execution is discussed in Chapter 9 of the TBBS 2.2 manual, on page 9-7.)

When it is executed this questionnaire determines whether the user's 
password has expired.  If it has not expired the questionnaire exits 
immediately.  Otherwise it forces the user into a password change routine.

Here is the QAL source code for the PASSEXP questionnaire:

Q&A: PASSEXP
IF: "%PWDEXP%" = "X"
CLEAR:
BLOCK: ANSI
GET:
PASSWORD EXPIRATION ALERT!

Your password has expired.  You will need to select a new one. Carefully 
consider your new password choice and REMEMBER IT!  You will need 
it to logon to this system as of your next call!

Please enter a new password: ~
TYPE=STRING LENGTH=8 MIN=2 VAR=A
ENDBLOCK:
CHANGE: PASSWORD=%A%
ENDIF:
ENDQ&A:

As you can see, the PASSEXP questionnaire script is extremely simple.  It 
first checks to see if %PWDEXP% is equal to an "X" (if the password is NOT 
expired %PWDEXP% will equal ".").  If it does equal "X" then this QAL 
questionnaire prompts the user (with explanation) to enter a new password 
which it stores to the "A" variable.  A CHANGE: command is then issued to 
replace the password with the contents of the "A" variable.  That's all 
there is to it!

As you can see from these examples, using QAL is fairly simple. We encourage 
you to use and extend these examples in any way you wish.  The more you use 
QAL, the more familiar you will become, and the easier it will get.  For 
system designers who've been with TBBS for some time, you'll notice that QAL 
is very similar in structure and operation to SDL, and it's every bit as 
flexible and easy to use. 

In future issues, we'll be bringing you more "Stupid QAL Tricks".  If you 
have any suggestions for this column, let us know.

- END -
PS0292-4
Rev. 2/92

Copyright (C) 1994 eSoft, Inc., All Rights Reserved.  Permission granted
to distribute this file in its entirety, without modification, to any
interested party.  Any other use requires the written permission of
eSoft, Inc.

IMPORTANT:  The information herein is subject to change without notice.
Please call or write to confirm factual information of importance to you
or your organization.

