Introduction

This chapter deals with

• writing validation and default-value functions for mio
• link editing functions to build a new version of mio
• some ways of carrying data from one request/response call to another
• writing services specifically tailored to interface with DES.

Writing Functions for the Data Entry System

UFORM specifications offer four places where you can call in functions of your own to customize the validation and default-value capability of mio. Three places are for validation functions, one for default functions:

• as a firstval() validation function to initialize the form.
• as a lastval() validation function when the user enters a leave key.
• as a field validation function for an unprotected field. (Specified with a VAL=FUNC statement)
• as a default function for an unprotected field. (Specified with a DFLT=FUNC statement)

Validation Functions

Validation functions can be used to check the input in a single field, to check values across fields, to change the attributes of fields, or even to change the form that is displayed on the terminal. This last operation would normally be based on an evaluation performed in the function; if the objective was only to change forms it would be simpler to use a UFORM MENU or FORMEXIT statement.

The Declaration for Validation Functions

The declaration of the firstval(), lastval() and field validation functions has the same format. It is:

int usrfunc(val, err, usrarg, flag, fldid, occno)
char *val;      /* pointer to value being validated */
char **err;     /* pointer to error message or 0 */
char *usrarg;   /* user argument passed to function */
int flag;       /* identifies type of function */
FLDID *fldid;   /* pointer to the buffer field id of this field */
int *occno;     /* pointer to buffer occurrence number.*/

where:

usrfunc is the name of the function.

val points to the value of the field being validated. In calls to firstval() and lastval() functions val should be null (0), since no particular field is being validated.

err is a pointer to an error pointer. If an error is detected, err may be used to change the error pointer to point to an error message.

usrarg points to an argument string if one is needed. Its length can not exceed 11 characters.

flag is 2 for firstval(), 1 for lastval(), and 0 for field validation functions.

fldid and occno are pointers to the field id and occurrence number of the field being validated.

firstval() and lastval() Return Codes

firstval() is the generic name of a validation function called by the form handler program when the users exits the form, but before any other validation functions are called. It is often used to change field attributes or otherwise initialize the form. The nature and timing of the actions taken by mio depends on the value returned by the function.

lastval() is the generic name of a validation function called after the user has left the form. It is useful for checking for agreement among fields. For example, if a form has a field for State and another for Zip_Code, a user can enter values in each that would be accepted by field validation functions, but that don't agree with each other. A State of NY and Zip_Code of 94117 are contradictory. Either State should be CA or Zip_Code should start with digits in the 100-149 range.

firstval() Return Codes

firstval() should be written to return a 1, 2, 3 or 4 on success and a -1 on failure. The action taken by mio on receipt of the return code is shown in Table 1

Table 1: firstval Return Codes and mio Actions

Here is further explanation of the actions listed in Table 1:

• The dash means the field in not applicable.
• Display of an error message assumes one has been specified.
• Making attributes changes assumes the changes have been specified. (See Changing Field Attributes later in this chapter)
• Deferring changes to the next form assumes another form has been specified. (See System Fields later in this chapter)

If the validation criteria are not met, the function returns a -1. When a -1 is returned, no dynamic attribute changes are applied, no field validations are performed and lastval() is not called.

The firstval() function flag is always 2.

lastval() Return Codes

lastval() should be written to return a 1 or 2 on success and a -1 on failure. The action taken by mio is shown in Table 2.

Table 2: lastval Return Codes and mio Actions

The assumptions listed above following Table 1 are also in effect for lastval().

Field Validation Functions

The function must return a -1 if the field is in error and a 1 if the field is acceptable.

Table 3: Field Validation Return Codes and mio Actions

If the field is found to be invalid, the function can set its err argument to point to an error message. If this is done, it overrides any value provided by the UFORM ERR specification (Error message: line on page 2 of the VARIABLE FIELD PARAMETERS form in vuform illustrated in Figure 3-12). Field validation functions are declared as shown above, except that flag is always 0.

