do_form-form display subroutine
#include "fml.h"
FBFR *
do_form(formname, fbfr)
char *formname;
FBFR **fbfr;
do_form() displays formname, collects input from a user, and returns a pointer to a fielded buffer containing the information entered on a form. If the form was exited with the abort function key, or by pressing the break key, then NULL is returned. On a system error, (FBFR *)-1 is returned. formname should be a file output by mc(1). If formname begins with a slash (/) the given path is searched; otherwise, formname is searched for in the directories listed in the MASKPATH environment variable. formname should include the .M file extension. When do_form() is called, fbfr is either a pointer to a pointer to a fielded buffer, a pointer to NULL, or a NULL pointer. If it is a pointer to NULL or a NULL pointer, do_form() allocates the fielded buffer. If it is not NULL, information contained in the fielded buffer is displayed on the screen. Upon return, the value contained in fbfr, if it is not a NULL pointer, points to a fielded buffer containing the screen content. If the value returned by the function is not a NULL and not a -1, then it points to the same fielded buffer. It is the caller's responsibility to free the fielded buffer pointed to by fbfr by calling tpfree(), regardless of the return value of the function. do_form() calls formexit() on disastrous conditions. A default version of formexit() exists in $TUXDIR/lib/libtfrm.a. do_form uses tpalloc(3) to allocate a buffer and tpfree(3) must be used to free the fielded buffer.
Application-defined function keys can be used (including re-mapping the default command and control keys) by exporting the file name in the UDFK environment variable. The file format is described in udfk(5).
This example displays the form supplied in a command line argument and writes the resulting fielded buffer on the standard output.
main(argc,argv)
int argc; char *argv[];
{
FBFR *fbfr, *fbfr1;
fbfr = (FBFR *)NULL;
fbfr1 = do_form(argv[1],fbfr);
if (fbfr1 == (FBFR *)NULL)
fprintf(stderr, "user quit\en");
else if (fbfr1 == (FBFR *)-1)
fprintf(stderr,\0"system error\en");
else
Fprint(fbfr1);
tpfree(fbfr);
}
If the form was exited with a transmit-form key (i.e., when a service would be called in mio(1)), a pointer to a fielded buffer is returned. If the form was exited with an abort function key, or with the break key, NULL is returned and the fbfr argument contains the pointer to the fielded buffer (if it is not a NULL pointer). On errors, such as malloc(3) failures, or failure to read a file, a (FBFR *)-1 is returned.
The form displayed allows full shell escapes.
When compiling, use
buildclient -o outputfile -f "appfiles" -l -ltfrm -l -lcurses -l -lm
where outputfile is the executable name, and appfiles are application files needed.
do_form() is not designed to work with menu hierarchies, specifically calling services from within the hierarchy. When a transmit-form key is entered from a form, do_form() returns the associated fielded buffer. If the form is not a top-level form, do_form() pops all levels of forms and returns. Data is not propagated up the menu hierarchy, and the current state (the position within the menu hierarchy) is lost.
mio(1), malloc(3) in a UNIX System reference manual, TUXEDO Data Entry System Guide, TUXEDO FML Guide