|
|
|
|
|
|
A client joins an application explicitly by calling the tpinit(3c) function with the following signature:A client joins an application implicitly by issuing a service request (or any ATMI function) without first calling the tpinit()function. In this case, the tpinit() function is called by the Oracle Tuxedo system on behalf of the client with the tpinfo argument set to NULL. The tpinfo argument points to a typed buffer with a TPINIT type and NULL subtype. The TPINIT typed buffer is defined in the atmi.h header file and includes the following information:char usrname[MAXTIDENT+2];
char cltname[MAXTIDENT+2];
char passwd[MAXTIDENT+2];
char grpname[MAXTIDENT+2];
long flags;
long datalen;
long data;Table 4‑1 summarizes the TPINIT data structure fields.
.
.
TPINIT *tpinfo;
.
.
.
if ((tpinfo = (TPINIT *)tpalloc("TPINIT",(char *)NULL,
TPINITNEED(8))) == (TPINIT *)NULL){
Error Routine
}Refer to tpinit() in the Oracle Tuxedo ATMI C Function Reference for more information on the TPINIT typed buffer.
{
check level of security
call tpsetunsol() to name your handler for TPU_DIP
get usrname, cltname
prompt for application password
allocate a TPINIT buffer
place values into TPINIT buffer structure members
if (tpinit((TPINIT *) tpinfo) == -1){
error routine;
}
allocate a message buffer
while user input exists {
place user input in the buffer
make a service call
receive the reply
check for unsolicited messages
}
free buffers
. . .
if (tpterm() == -1){
error routine;
}
}On error, -1 is returned and the application sets the external global variable, tperrno, to a value that indicates the nature of the error. tperrno is defined in the atmi.h header file and documented in tperrno(5) in the File Formats, Data Descriptions, MIBs, and System Processes Reference. Programmers typically assign an error code to this global variable that reflects the type of error encountered. There is a discussion of the values of tperrno in “System Errors” on page 11‑1. See “Introduction to the C Language Application-to-Transaction Monitor Interface” in the Oracle Tuxedo ATMI C Function Reference for a complete list of error codes that can be returned for each of the ATMI functions.Listing 4‑3 illustrates how to use the tpinit() and tpterm() functions. This example is borrowed from, bankapp, the sample banking application that is provided with the Oracle Tuxedo system.Listing 4‑3 Joining and Leaving an Application#include <stdio.h> /* UNIX */
#include <string.h> /* UNIX */
#include <fml.h> /* BEA Tuxedo System */
#include <atmi.h> /* BEA Tuxedo System */
#include <Uunix.h> /* BEA Tuxedo System */
#include <userlog.h> /* BEA Tuxedo System */
#include "bank.h" /* BANKING #defines */
#include "aud.h" /* BANKING view defines */
...
main(argc, argv)
int argc;
char *argv[];
{
...
if (strrchr(argv[0],'/') != NULL)
proc_name = strrchr(argv[0],'/')+1;
else
proc_name = argv[0];
...
/* Join application */
if (tpinit((TPINIT *) NULL) == -1) {
(void)userlog("%s: failed to join application\n", proc_name);
exit(1);
}
...
/* Leave application */
if (tpterm() == -1) {
(void)userlog("%s: failed to leave application\n", proc_name);
exit(1);
}
}The previous example shows the client process attempting to join the application with a call to tpinit(). If the process encounters an error (that is, if the return code is –1), the process writes a descriptive message to the central event log via a call to userlog(), which takes arguments similar to the printf() C program statement. Refer to userlog(3c) in the Oracle Tuxedo ATMI C Function Reference for more information.Similarly, when tpterm() is called, if an error is encountered, the process writes a descriptive message to the central event log.
