Programming an Oracle Tuxedo ATMI Application Using C

     Previous  Next    Open TOC in new window    View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

Writing Clients

This topic includes the following sections:

 


Joining an Application

Before an ATMI client can perform any service request, it must join the Oracle Tuxedo ATMI application, either explicitly or implicitly. Once the client has joined the application, it can initiate requests and receive replies.

A client joins an application explicitly by calling the tpinit(3c) function with the following signature:

int
tpinit (TPINIT *tpinfo)

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
Field
Description
usrname
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 defaults to 30 and is configurable by the administrator), and must be terminated by NULL.
cltname
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 defaults to 30 and is configurable by the administrator), and must be terminated by NULL.

Note: The value sysclient is reserved for the cltname field.

passwd
Application password in unencrypted format. Used for user authentication. The value is a string of up to 30 characters.
grpname
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.
flags
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 or tpinit() in the Oracle Tuxedo ATMI C Function Reference for more information on flags.
datalen
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.
data
Placeholder for variable length data that is forwarded to an application-defined authentication service.

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.

See Also

 


Using Features of the TPINIT Typed Buffer

The ATMI client must explicitly invoke the tpinit() function in order to take advantage of the following features of the TPINIT typed buffer:

Client Naming

When an ATMI client joins an application, the Oracle Tuxedo system assigns a unique client identifier to it. The identifier is passed to each service called by the client. It can also be used for unsolicited notification.

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.

Note: If a process is executing outside the administrative domain of the application (that is, if it is running on a workstation connected to the administrative domain), the LMID of the machine used by the Workstation client to access the application is assigned.

Once a unique identifier for a client process is created:

Refer to Writing Event-based Clients and Servers 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 Naming

Client Naming

Unsolicited Notification Handling

Unsolicited notification refers to any communication with an ATMI client that is not an expected response to a service request (or an error code). For example, an administrator may broadcast a message to indicate that the system will go down in five minutes.

A 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 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.

Table 4-2 Client Notification Flags in a TPINIT Typed Buffer
Flag
Description
TPU_SIG
Select unsolicited notification by signals. This flag should be used only with single-threaded, single-context applications. The advantage of using this mode is immediate notification. The disadvantages include:
  • 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.
TPU_THREAD
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.
TPU_IGN
Ignore unsolicited notification.

Refer to tpinit(3c) in the Oracle Tuxedo ATMI C Function Reference for more information on the TPINIT typed buffer flags.

System Access Mode

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.

Table 4-3 System Access Flags in a TPINIT Typed Buffer
Mode
Description
Protected
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.

Resource Manager Association

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.

Client Authentication

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.

The application password security level requires every client to provide an application password when it joins the application. The administrator can set or change the application password and must provide it to valid users.

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.

Note: The password should not be displayed on the screen.

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.

 


Leaving the Application

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.

 


Building Clients

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:

buildclient filename.c -o filename -f filenames -l filenames

Table 4-4 describes the options to the buildclient command.

Table 4-4 buildclient Options
This Option or Argument . . .
Allows You to Specify . . .
filename.c
The C application to be compiled.
-o filename
The executable output file. The default name for the output file is a.out.
-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).
-r
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.

Notes: The Oracle Tuxedo libraries are linked in automatically; you do not need to specify any Oracle Tuxedo libraries on the command line.
Note: Link editing must be done by running the buildclient command.

The order in which you specify the library files to be link edited is significant: it depends on the order in which functions are called in the code, and which libraries contain references to those functions.

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.

buildclient -C -o audit -f audit.o

The following example command line compiles a C program called audit.c and generates an executable file named audit.

buildclient – o audit – f audit.c

See Also

 


Client Process Examples

The 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 Paradigm
main()
{
      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. 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.


  Back to Top       Previous  Next