val is a character pointer to the value in the field. To access the values in other fields of the form the get_val() routine can be called, or the external FML buffer pointer _gfbfr can be referenced. These are described below.

Getting the Value of Fields in Validation Functions

In standard field validation functions val points to the value of the field. However for firstval() and lastval(), since no particular field is being validated, it would be inappropriate to make val point to the value in an arbitrary field. For these functions, val is always passed as null (0). Instead of accessing field values via a pointer, the firstval() and lastval() functions can call the get_val() routine, to find the value of any field on the screen. get_val() expects two arguments:

• the buffer field id
• the occurrence number

get_val() returns a read-only pointer to the field value or a (char *)0 if no value exists for the field. The pointer returned by get_val() is only valid until the next call of get_val().

In the TUXEDO System/T software get_val() is declared as follows:

char *get_val(fldid, occno)
FLDID fldid;
int occno;

In your firstval() or lastval() function it should be declared as:

extern char *get_val();

Another way to look at the data entered in the form is via the external variable _gfbfr. _gfbfr should be declared as follows:

#include "fml.h";	
extern FBFR *_gfbfr;

_gfbfr can be read and modified with the standard FML buffer functions of the Field Manipulation Language (see the TUXEDO FML Guide). If necessary, _gfbfr can even be made larger by a call to tprealloc(). tprealloc() routine tprealloc() Modifications made to _gfbfr are reflected on the terminal on return from firstval() or lastval(). For read-only access, get_val() is preferred, since it is not FML specific.

By changing some system reserved fields in _gfbfr it is possible to change forms and the destination service in your firstval() or lastval() routine. (See System Fields later in this chapter.) It is also possible to alter attributes of fields dynamically. The techniques for doing these things in the firstval() and lastval() functions are the same as those used in a service. They are described in Changing Field Attributes below. For the form change to take effect, lastval() must return a 1 or a 2. When dynamically changing attributes a successful return value can be 1 or 2. The difference between a return of 1 and 2 is as follows: the return of a 1 implies that dynamic attribute changes should take effect immediately; the return of 2 implies that the dynamic attribute changes should be deferred.

_gfbfr can be modified and attributes can be dynamically altered from firstval(), lastval() and standard field validation functions. However, there is some risk involved in changing system fields in the buffer in validation functions. It is easy to create confusion for the service that processes the data from the form.

There is another global variable called _gformnam, it should be declared as follows :

extern char _gformnam[];

It contains the name of the form currently shown on the screen. This global variable should be considered read-only; it should never be altered by the user program.

In the firstval() function flag is always 2, in the lastval() function it is always 1, and in standard field validation functions it is always 0. This difference makes it possible to use the same function for all three validations. You need only check flag. In all validation functions fldid and occno are passed as pointers. In standard field validation functions, changing their values accomplishes nothing. However, if lastval() returns failure, the cursor is positioned at the field designated by *fldid and *occno. err keeps the same meaning with all validations. That is, it should be set to point to an error message, which is displayed if the function returns failure. Before lastval() is called, mio places the function key used to exit the form in the LEVKEY system field.

Changing Field Attributes

The attributes associated with a field on a form can be dynamically altered by the firstval() function, the lastval() function, by a standard field validation function, or by a service. The alteration is made via a call to change_atts(). The format of the call is:

int change_atts(fbfr, fldid, occno, atts)
FBFR *fbfr; 	/* FML buffer with screen representation*/
Fldid fldid;	/* FML buffer field id */
int occno;	/* occurrence number */
char *atts;	/* attributes */

change_atts() adds a reserved field to the FML buffer for the screen. Depending on the return code of the function that calls change_atts(), the changes appear on the terminal immediately or are deferred to the next form.

Attributes that can be changed are shown in Table 4. The full table of attribute flag values is shown in Appendix A, Figure 4.

Table 4: Attribute Flags That Can Be Changed with change_atts()

Attributes other than those listed above may not be changed.

atts points to any of the FLAGS values to be changed.

For example, to change occurrence zero of LAST_NAME from an unprotected field accepting mixed case input displayed with normal intensity to unprotected, upper case, bold the function would be called as follows:

