![]() |
![]() |
![]() |
![]() |
![]() |
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.
Table 4‑1 TPINIT Data Structure Fields Name representing the client; used for both broadcast notification and administrative statistics retrieval. The client assigns a value to usrname during the call to the tpinit() function. The value is a string of up to MAXTIDENT characters (which is defined as 30), and must be terminated by NULL. Client name with application-defined semantics: a 30-character NULL-terminated string used for both broadcast notification and administrative statistics retrieval. The client assigns a value to cltname during the call to the tpinit() function. The value is a string of up to MAXTIDENT characters (which is defined as 30), and must be terminated by NULL.
Note: Associates client with resource manager group. If set to a 0-length string, the client is not associated with a resource manager and is in the default client group. The value of grpname must be the NULL string (0-length string) for Workstation clients. Refer to Using the ATMI Workstation Component for more information on Workstation clients. Indicates both the client-specific notification mechanism and the mode of system access. Controls both multicontext and single-context modes. Refer to “Unsolicited Notification Handling” on page 4‑5 or tpinit() in the Oracle Tuxedo ATMI C Function Reference for more information on flags. Length of the application-specific data. The buffer type switch entry for the TPINIT typed buffer sets this field based on the total size passed in for the typed buffer. The size of the application data is the total size less the size of the TPINIT structure itself plus the size of the data placeholder as defined in the structure. Before it can join the application, the client program must call tpalloc() to allocate the TPINIT buffer. Listing 4‑1 shows how to allocate a TPINIT buffer that will be used to pass eight bytes of application-specific data to the tpinit() function.Listing 4‑1 Allocating a TPINIT Typed Buffer.
.
.
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.
• tpinit(3c) in the Oracle Tuxedo ATMI C Function ReferenceThe ATMI client must explicitly invoke the tpinit() function in order to take advantage of the following features of the TPINIT typed buffer:You can also assign unique client and usernames of up to 30 characters each, by passing them to the tpinit() function via the tpinfo buffer argument. The Oracle Tuxedo system establishes a unique identifier for each process by combining the client and usernames associated with it, with the logical machine identifier (LMID) of the machine on which the process is running. You may choose a method for acquiring the values for these fields.
• Refer to “Writing Event-based Clients and Servers” on page 8‑1 for information on sending and receiving unsolicited messages, and the Oracle Tuxedo ATMI C Function Reference for more information on tmadmin(1).Figure 4‑1 shows how names might be associated with clients accessing an application. In the example, the application uses the cltname field to indicate a job function.Figure 4‑1 Client NamingA client can be notified of an unsolicited message in a number of ways. For example, some operating systems might send a signal to the client and interrupt its current processing. By default, the Oracle Tuxedo system checks for unsolicited messages each time an ATMI function is invoked. This approach, referred to as dip-in, is advantageous because it:As some time may elapse between “dip-ins,” the application can call the tpchkunsol() function to check for any waiting unsolicited messages. Refer to “Writing Event-based Clients and Servers” on page 8‑1 for more information on the tpchkunsol()function.When a client joins an application using the tpinit() function, it can control how to handle unsolicited notification messages by defining flags. For client notification, the possible values for flags are defined in Table 4‑2.
• The calling process must have the same UID as the sending process when you are running a native client. (Workstation clients do not have this limitation.)
• TPU_SIG is not available on all platforms (specifically, it is not available on MS-DOS workstations).If you specify this flag but do not meet the system or environmental requirements, the flag is set to TPU_DIP and the event is logged. TPU_DIP (default) Select unsolicited notification by dip-in. In this case, the client can specify the name of the message handling function using the tpsetunsol() function, and check for waiting unsolicited messages using the tpchkunsol() function. Select THREAD notification in a separate thread. This flag is allowed only on platforms that support multithreading. If TPU_THREAD is specified on a platform that does not support multithreading, it is considered an invalid argument. As a result, an error is returned and tperrno(5) is set to TPEINVAL. Refer to tpinit(3c) in the Oracle Tuxedo ATMI C Function Reference for more information on the TPINIT typed buffer flags.An application can access the Oracle Tuxedo system through either of two modes: protected or fastpath. The ATMI client can request a mode when it joins an application using the tpinit() function. To specify a mode, a client passes one of the following values in the flags field of the TPINIT buffer to the tpinit() function.
Allows ATMI calls within an application to access the Oracle Tuxedo system internal tables via shared memory, but protects shared memory against access by application code outside of the Oracle Tuxedo system libraries. Overrides the value in UBBCONFIG, except when NO_OVERRIDE is specified. Refer to Setting Up an Oracle Tuxedo Application for more information on UBBCONFIG. Fastpath (default) Allows ATMI calls within application code access to Oracle Tuxedo system internals via shared memory. Does not protect shared memory against access by application code outside of the Oracle Tuxedo system libraries. Overrides the value of UBBCONFIG except when NO_OVERRIDE is specified. Refer to Setting Up an Oracle Tuxedo Application for more information on UBBCONFIG.An application administrator can configure groups for servers associated with a resource manager, including servers that provide administrative processes for coordinating transactions. Refer to Setting Up an Oracle Tuxedo Application for information on defining groups.When joining the application, a client can join a particular group by specifying the name of that group in the grpname field of the TPINIT buffer.The Oracle Tuxedo system provides security at incremental levels, including operating system security, application password, user authentication, optional access control lists, mandatory access control lists, and link-level encryption. Refer to Setting Up an Oracle Tuxedo Application for information on setting security levels.If this level of security is used, Oracle Tuxedo system-supplied client programs, such as ud(), prompt for the application password. (Refer to Administering an Oracle Tuxedo Application at Run Time for more information on ud, wud(1).) In turn, application-specific client programs must include code for obtaining the password from a user. The unencrypted password is placed in the TPINIT buffer and evaluated when the client calls tpinit() to join the application.You can use the tpchkauth(3c) function to determine:Typically, a client should call the tpchkauth() function before tpinit() to identify any additional security information that must be provided during initialization.Refer to Using Security in CORBA Applications for more information on security programming techniques.Once all service requests have been issued and replies received, the ATMI client can leave the application using the tpterm(3c) function. The tpterm() function takes no arguments, and returns an integer value that is equal to –1 on error.To build an executable ATMI client, compile your application with the Oracle Tuxedo system libraries and all other referenced files using the buildclient(1) command. Use the following syntax for the buildclient command:Table 4‑4 describes the options to the buildclient command.
Table 4‑4 buildclient Options -o filename -f filenames A list of files that are to be link edited before the Oracle Tuxedo system libraries are link edited. You can specify -f more than once on the command line, and you can include multiple filenames for each occurrence of -f. If you specify a C program file (file.c), it is compiled before it is linked. You can specify other object files (file.o) separately, or in groups in an archive file (file.a). -l filenames A list of files that are to be link edited after the Oracle Tuxedo system libraries are link edited. You can specify -l more than once on the command line, and you can include multiple filenames for each occurrence of -l. If you specify a C program file (file.c), it is compiled before it is linked. You can specify other object files (file.o) separately, or in groups in an archive file (file.a). The resource manager has access to libraries that should be link edited with the executable server. The application administrator is responsible for predefining all valid resource manager information in the $TUXDIR/updataobj/RM file using the buildtms(1) command. Only one resource manager can be specified. Refer to Setting Up an Oracle Tuxedo Application for more information.By default, the buildclient command invokes the UNIX cc command. You can set the CC and CFLAGS environment variables to specify an alternative compile command, and to set flags for the compile and link-edit phases, respectively. For more information, refer to “Setting Environment Variables” on page 2‑5.The following example command line compiles a C program called audit.c and generates an executable file named audit.
• buildclient(1) in the Oracle Tuxedo Command ReferenceThe following pseudo-code in Listing 4‑2 shows how a typical ATMI client process works from the time at which it joins an application to the time at which it leaves the application.Listing 4‑2 Typical Client Process Paradigmmain()
{
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.