Tim Berens is president of Back Office Applications, Inc., a contract software house. He can be reached at 1250 W Dorothy Ln., Ste. 301, Dayton OH 45409.
The first time I heard of storing data in tables, it seemed completely unnecessary. Drawing on my full two weeks of programming experience, I came to the conclusion that arrays were just too much work.
Since that rather premature conclusion, I have found arrays to be one of the most useful tools for handling large quantities of data. I remember drawing a similarly premature conclusion when I first heard about an underused feature of the C language -- arrays of pointers to functions.
A pointer to a function contains the starting address of a subroutine. Just like a character pointer points to a character in memory, a function pointer points to a function, which can be executed using the pointer. A function executed in this way performs exactly the same as a function executed using a standard call. Arguments can be passed to it, and a value can be returned from it.
A function pointer by itself can be a handy tool, but it takes on a great deal more significance when stored with others in an array. We call such an array a "procedure table."
A procedure table is a powerful tool for software design. It is a method of storing procedures (functions and subroutines) in a table so that the stored data can be accessed by using a numeric offset. This gives you a method for systematically controlling procedures, as in a loop, for example.
To illustrate the use of procedure tables, I have chosen a task that I have had to tackle in many systems and one that I have always found particularly cumbersome. At some point, a program usually prompts the user for a series of responses in order to gather parameters. These parameters may be used as query criteria for a report, for narrowing down a potential problem, as input for a graph, and so on.
Gathering these parameters is complicated by the validation of the responses, and by multiple possible paths through the prompts. For example, if the first prompt asks the user if a report is to be printed for a single account, a range of accounts, or all accounts, the second prompt depends on the user's response. If the second and third prompts get the starting and ending account numbers for a range, the program must validate that the ending account number is larger than the starting account number. This goes on ad nauseam.
It always bothered me to take the obvious approach to this problem. Gathering the parameters in this manner resulted in a mass of nested if/else phrases. This type of code is difficult to read and maintain and is not reusable. Procedure tables provide a better way.
prompter( )
Listings One and Two illustrate prompter( ). The goal of prompter( ) was to develop a reusable routine that prompts a user, validates responses, and performs actions based on those responses. prompter( ) must be able to handle unique validations and multiple paths through the dialog. It does this by executing functions stored in a procedure table, which is implemented as an array of data structures.
The basic building block of prompter( ) is the data structure question, which is declared as:
struct question {
char * text;
char * response;
int (*validate)( );
int (*doit)( );
int (*set)( );
};
The application that calls prompter( ) defines one or more arrays of this structure. prompter( ) loops through the array(s) of structures according to the algorithm shown in Example 1. Let's look at each member of question in detail.
Example 1: Looping through an array
loop{
display current_question->text
get response from user
execute current_question->validate
if (no error on validate){
execute current_question->doit
}
copy response to current_question->response
execute current_question->set
if (error from validate){
call error handler
}
}
- question.text is the text of the prompt, such as "Do you want this report for one account, a range of accounts, or all accounts?"
- question.response is a pointer to the variable that receives the user's response. This allows prompter( ) to gather the parameters needed by the application. If question.response is set to NULL, prompter( ) assumes the application no longer needs the response and throws it away.
- question.validate is the address of the routine that validates the response. For example, it may check to see that the account number entered is valid. If an error occurs, the function returns a unique non-zero code, and the error is handled downstream by the handle_error( ) routine.
- question.doit is the address of the routine that will perform the action, if any, associated with this question. For example, it might convert an ASCII account number to an integer and store it in the appropriate variable.
- question.set is the address of a routine that determines what the next question will be. It can tell prompter( ) to go on to the next question in the array or to jump to a new array of questions, depending on the response given by the user. For example, if the user requests a report for a range of accounts, this routine will tell prompter( ) to ask the questions stored in the range_of_accounts array. If an error was encountered, the routine can tell prompter( ) to ask the current question again, or to back up and restart the questions at a previous point in the array.
After each function executes, it returns a status code that indicates if it was successful. prompter( ) uses this value to route control to the error handler if an error is encountered.
prompter( ) makes no decisions about which question structure to use as its basis for prompting the user. The application defines the arrays of question structures, and it is responsible for deciding what their contents are and the order they will be in.
Several routines are provided to simplify this job. These routines are called by the set member of question (question.set( )), which decides what the next question will be based on the response given by the user.
The prcontrol Structure
The prcontrol structure is the master control structure for prompter( ). It contains all information regarding the current state of the prompting. A pointer to this structure is passed to every function called from prompter( ). This allows the functions to examine and modify the current state of prompter( ).
The prcontrol structure is declared:
struct prcontrol {
int current_question;
struct question * current_group;
int group_stack_ptr;
char response[121];
int errstat;
struct errormess * errormess;
}
Let's look at each member in detail:
- prcontrol.current_question is the offset of the current question in the array of question-data structures pointed to by prcontrol.current_group. prcontrol.current_question is set to zero on entry to prompter( ) and is typically incremented by question.set in order to go on to the next question.
- prcontrol.current_group is a pointer to an array of question structures. This is the group of questions that is currently being asked.
- prcontrol.group_stack_ptr is a part of the mechanism that allows prompter( ) to jump easily from one array (or group) of questions to the next. This permits prompter( ) to follow multiple paths through the prompts. See the discussion of multiple paths later in this article.
- prcontrol.response is a buffer for holding the response entered by the user.
- prcontrol.errstat is the error status returned from question.validate( ) or question.doit( ). Typically this value is examined by question.set( ) before deciding what route to tell prompter( ) to take. It is also passed to handle_error( ) to display the proper error message.
- prcontrol.errormess is a pointer to an array of errormess structures. This pointer is passed to handle_error( ) when an error is encountered so it can display the proper error message.
Multiple Paths
The ability to follow multiple paths is handled through the use of a stack, which is implemented as an array of group_stack structures.
The group stack enables prompter( ) to jump to another group of questions without losing its place. It operates in a way similar to the stack in a C or assembler program.
When a question.set( ) routine decides it must jump to another array of questions, it calls the routine start_group( ). start_group( ) calls push_group( ) to push prcontrol.current_group and prcontrol.current_question onto the group stack.
When this group of questions is finished executing, a question.set( ) routine calls end_group( ). end_group( ) calls pop_group( ), which pops prcontrol.current_group and prcontrol.current_question off of the group stack. end_group( ) then increments prcontrol.current_question to continue at the next question, past the point where the other group of questions was called.
This method allows a group of questions to start another group of questions, which can start another group of questions, and so on, and prompter( ) can still easily return to the point at which it started.
Error Handling
Wouldn't computer programs be much easier to write if we could assume that users never make mistakes? But of course we cannot assume this, so prompter( ) has an error handling mechanism.
Any time an error is encountered by question.validate( ) or question.doit( ), the routine that detects the error returns a unique, non-zero value to prompter( ). This value is saved in prcontrol.errstat( ). The routine in question.set( ) then decides how this error will effect the direction of the questions.
This error status is then passed to the routine handle_error( ), whose responsibility is to build and display the proper error message. handle_error( ) works with an array of struct errormess. This array is declared:
struct errormess{
int errstat;
char * message;
int (*build)( );
};
errormess.errstat is the value that identifies the error, and errormess.message is the message that appears when this error is encountered. errormess.build is the address of the function that will perform any extra formatting of errormess.message. For example, if the error ACCOUNT_NOT_IN_FILE is encountered, this routine might turn the message Account %s not in file into "Account 101 not in file."
The application program defines an array of these structures. When handle_error( ) is called, it searches through this array until it finds a match. When a match is found it executes errormess.build if errormess.build is not NULL. Then it displays the message.
Is This Too Much Work?
Before we dig into a specific example, let me try to address a question that many will have. Yes, this is too much work to go through to ask two questions. But this is not too much work to go through to ask 200 or even 20 questions.
A method like this produces real savings in development time. The reason is that system prompts occur in patterns. For example, a system we recently developed had about 20 reports. Each report required that the user specified an output destination: printer, screen, or disk. The disk selection requires additional entry of a filename. If the file exists, the user has the option of overwriting that file, choosing a new file or appending the report to the file.
The savings in development time is realized after the printer, screen, or file procedure tables have been built and the routines coded for the first time. At this point, all routines become data that is fed to prompter( ). Any program that needs to access this particular series of questions as a part of its prompts simply calls start_group( ) from one of its question.set routines to start this group of questions. The printer, screen, or file prompts appear on the screen and when they have completed, the prompts go on from where they left off. The programmer never again has to worry about this series of prompts.
As the number of this type of pattern of prompts increases, the value of prompter( ) as a development tool increases. prompter( ) can be even used to do a rudimentary form of reasoning by having it chew its way through a series of prompts from a user. It will eventually reach a conclusion.
A Specific Example
The example I have chosen to illustrate prompter( ) is a series of prompts that gathers parameters for a mythical account report. The parameters that must be gathered are:
- The account query criteria -- the account number or range of accounts to be included.
- The display parameter's record that is to be used.
- Should the Over/Short report be printed automatically?
- The report destination: printer, screen, or disk.
You can see the flow of the prompts by reading the initialization of this array. Let's look at the initialization of the first member in detail:
account_parms[0].text points to "Do you want this report for a single account or a range of accounts? (S or R)." This text will be displayed when the user is being prompted.
account_parms[0].response points to single_or_range (which is an array of char). The response entered by the user will be copied here so the report program knows if the report is to be for a single account or a range of accounts.
account_parms[0].validate is set to the address of the routine account_or_range_val( ). This routine will make sure that the response is S or R. If not, account_or_range_val( ) returns the error status ENTER_S_OR_R and handle_error( ) prints the appropriate error message.
account_parms[0].doit is set to the address of no_op( ). This routine does nothing but return(O);. no_op( ) is used as a place holder, because no doit action is required for this prompt. It is necessary because prompter( ) will execute the function specified in account_parms[0].doit, so a function address must be stored there.
account_parms[0].set points to account_or_range_set( ). This function determines if the user entered S, R, or an erroneous response. If an error occurred, account_or_range_set( ) does nothing. This will cause the question "Do you want this report for a single account or a range of accounts? (S or R)" to be asked again. If the user entered S, account_or_range_set( ) starts the group that requests the single account number. If the user entered R, account_or_range_set( ) starts the group that requests the range of account numbers.
As you look through the code in Listing Two, you will see calls to several functions that assist with control of flow. These functions include:
- start_group( ), which starts a new group of questions.
- end_group( ), which ends the current group of questions. It calls pop_group( ) to restore the prompting to its previous state.
- checkerror_next_question( ), which causes prompter( ) to go on to the next question unless an error was encountered.
- checkerror_end_group( ), which ends the current group of questions unless an error was encountered.
- restart_group( ), which restarts the current group of questions.
As you develop more and more code that uses prompter( ), you begin to notice patterns. Once a pattern has been discovered, you write a generalized routine to handle the pattern, and this routine can be used over and over.
I suggest that the simplest way to get a clear picture of how prompter( ) works its way through the procedure tables is to single-step your way through prompter( ) with a debugger like CodeView.
Suggestions for Improving prompter( )
The first step to improve prompter( ) is to remove the printf( )/gets( ) interface, and attach a windowing-type interface. To do this, I suggest that you add an element to the question data structure. This element (question.form) is a pointer to a function that formats the output. Its job is to place the question text on the screen in its proper position, adjusting such attributes as color. If you are careful to isolate all screen positioning to only the question.form routines, you can later port the system to a different display by just rewriting these functions.
Next, add a better keyboard input routine. Most production systems do not use gets( ) for input.
Finally, as you use prompter( ), you will notice that there is room for improvement in the area of moving backwards in the prompts. You can develop a more elegant approach by having the routine prompter( ) automatically call pop_group( ) when it is at the end of a group.
Back to Procedure Tables
The point of this article was not to demonstrate how to prompt users for input but, to demonstrate the use of procedure tables. Procedure table techniques that are similar to those used in prompter( ) can be applied to a wide variety of tasks. We have used these techniques for the development of file maintenance programs, communications programs, parsers, menus, report generators, keyboard input validation routines, and others.
We have found procedure tables to be extremely helpful for developing software that is flexible, bug free, and highly maintainable. Using procedure tables allows us to treat functions as if they were data, and this opens up a new world to system design.
Availability
All source code for articles in this issue is available on a single disk. To order, send $14.95 (Calif. residents add sales tax) to Dr. Dobb's Journal, 501 Galveston Dr., Redwood City, CA 94063, or call 800-356-2002 (from inside Calif.) or 800-533-4372 (from outside Calif.). Please specify the issue number and format (MS-DOS, Macintosh, Kaypro).
C PROCEDURE TABLES by Tim Berens
[LISTING ONE]
Copyright © 1989, Dr. Dobb's Journal<a name="017d_000f">
/***************************************************************************
Name : prompter.c
Description : A routine for prompting a user for a series of answers.
***************************************************************************/
#include<stdio.h>
#include"prompter.h"
struct group_stack group_stack[GROUP_STACK_SIZE];
prompter(pc)
struct prcontrol * pc;
{
int errstat;
pc->current_question = 0;
pc->group_stack_ptr = 0;
for(;;){
pc->errstat = 0;
display_current_question(pc);
gets(pc->response);
if(*pc->response == 0){
continue;
}
if(!(pc->errstat =
(*pc->current_group[pc->current_question].validate)(pc))){
if(pc->errstat =
(*pc->current_group[pc->current_question].doit)(pc)){
if(pc->errstat == EXIT_NOW){
return(0);
}
}
}
if(pc->current_group[pc->current_question].response != NULL){
strcpy(pc->current_group[pc->current_question].response,
pc->response);
}
(*pc->current_group[pc->current_question].set)(pc);
if(pc->current_group[pc->current_question].text == NULL){
return(0);
}
if(pc->errstat){
handle_error(pc->errstat,pc->errormess);
}
}
}
display_current_question(pc)
struct prcontrol * pc;
{
printf("\n%s\n",pc->current_group[pc->current_question].text);
printf("--->");
}
handle_error(errstat,errormess)
int errstat;
struct errormess * errormess;
{
int i;
int emess_offset = -1;
char * message,messagebuff[100];
for(i = 0 ; errormess[i].errstat != -1 ; ++i){
if(errormess[i].errstat == errstat){
emess_offset = i;
break;
}
}
message = messagebuff;
if(emess_offset != -1){
strcpy(message,errormess[emess_offset].message);
if(errormess[emess_offset].build){
(*errormess[emess_offset].build)(message);
}
}
else{
sprintf(message,"Error %d.",errstat);
}
puts("\n");
puts(message);
return(0);
}
/***************************************
Flow control routines
***************************************/
no_op()
{
return(0);
}
next_question(pc)
struct prcontrol * pc;
{
++pc->current_question;
return(0);
}
pop_group(pc)
struct prcontrol * pc;
{
--pc->group_stack_ptr;
pc->current_group = group_stack[pc->group_stack_ptr].group;
pc->current_question = group_stack[pc->group_stack_ptr].current_question;
return(0);
}
push_current_group(pc)
struct prcontrol * pc;
{
group_stack[pc->group_stack_ptr].group = pc->current_group;
group_stack[pc->group_stack_ptr].current_question = pc->current_question;
++pc->group_stack_ptr;
return(0);
}
start_group(newgroup,pc)
struct question * newgroup;
struct prcontrol * pc;
{
push_current_group(pc);
pc->current_group = newgroup;
pc->current_question = 0;
return(0);
}
restart_group(pc)
struct prcontrol * pc;
{
pc->current_question = 0;
return(0);
}
end_group(pc)
struct prcontrol * pc;
{
pop_group(pc);
++pc->current_question;
return(0);
}
checkerror_end_group(pc)
struct prcontrol * pc;
{
if(pc->errstat){
return(0);
}
end_group(pc);
return(0);
}
checkerror_next_question(pc)
struct prcontrol * pc;
{
if(pc->errstat){
return(0);
}
next_question(pc);
return(0);
}
<a name="017d_0010"><a name="017d_0010">
<a name="017d_0011">[LISTING TWO]<a name="017d_0011">
/***************************************************************************
Name : prompter.h
Description : Declarations for prompter
***************************************************************************/
struct prcontrol {
int current_question;
struct question * current_group;
int group_stack_ptr;
char response[121];
int errstat;
struct errormess * errormess;
};
struct question {
char * text;
char * response;
int (*validate)();
int (*doit)();
int (*set)();
};
struct group_stack {
struct question * group;
int current_question;
};
/************************
errormess data structure
************************/
struct errormess {
int errstat;
char * message;
int (*build)();
};
#define GROUP_STACK_SIZE 50
#define NO_ERROR 0
#define EXIT_NOW 2001
int pop_group(),end_group(),no_op(),next_question();
int checkerror_end_group(),checkerror_next_question();
<a name="017d_0012"><a name="017d_0012">
<a name="017d_0013">[LISTING THREE]<a name="017d_0013">
/***************************************************************************
Name : prsample.c
Description : A sample that uses the prompter() routine
***************************************************************************/
#include<stdio.h>
#include"prompter.h"
#include<ctype.h>
/**************************
The report parameter variables
***************************/
char report_destination[2];
char dest_filename[30];
char single_or_range[2];
char start_account[20],end_account[20];
int account_number;
char display_parmname[50];
char include_overshort[2];
/*********************
Error Values
*********************/
#define ENTER_S_OR_R 1
#define ENTER_Y_OR_N 2
#define START_ACCOUNT_LARGER 3
#define BAD_PARM_NAME 4
#define BAD_ACCOUNT_NUMBER 5
#define ENTER_P_S_OR_D 6
#define FILE_EXISTS 7
/************************
Report to printer, screen or disk routines
************************/
int filename_val();
struct question report_filename[] = {
{ "What is the name of the disk file?",
dest_filename,filename_val,no_op,checkerror_end_group},
{ NULL,NULL,NULL,NULL,NULL }
};
filename_val(pc)
struct prcontrol * pc;
{
FILE * fp,*fopen();
/* you should put a routine to validate that the response
entered is a legal file name here */
if(fp = fopen(pc->response,"r")){
fclose(fp);
return(FILE_EXISTS);
}
return(0);
}
reportdest_val(pc)
struct prcontrol * pc;
{
char * strchr();
if((!strchr("PpSsDd",pc->response[0])) || (strlen(pc->response) != 1)){
return(ENTER_P_S_OR_D);
}
return(0);
}
reportdest_set(pc)
struct prcontrol * pc;
{
char destination;
destination = islower(*pc->response) ? *pc->response-32 : *pc->response;
switch(destination){
case 'P' :
case 'S' : next_question(pc);
break;
case 'D' : start_group(report_filename,pc);
break;
}
return(0);
}
/***************************
Account routines
***************************/
int account_val(),end_account_set(),end_account_val();
struct question account_range[] = {
{"Enter the starting account.",
start_account,account_val,no_op,checkerror_next_question},
{"Enter the ending account.",
end_account,end_account_val,no_op,end_account_set},
{ NULL,NULL,NULL,NULL,NULL }
};
int save_account_doit(),account_set();
struct question account[] = {
{"Enter the account.",
start_account,account_val,save_account_doit,checkerror_end_group},
{NULL,NULL,NULL,NULL,NULL}};
account_or_range_val(pc)
struct prcontrol * pc;
{
char * strchr();
if((!strchr("SsRr",pc->response[0])) || (strlen(pc->response) > 1)){
return(ENTER_S_OR_R);
}
return(0);
}
account_or_range_set(pc)
struct prcontrol * pc;
{
char account_or_range;
account_or_range = islower(*pc->response) ? *pc->response-32 :
*pc->response;
if(pc->errstat){
return(0);
}
if(account_or_range == 'S'){
start_group(account,pc);
}
if(account_or_range == 'R'){
start_group(account_range,pc);
}
return(0);
}
save_account_doit(pc)
struct prcontrol * pc;
{
account_number = atoi(pc->response);
return(0);
}
account_val(pc)
struct prcontrol * pc;
{
if((atoi(pc->response) < 100) || (atoi(pc->response) > 1000)){
return(BAD_ACCOUNT_NUMBER);
}
return(0);
}
end_account_val(pc)
struct prcontrol * pc;
{
int errstat;
if(errstat = account_val(pc)){
return(errstat);
}
if(atoi(start_account) >= atoi(pc->response)){
return(START_ACCOUNT_LARGER);
}
return(0);
}
end_account_set(pc)
struct prcontrol * pc;
{
switch(pc->errstat){
case NO_ERROR : end_group(pc);
break;
case START_ACCOUNT_LARGER : restart_group(pc);
break;
case BAD_ACCOUNT_NUMBER : break;
}
return(0);
}
/***************************
Get display parameters routines
****************************/
char * legal_parmnames[] = { /* In a "real" system, this table */
"default", /* would probably be stored in a file */
"daily", /* and parmname_val would check to see */
"weekly", /* if the name entered is in this file. */
"yearly",
NULL
};
parmname_val(pc)
struct prcontrol * pc;
{
int i;
for(i = 0 ; legal_parmnames[i] != NULL ; ++i){
if(strcmp(pc->response,legal_parmnames[i]) == 0){
return(0);
}
}
return(BAD_PARM_NAME);
}
bld_bad_parmname(message)
char * message;
{
sprintf(message + strlen(message)," %s, %s, %s, or %s.",
legal_parmnames[0],legal_parmnames[1],legal_parmnames[2],
legal_parmnames[3]);
return(0);
}
/**************************
yesno validation
***************************/
yesno_val(pc)
struct prcontrol * pc;
{
char * strchr();
if((!strchr("YyNn",pc->response[0])) || (strlen(pc->response) != 1)){
return(ENTER_Y_OR_N);
}
return(0);
}
/**************************************
Main question array procedure table
***************************************/
struct question account_parms[] = {
{"Do you want this report for a single account or a range of accounts? (S or R)",
single_or_range,account_or_range_val,no_op,account_or_range_set },
{"Enter the name of the display parameter record.",
display_parmname,parmname_val,no_op,checkerror_next_question},
{"Do you want to include the Over/Short Report? (Y/N)",
NULL,yesno_val,no_op,checkerror_next_question},
{"Do you want this report on the printer, screen, or saved to disk?(P,S or D)",
report_destination,reportdest_val,no_op,reportdest_set},
{ NULL,NULL,NULL,NULL,NULL }
};
struct errormess account_errormess[] = {
{ ENTER_S_OR_R,"Please enter S or R.",NULL },
{ ENTER_Y_OR_N,"Please enter Y or N.",NULL },
{ START_ACCOUNT_LARGER,"The starting account must be smaller than the ending account.",NULL },
{ BAD_ACCOUNT_NUMBER,"The account number must be between 100 and 1000",NULL },
{ BAD_PARM_NAME,"Choose one of the following :",bld_bad_parmname },
{ ENTER_P_S_OR_D,"Please enter P, S or D",NULL },
{ FILE_EXISTS,"That file already exists.",NULL },
{ -1,NULL,NULL }
};
main(argc,argv)
int argc;
char * argv[];
{
int errstat;
struct prcontrol prcontrol;
prcontrol.current_group = account_parms;
prcontrol.errormess = account_errormess;
if(errstat = prompter(&prcontrol)){
handle_error(errstat,account_errormess);
}
/* Print the report with the gathered parameters */
}
[EXAMPLE 1]
loop{
display current_question->text
get response from user
execute current_question->validate
if(no error on validate){
execute current_question->doit
}
copy response to current_question->response
execute current_question->set
if(error from validate){
call error handler
}
}