change_atts(fbfr,LAST_NAME,0,"Uu3")

atts can also point to the string "RESTORE". In this case the field will be restored to its initial attributes. Continuing with the above example, LAST_NAME could be restored to its initial attributes by:

change_atts(fbfr,LAST_NAME,0,"RESTORE")

The calls shown above also affect other occurrences of LAST_NAME on the same form that are tied to occurrence zero. change_atts() affects all fields on a form with the given fldid and occno. In the above example, if field LAST_NAME, occurrence number zero, appeared on two pages of a form, both fields would be affected by the change_atts() calls.

change_atts() has three return codes.

1

- means success

0

- means an FML buffer operation failed.

-1

- means there is an error in an atts value.

With the 0 return, the Ferror variable shows the cause of failure. Since change_atts() adds a field to the FML buffer, an out-of-space error is a possibility. In this case, tprealloc() should be called to enlarge the FML buffer.

If a firstval() function is changing the attributes of the form currently on the screen, then on success firstval() should return a 1 or a 3. If it is changing the attributes of a form it is about to display (by changing the FORMNAM system field), it should return a 2 or a 4.

If a lastval() function is changing the attributes of the form currently on the screen, it should return a 1 on success. If it is changing the attributes of a form it is about to display (by changing the FORMNAM system field) it should return a 2.

Default-Value Functions

Default-value functions are named in a UFORM extended descriptor statement for a variable field. Using a function to furnish the default value for a field allows you to vary the default value depending on a value entered by the user in some other field. Once control has been passed to the function, the techniques described above under Getting the Value of Fields in Validation Functions, can be used to inspect other fields in the buffer.

The Declaration for Default-Value Functions

For default-value functions (specified in vuform under Default type: FUNC on page 2 of the VARIABLE FIELD PARAMETERS form illustrated in Figure 3-12), the declaration is as follows:

char *usrfunc(fldid, occno, usrarg)
FLDID fldid;	/* buffer field id of this field.*/
int occno;	/* occurrence number of this field in buffer*/
char *usrarg;	/* user argument passed to function */

The function must return a pointer to a string, which is taken to be the default value.

Link Editing Functions with mio

