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

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

A User Information System

With TBBS 2.1, many system designers were accustomed to using a third-party 
program titled SVY2INX.  This program took the .SVY questionnaire output 
file, and formatted an output file for use with the Type 20 keyword search 
database function in TBBS.  Two features new to QAL and TBBS 2.2 make this 
program unnecessary:

1.  TBBS 2.2 allows full filename designation for the Type 20 command -- you 
no longer are forced to use the "family.INX" convention for a single file.  
This allows you to directly search the .SVY questionnaire output file 
without renaming it.

2.  QAL allows full control over the .SVY output file formatting.  This 
allows you to directly format the .SVY file output from your QAL 
questionnaire to be suitable for use with a Type 20 keyword search.

In this example, we'll develop a questionnaire to collect some common user 
information.  We will make an entry in our TBBS menus so that this 
questionnaire will be auto-executed once when the user is new, then never 
executed again.  You could also make this part of a "staged registration" 
technique, an example of which is shown on page 9-27 of the TBBS manual.  

As new users log onto the system over time, the .SVY questionnaire output 
file will grow and provide a searchable user database.  

Here's our sample TBBS 2.2 QAL questionnaire:

Q&A: USERDATA
CLEAR:
BLOCK: ANSI
GET:
Our system maintains a database of users that you and other users 
can search online.  Please complete the following so that we may add 
your information to the database.

What city and state are you calling from? ~
TYPE=STRING LENGTH=30 VAR=A

GET:
What is your age? ~
TYPE=STRING LENGTH=3 VAR=B

SHOW:
Thanks for your participation!
ENDTEXT:
PUTSVY: "%NAME% %A% %B%"
ENDQ&A:

Through the use of the QAL PUTSVY: command, the .SVY output file from this 
questionnaire will be formatted for direct use by a TYPE=20 text search 
command.  Each user response will be on a single line in the file and that 
will allow the Type 20 keyword search function to operate as we wish.

Note: If you have a need to manually add or edit entries in a .SVY file, you 
must exercise some caution.  Many word processors and text editors will add 
explicit EOF (^Z) characters to the file.  This will make it appear that new 
questionnaire responses weren't added since they will follow the  EOF 
character and thus be ignored.  Use a programmer's text editor, such as 
QEDIT or other editor which does not add this EOF mark to your text in the 
file.

Note: The auto-execute menu command which calls this questionnaire (using 
the TYPE=32 menu command) is created by setting the KEY=^@ and setting 
proper PRIV and FLAG settings for new users.  Auto-execute menu commands are 
explained on page 9-7 of your TBBS manual and also in the "Understanding How 
it Works" guide.

Detecting User Capabilities

Many times new users don't understand how to answer some of the system 
prompts when they're setting up their terminal parameters.  QAL 
Questionnaires can be used to "hand-hold" the user through the process of 
selecting terminal options, and to make setup modifications as well.

One of the most commonly mis-configured settings is ANSI.  What follows is a 
questionnaire which "tests" the users ANSI capabilities, and modifies the 
setting based on user responses to the test.

Q&A: TESTANSI
IF: %CANANSI% = "X"
  CLEAR:
  SHOW: "Our system has detected you"
  SHOW: "are capable of supporting"
  SHOW: "ANSI color and cursor cmds."
  SHOW: ""
  SHOW: "Would you like to use ANSI to"
  GET:  "enhance your display (Y/N)? ~"
    TYPE=HOTKEY  VAR=Z  VALID="YyNn"
  IFCASE: %Z% = "Y"
    CHANGE: ANS=X
  ENDIF:
ELSE:
  CHANGE: ANS=X
  SHOW: "^[[01;37;40m^[[H^[[2J~"
  CLEAR:
  SHOW: "The following is a test of your capabilities"
  SHOW: "to use ANSI color:"
  SHOW: ""
  SHOW: ""
  SHOW: "^[[01;37;41m *** ^[[44m ***^[[01;37;40m"
  SHOW: ""
  SHOW: ""
  SHOW: "Are the above asterisks in"
  GET:  "different colors (Y/N)? ~"
    TYPE=HOTKEY  VAR=Z  VALID="YyNn"
  IFCASE: %Z% = "Y"
    CHANGE: ANS=X
  ELSE:
    CHANGE: ANS=.
  ENDIF:
ENDIF:
QUIT:
ENDQ&A:

ANSI is a defined set of escape codes that allow you to implement color and 
cursor control, and enable the use of the full-screen message editor and 
full-screen mode of questionnaires.  However, in order for them to perform 
the task you want (and not just look like garbage to the caller) the 
caller's terminal program must have ANSI terminal emulation capability (See 
Chapter 1 -- ANSI support in your TBBS manual for details of ANSI code 
operation).  Often the caller will no know if his terminal program can do 
this or not -- that's where this QAL questionnaire comes in.

The secret to the operation of this questionnaire is the %CANANSI% insertion 
parameter.  When a user logs on TBBS 2.2 automatically performs a poll of 
the user's terminal software to determine if it is capable of handling ANSI 
extended formatting codes.  If this poll detects that the user has an ANSI 
capable terminal program then %CANANSI% will return a single letter "X".  If 
the poll does not get a response indicating ANSI capability, then %CANANSI% 
will return the single letter ".".  This test is the heart of the logic in 
this questionnaire, and results in using the CHANGE" command to set ANS=X or 
ANS=. as desired.

This questionnaire is excerpted from a more complete version named 
CHKANSI.QAL, which is available for download from the eSoft Support BBS.  To 
obtain the full QAL questionnaire log onto the support BBS and from the top 
level menu select iles.  Then select the area for TBBS 2.2 files.  You'll 
see CHKANSI.QAL listed there.  Feel free to modify and use this 
questionnaire in any way you wish.

Next month, we'll discuss how you can use QAL to tap into TBBS 2.2's new 
address fields to maintain user information.

- END -
PS0492-4
Rev. 4/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.

