The BEA TUXEDO server machine must have the BEA TUXEDO System/T and the native-side /WS installed.

Programming Considerations with the Macintosh libraries

This section covers items specific to writing and building TUXEDO System/Workstation client programs to run under Macintosh. They are intended to supplement the material presented in the BEA TUXEDO Programmer's Guide.

Our assumption is that readers of this section either have experience in writing Macintosh programs or have access to tutorial material on that subject. Our discussion is limited to a description of how you go about putting System/T functions into Macintosh programs.

Writing Client Programs

The ATMI and FML calls used in Macintosh client programs are much the same as described in the BEA TUXEDO Programmer's Guide. An example of tuxputenv(3c) is given in Figure 1.

Fig. 1: Handling the environment

	void
	main()
	{
		TPINIT      *tpinfop;
		FILE        *fp;
		char        aline[MAXLINE];
		char        *loc_env[MAXENV];
	....
		if((loc_env[top_one]=(char *) malloc(strlen(aline) + 1)) == NULL) {
			userlog("Error mallocing space for the environment.");
			continue;
		}
		strcpy(loc_env[top_one], aline);
		if(tuxputenv(loc_env[top_one]) != 0) {
			userlog("Error adding %s to the environment.",
				loc_env[top_one]);
			free(loc_env[top_one]);
			continue;
		}

Using bankapp as an Example

After TUXEDO System/T is installed on the Macintosh, among the files in the directory $TUXDIR/apps/bankapp you will find the following:

bankapp.r  - dialog resource for BANKAPPM windows
BANKAPPM.C   - Macintosh application source file
BANKAPPM.h - Macintosh application header file
MACDialog.c -  Macintosh application source file
MACDialog.h - Macintosh application header file
bank.flds     - FML buffer field identifiers
mkbankhdr.tsh - TuxShell script to create headers

These are the files needed to produce a bankapp client for Macintosh. Notice there is a TuxShell(1) script, mkbankhdr.tsh, which needs to be modified for your instantiation and run with the TuxShell(1) program before compilation.

Take a look through the application file, BANKAPPM.c; we want to call your attention to a few items. Figure 2 shows a partial list of the #include files you should use.

Fig. 2: bankapp for Macintosh: #include files

	41	#include <Quickdraw.h>
	42	#include <Resources.h>
	43	#include <Fonts.h>
	44	#include <OSEvents.h>
	45	#include <Desk.h>
	46	#include "MACDialog.h"
	47	#include "BANKAPPM.h"
	48	#include "bank.flds.h"
	49	#include <string.h>
	50	#include <Uunix.h>
	51	#include <atmi.h>
	52	#include <fml.h>
	53	#include <Usysflds.h>
	54	#include <userlog.h>

Lines 93 to 410 (not shown) are Field Validation Routines: five routines that check the validity of the input typed in by the user. We will not show this code except for an example (in Figure 3) of how syntax errors cause a message to be displayed on the user's screen by means of a call to NoteAlert.

Fig. 3: bankapp for Macintosh: displaying a syntax error

	151     for (i=0; amount[i] != 0 && i < 10; i++) {
	152         if (amount[i] == '.') {
	153             if (decimal)
	154                 break;
	155             decimal++;
	156             continue;
	157         }
	158         if (!isdigit(amount[i]))
	159             break;
	160         if (decimal) {
	161             decimal++;
	162             if (decimal > 3)
	163                 break;
	164         }
	165     }
	166     if (i == 0 || (3 - decimal) + i > 10) {
	167         (void) NoteAlert(amounCAUT, NULL);
	168         return(FALSE);
	169     }

The actual work of the application begins at with the comments at line 412 (not shown). Each of the dialog boxes has a set of routines which are used to implement its functionality.

The dialog boxes, which take up the rest of the code, accept input from the user, start a transaction, make a call to the requested service and return information to the user. The code in Figure 4 shows how errors might be handled. In lines 594-599, for example, if the call to tpbegin(3c) fails, a message is sent to userlog(3c) and also to the user's screen via the ParamText function. In lines 600-605, if the service call fails and the buffer is not NULL, the status line is picked up and returned to the user.

Lines 625-630 show the service request being successfully performed and the requested balance being displayed on the user's screen.

Fig. 4: bankapp for Macintosh: error handling

594     if (tpbegin(30, 0) == -1) {
595         (void) userlog("failed to begin transaction");
596         NumToString(tperrno, tpStr);
597         ParamText("\pOpen Account Failed", "\p",
598                     "\ptperrno = ", tpStr);
599     }
600     else if (tpcall("OPEN_ACCT", (char *) *fbfr, 0, (char **) fbfr,
		&len, 0) == -1) {
601         if((tperrno == TPESVCFAIL) && (*fbfr != NULL) &
602                 ((s = Ffind(*fbfr,STATLIN,0,0)) != 0)) {
603             BlockMove(s, &account1[1], (Size) (account1[0] =
			(unsigned char) strlen(s)));
604             ParamText((unsigned char *) account1, "\p", "\p", "\p");
605         }
606         else {
607             NumToString(tperrno, tpStr);
608             ParamText("\pTransfer Failed", "\p", "\ptperrno = ", tpStr);
609         }
625             Fget(*fbfr, ACCOUNT_ID, 0, (char *) &acc_num, 0);
626             s = Ffind(*fbfr, SBALANCE, 0, 0);
627             NumToString(acc_num, tpStr);
628             BlockMove(s, &account1[1], (Size) (account1[0] =
			(unsigned char) strlen(s)));
629             ParamText("\pAccount Number: ", tpStr,
630                         "\pAccount Balance: ", (unsigned char *) account1);

Blocking Network Behavior

When an ATMI function is called the Macintosh could block on the network waiting for a reply from the server. This can happen on any call that initiates a network message to the UNIX machine, for example, tpcall(3c), tpinit(3c), tpgetrply(3c) and so on. These functions may take an arbitrarily long time to complete; a good example is tpcall(3c), which may block until the server has completed the processing required.

With the TUXEDO System Workstation for Macintosh a blocking operation that cannot be completed immediately is handled as follows. The Macintosh initiates the operation and enters a loop in which it calls WaitNextEvent while retrieving only NULL events (yielding the processor to another process if necessary). It then checks for the completion of the ATMI function. If the ATMI call is complete the blocking call is completed and the appropriate result is returned to the caller. If the ATMI call is not complete the Macintosh continues to dispatch WaitNextEvent messages. For a complete description of this behavior see AEMsetblockinghook(3) AEMsetblockinghook(3) in the BEA TUXEDO Reference Manual: Section 3c.

Although this mechanism is sufficient for simple applications, it cannot support the complex message dispatch requirements of more advanced applications. For such applications, ATMI includes AEMsetblockinghook(3) AEMsetblockinghook(3), which allows the programmer to define a special routine which will be called instead of the default routine.

By using AEMsetblockinghook(3), there is a risk that the application will attempt to issue another ATMI call. Such application behavior is not supported by ATMI calls. AEMisblocked(3) AEMisblocked(3) can be called at any time to detect if there is a blocking ATMI call outstanding. Any other ATMI call made while this condition exists will fail and set tperrno to TPEPROTO.

If an application invokes a blocking operation like tpcall() and provides a typed buffer to it as an argument, it is the responsibility of the application to ensure that the buffer is available to ATMI until the operation is completed.

FML functions will continue to work even if there is a blocking call in progress, therefore it is the responsibility of the application to not use FML buffers that are passed in as an argument to an ATMI call that is currently in progress until the ATMI call completes.

Building Client Programs

Any compiler that can read MPW C libraries can be used to compile application programs.

When compiling with MPW, be sure to use the -model far, -m, and -mc68020 options.

When using THINK C, use the same compiler options as specified above for library generation.

A Macintosh executable, TuxShell(1), is provided to run TUXEDO System/T utilities. TuxShell(1) takes as input a script containing utility command lines. See the manual page, TuxShell(1), for more detail.

Runtime

When you run client programs, the TUXDIR environment variable must be set properly before tpinit(3c) or tpalloc(3c) is called. In order to use the TUXEDO System/T catalogs properly, the locale:C directory must be below the {TUXDIR} directory. You may want to put the locale:C directory into the System Folder, since the application can always find that filesystem.

Limitations

The following is a list of limitations that apply to Release 5.0 (or higher) of the System/T Macintosh libraries.

• The THINK C, version 7.1, compiler is required for building the TuxShell(1) program.
• Multiplexed network connections are not available; each client process requires a separate network connection.