User validation and default functions should be compiled with the -c option to suppress the link edit phase (see cc(1) in a UNIX programmer's reference manual). The resulting object files can then be stored in archive libraries. In general it is best to store validation functions and default-value functions in separate libraries, and to store no other external functions with them. If default functions and validation functions are stored together in one archive library or compiled together into one object file, the following naming convention must be followed:

• validation function names must begin with _v_
• default-value function names must begin with _d_.

This isn't such a bad idea even when the functions are stored in separate archive libraries; it makes them self-documenting.

The formerly-supported buildmio(1) was used to build a version of mio with user functions linked in. The -o option of buildmio can be used to assign a name to the executable file. The default name is a.out. The fact that your new version of mio has user functions linked in does not prevent you from naming it mio. However, if you do, it would be wise to save the original version under another name in case you have to backtrack.

In addition to linking user functions into mio, buildmio also gives you the capability of replacing all the literals (including error messages) output by mio, with literals of your own choosing.

You can run mio in test mode (-t option) after you use buildmio if you want to check how the compiled form looks and whether the validation functions perform correctly. See Using mio in Chapter 4.

Undisplayed Fields

In addition to fields normally displayed on the user's screen, there are two types of fields that are not displayed.

Secret Fields

These are fields with a UFORM display flag of S, for secret. Secret fields are just like other fields as far as the application is concerned. Their distinguishing feature is that their contents are never displayed on the screen. Screen space is reserved for them, but characters entered into the field by the user are not echoed. If a value for a secret field is sent from the application service (presumably for use in some later validation function), the field is displayed as blank. In all other respects, the use of secret fields by an application service is just like non-secret fields.

It is worth remembering that the secret character of these fields applies only to their display. When stored in a data base a secret field is no more or less immune from unauthorized viewing than an ordinary field. It is not encrypted unless your application does it.

Undefined Fields

In addition to secret fields, the application service may send fields to the client process, mio, in the output buffer. Fields not mentioned in the UFORM definition of the form are not displayed on the screen. They are retained by mio in the screen buffer, and are subsequently input with the next mask. Such fields are commonly used to store information to be carried from one service request to another by re-entrant application functions. (The fields are, of course, defined in a field table file, as are all FML fields used in a TUXEDO System/T application.)

The use of such fields is totally application-specific, but the possible need for their existence is based on these characteristics of the TUXEDO System/T software:

• mio operates in request/response mode; that is, it sends service requests via calls to tpacall().
• Services are serially reusable. No values from one use are left over for the next use.
• If the application logic call for repeated visits to the same service, there is no guarantee that the requests will be handled by the same copy of the service.
• There is also no guarantee that the service has not been used to process a request for another user between the repeated visits.

This leads to a the need to be able to store information from one visit and make it available on subsequent visits. In the paragraphs that follow we will describe two ways of doing this.

Hiding Data in the Form Buffer

This is the simpler of the two methods. Here is how you might go about it:

Step 1:

Include in the application field tables the name of the field you intend to use.

Step 2:

Set the field to any value that carries your intended meaning.

Step 3:

Include in the logic of the service some code that checks the value of the field.

Step 4:

Use UPDTMOD mode 1 or 2 the first time the field is added to the buffer, so the field does not get discarded.

Hiding Data in a Database Record

This method also assumes a field in the form buffer to carry information about a record key. Beyond that the strategy is to define a file of scratch pad records that can be created in one visit to the service and referenced in a subsequent visit.

An advantage of this method is that the amount of data stored could easily be more extensive than you might want to carry in a field in the buffer.

A disadvantage is that you need to include in the application design some process for cleaning the file out as required.

Conversational Clients

It may be preferable to write conversational clients and servers rather than using either of the above two methods for carrying information from one request/response call to another. In the conversational mode a connection between the client and server is maintained until it is brought down, so the client can be assured of working with a dedicated server until the task is complete. Refer to Chapter 4 "Writing Conversational Clients and Servers" in the BEA TUXEDO Programmer's Guide.

Accessing Forms from a C Client Program

The TUXEDO System/T software includes a function called do_form(3c). do_form() acts like a simplified version of mio. The first of its two arguments is the name of a compiled form; the second is a pointer to a pointer to a fielded buffer. Use of the function is described in the BEA TUXEDO Reference Manual: Section 3c. The formal declaration is shown in Figure 1.

Fig. 1: do_form() Declaration

#include "fml.h"
do_form(formname,fbfr)
char *formname;
FBFR *fbfr;

usrfunc(svcinfo)
TPSVCINFO *svcinfo;

char	name[32];	/* service name being invoked */
char	*data;	/* request data */
long	len;	/* request data length */
long	flags;	/* describes service attributes */
int	cd;	/* connection descriptor if (flags & TPCONV) true */
int	appkey;	/* application authentication client key */
CLIENTID	cltid;	/* client identifier for originating client */

static FBFR *fbfr
	.
	.
	.
FBFR *newbuf = NULL	/*Temporary buffer used to ensure there is
			  enough data space left in the screen buffer*/
	.
	.
	.
fbfr = (FBFR *)svcinfo->data
	.
	.
	.
/*At this point, assuming that at least 1000 bytes of unused data
  space is needed, allocate 1000 more bytes.  Checking for that
  amount of unused space means having enough space in the buffer.*/
	/*If the buffer has less than 1000 free bytes of data space left*/
	if(Funused(fbfr) < 1000) {
	/*Allocate enough space for 50 additional fields and 1000
	  bytes of data space.                                    */
		newbuf = (FBFR*)tprealloc((char*)fbfr, svcinfo->len+1000)
			/* Check that return is not null. Code omitted.  */
			/*Copy the current data from the screen buffer to the
	  		temporary buffer.                                  */
		Fcpy(newbuf,fbfr);
			/* Check the return to make sure it is not < 0 */
			/*Set the screen buffer to point to the temporary buffer*/
		fbfr = newbuf;
}

get_mods(fbfr,mod_array,size_mod_array)
FBFR *fbfr;
struct track_mods *mod_array;
int size_mod_array;

#include "Fld.h"
struct track_mods {
	FLDID fldid;	/* field id of field */
	int occno;	/* occurrence number of field */
	short flags;
	};

mods_needed(fbfr)
FBFR *fbfr;

fld_mod(fbfr, fldid, occno)
FBFR *fbfr;
FLDID fldid;
int occno;

set_mods(fbfr,fldid,occno,cmd)
FBFR *fbfr;
FLDID fldid;
int occno;
char *cmd;

#include   <stdio.h>
#include   "fml.h"
#include   "atmi.h"
#include   "Usysflds.h"
#include   "mods.h"
extern char *Fname();
extern char *malloc();
#define ERROR { sprintf(s,"FATAL ERROR");\
                Fchgs(f,STATLIN, 0, s);	\
                tpreturn(TPFAIL,-1,NULL,0,0);\
               }
