Possibilities - Stupid QAL Tricks 7/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 7/92
----------------------

*** From July 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. 

Using the Userlog as a Simple Database

In past "Stupid QAL Tricks" columns, we've introduced you to the power of 
QAL and its ability to store data in the userlog.  In this issue, we bring 
you a more advanced example of how to store and use data in the userlog.

Before we begin, however, it's important to understand that questionnaires 
can manipulate data ONLY in the record of the user running the 
questionnaire.  In other words, if I'm a user named JOHN DOE, and I run 
respond to a questionnaire, only MY user data (that of John Doe) can be 
retrieved or modified by the questionnaire. 

Further, the data which you can manipulate is limited to the following 
userlog data fields: privilege level, access flags, IBM and ANSI settings, 
screen (page) length, screen width, time left on the current call, location, 
notes, password, upper case and linefeed settings, address, city, state, 
ZIP, phone and country. No other fields can be changed by QAL 
questionnaires.  You can READ and DISPLAY other fields, however, simply by 
using insertion parameters (discussed in Chapter 2 of the TBBS manual).

This article will focus on the use of the address fields in the userlog.  
These new fields, made available with the release of TBBS 2.2, are actually 
general purpose text data storage fields.  Although they are intended for 
the storage of address information, you could use them to store virtually 
any type of information you like.  Keep that in mind when reviewing this 
example.

Here is a sample QAL file that will allow a caller to enter and/or update 
the information in his name, address, and phone number userlog fields.

Q&A: DATABASE
; Store initial values 
; for use if updating
SET: A=%NAME%
SET: B=%ADDR1%
SET: C=%ADDR2%
SET: D=%CITY%
SET: E=%STATE%
SET: F=%ZIP%
SET: G=%PHONE%
; Begin prompting block
BLOCK: ANSI UPDATE
GET: What is your name? ~
     TYPE=STRING VAR=A LENGTH=30
GET: What is your address (line 1)? ~
     TYPE=STRING VAR=B LENGTH=30
GET: What is your address (line 2)? ~
     TYPE=STRING VAR=C LENGTH=30
GET: What is your city? ~
     TYPE=STRING VAR=D LENGTH=20
GET: What is your state? ~
     TYPE=STRING VAR=E LENGTH=2
GET: What is your ZIP code? ~
     TYPE=STRING VAR=F LENGTH=5
GET: What is your phone number? ~
     TYPE=STRING VAR=G LENGTH=5
ENDBLOCK:
; Write changes to userlog
; Name they entered is stored to 
; NOTES field for reference
CHANGE: NOTES="%A%" ADDR1="%B%"
        ADDR2="%C%" CITY="%D%"
        STATE="%E%" ZIP="%F%"
        PHONE="%G%"
ENDQ&A:

This example is clearly biased to United States systems; it could easily be 
modified to accommodate other geographical areas.  It's important to 
remember that the userlog field names (ADDR1, CITY, STATE, etc.) are for 
reference purposes only -- you can store any data there you wish.  The only 
limitation is that these fields (ADDR1, ADDR2, CITY, STATE, ZIP, PHONE and 
COUNTRY) can have an accumulated total of no more than 121 characters.  It 
is therefore important to control the length of the entered strings as shown 
in the example by using the LENGTH= keyword.

Note that when several CHANGE: fields are desired at the same time that they 
may be placed on either separate CHANGE: commands or on a single CHANGE: 
command.  It is more efficient to place them all on a single CHANGE: 
command.  This is because the userlog image is re-written to disk with each 
CHANGE: command that modifies it.  In this example the userlog record is 
written only once instead of multiple times as it would be if all changes 
were not on one command.

Retrieving the Information

Once this data is written to the userlog, however, how do you access it?  
eSoft does not provide tools for accessing the address data in the TBBS 2.2 
release.  As a result you will need to use a third-party application 
program, such as the shareware program ALOG, to access and/or modify this 
data.  ALOG also includes features such as mailing label printing that 
allows you to make the userlog a convenient database for personal user data.  
ALOG and other utilities are available for download from the eSoft Support 
BBS (see the back cover for details on how to call the Support BBS).

What if you wanted select portions of the entered data to be written to the 
survey output file so as to make it searchable via a Type 20 keyword search 
function?  That's an easy addition to the above example.  Replace the line 
"ENDQ&A:" with the following:

PUTSVY: "%NAME% %D%, %E%"
ENDQ&A:

This simple change would write a file named DATABASE.SVY which can then be 
linked to a Type 20 menu entry.  This would allow users to search a list of 
users who've answered the questionnaire.

There are many other possibilities for this basic questionnaire, storage and 
output mechanism.  Feel free to experiment with other uses of this 
capability on your own until our next QAL Tricks session.

- END -
PS0792-5
Rev. 7/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.