MOD(sinfo)
TPSVCINFO *sinfo;
{
         struct track_mods *mod_array;
         int i,cnt;
         FBFR *f;
         char s[100];
         f = (FBFR *)sinfo->data;	/* read in message from mio */
         cnt=mods_needed(f);	/* get the number of entries needed */
         if (cnt < 0) ERROR;
         /* allocate space for the array */
         mod_array=(struct track_mods *)malloc(cnt * sizeof(struct track_mods));
         if (!mod_array) ERROR;
         if (get_mods(f,mod_array,cnt) < 0) ERROR;
         fprintf(stderr,"\n%d field(s) modified\n",cnt);
         for (i=0; i<cnt; i++)
            fprintf(stderr,"%s %d\n",
             Fname(mod_array[i].fldid),mod_array[i].occno);
        /* reset all the mods on the form */
        if (set_mods(f,(FLDID)0,0,"MOD_RESET") < 1) {
             ERROR;
        }
	if (mod_array) free(mod_array);
	tpreturn(TPSUCCESS,1,f,0,0)
}

$ buildserver -o MOD -s MOD -f MOD.c  -f $TUXDIR/lib/formlib.a

short s;
s = 1;
Fchg(fbfr,UPDTMOD,0,&s,0);

#include "fml.h";
extern FBFR *_gfbfr;

TPSVCINFO  *svcinfo;
FBFR *fbfr;
	{
	.
	.
	.
	fbfr = (FBFR *)svcinfo->data;
	.
	.
	.
	}

	/* See if an occurrence zero of DESTSRVC exists */
if(Fpres(fbfr,DESTSRVC,0){
	process the error;
	}
	/* No? Then okay to add one */
if(Fadd(fbfr,DESTSRVC,"OPEN_ACCT",0) == -1){
	process the error;
	}
 .
 .
 .

if(Fchg(fbfr,DESTSRVC,0,"CLOSE_ACCT",0) == -1){
	process the error;
	}

/*The system field LEVKEY always contains the value of the transmission
  key; that is, it records the value of the key sequence that was
  depressed when the form was completed and sent into the mio()
  process.  The possible values of LEVKEY are <ESC> 0 (interpreted
  by the system as "F0") through <ESC> 9 (interpreted as "F9") and
  <CTRL> v (interpreted by the system as "F11").  With LEVKEY,
  meaning can be assigned to certain key sequences.                 */
char  *levkval;		/*Points to the value contained in the system
		  	  field LEVKEY                             */	
levkval = Fvals(fbfr,LEVKEY,0);
/*In this example the possible values of LEVKEY are "F1"
  through "F3".  Therefore, the switch can be done just on
  a value of 1, 2 or 3 in levkval[1] since levkval[0] == 'F'
  for each of the cases.                                           */
	switch(levkval[1]) {
	case '1':
	 	add();
		break;
	case '2':
		display();
		break;
	case '3':
		modify();
		break;
	}