Understanding SQL*Net

Library

Product

Contents

Index

**SQL*Net OPEN**

Practical Uses for SQL*Net OPEN
Compatibility with Oracle Network Products
SQL*Net OPEN Function Calls
SQL*Net OPEN API Errors
Configuring the System to Use Your Application
Sample Programs

This appendix describes the new SQL*Net feature, SQL*Net OPEN. SQL*Net OPEN is the application program interface (API) to SQL*Net. Using SQL*Net OPEN, programmers can develop both database and non-database applications that make use of the SQL*Net network already deployed in their environment.

By exposing an interface to SQL*Net, SQL*Net OPEN provides applications a single common interface to all industry standard network protocols. With SQL*Net, database applications can connect to other database applications across networks with different protocols. SQL*Net OPEN extends this connectivity to non-database applications.

SQL*Net OPEN provides a simple and portable call interface that enables developers to build truly portable network applications. They can rapidly deploy an application developed on one machine to another without having to modify their calls to the network interface.

The relationship of SQL*Net OPEN to other products is shown in Figure D - 1.

Figure D - 1. SQL*Net OPEN

**Practical Uses for SQL*Net OPEN**

You can use SQL*Net OPEN to solve a number of problems, such as:

Client/agent/server connectivity

SQL*Net OPEN enables you to use any application to communicate with any agent. For example, the agent might be an application server that allows simultaneous connectivity to Oracle and non-Oracle data sources, such as remote information servers.

Distributed applications

Using SQL*Net OPEN, you can build distributed applications that do not require a database and that can run over an existing Oracle network without any additional middleware.

Enhanced clients

You can use SQL*Net OPEN to integrate non-SQL information into SQL applications. For example, a process control application could communicate with a non-SQL application such as a sensor.

Compatibility with Oracle Network Products

SQL*Net OPEN is compatible with all releases of SQL*Net 2.0 and later. It works with related Oracle network products.

Oracle MultiProtocol Interchange

Using SQL*Net OPEN, you can take advantage of the cross-protocol connectivity provided by Oracle MultiProtocol Interchange. Through the MultiProtocol Interchange, applications can communicate across networks based on different protocols.

No additional programming is required to take advantage of the MultiProtocol Interchange. Its transfer of data across protocols is transparent to both users and programmers.

Advanced Networking Option

You can protect all your network data with standard encryption and data integrity checking through the Oracle Advanced Networking Option. Again, no additional programming is required to take advantage of these services.

**SQL*Net OPEN Function Calls**

The SQL*Net OPEN API consists of four function calls to perform the simple open, send, receive, and close functions common with network applications. It also contains a "control" call that provides access to more advanced features of the SQL*Net transport.

**SQL*Net OPEN API Usage**

SQL*Net OPEN provides a byte stream-oriented API which can be used to develop basic applications which send and receive data. This can be contrasted with a remote procedure call interface, for example, which provides the abstraction of a procedure call, and handles the marshalling of input and output arguments accordingly. Applications developed with SQL*Net OPEN must ensure for themselves that values that are sent across the network will be interpreted correctly at the receiving end.

The API as currently provided supports the C language. Examples given in this documentation are in C. Names used in API begin with "TNS," which stands for Transparent Network Substrate, the network transport technology on which SQL*Net version2 is based. For more information about TNS, refer to Chapter 2 in this manual.

**Finding the SQL*Net OPEN API**

The API is provided as part of the standard SQL*Net installation. To use the API, you need:

tnsapi.h, the header file which describes the API interfaces and errors. This file is provided in the appropriate location under the Oracle home directory for your platform. On UNIX, it is provided in $ORACLE_HOME/network/public.

The SQL*Net OPEN library. The name of the library varies by platform, but it is located where the other Oracle networking libraries are located, and contains the name "TNSAPI". On UNIX, it is in your $ORACLE_HOME/network/lib directory and is named libtnsapi.a. On Windows, the Oracle directories contain the files TNSAPI.DLL and TNSAPI.LIB in the appropriate locations.

Sample makefiles. These are provided for your platform under your network directory, as above. In UNIX they are in $ORACLE_HOME/network/demo. They can be used to determine the appropriate link line to use to build your application.

Building Your Own Application

Modules which make reference to SQL*Net OPEN functions should include the file tnsapi.h, as follows:

#include <tnsapi.h>

Your makefile (or other location for your build command) should ensure that the include path is set properly so that tnsapi.h will be found. Refer to the sample makefiles provided in your installation.

The SQL*Net OPEN API functions are described in the next sections:

TNSOPEN

Synopsis

  int tnsopen(handlep, name)
  void **handlep;
  const char *name;

Description Initializes the SQL*Net OPEN API per-connection handle. This function must be the first SQL*Net OPEN call that a user makes. Note that tnsopen() does not establish a connection; connections are established by the send and receive calls as needed. See the sections on tnssend() and tnsrecv() below.

If you're writing a client program (which will initiate the connection), "name" contains a service name in the same format as those in the SQL*Net configuration file TNSNAMES.ORA.

If you're writing a server program, "name" should be NULL. The connection will automatically be picked up by your server program when you make the first tnsrecv() call to receive data (see the section on tnsrecv, below.)

Parameters

  handlep (IN/OUT) - Address to receive SQL*Net connection handle

  name    (IN)     - service name

Prerequisites The handlep parameter must not be NULL

Returns Upon successful completion a zero value is returned. Otherwise, a positive SQL*Net API error is returned, as listed in the SQL*Net OPEN API Errors section.

TNSCLOSE

Synopsis

  int tnsclose(handlep)
  void **handlep;

Description Shuts down the connection. This function must be called by the user to close the connection and release the handle properly.

Parameters

handlep(IN/OUT) - Address of a pointer to a SQL*Net connection handle

Prerequisites The handlep parameter must not be NULL.

Returns Upon successful completion a zero value is returned, and *handlep is set to NULL. Otherwise, a positive SQL*Net API error number is returned.

TNSSEND

Synopsis

  int tnssend(handle, data, length)
  void *handle;
  const void *data;
  size_t *length;

Description Send data to the SQL*Net connection handle.

In the first call to tnssend() on the client side, the connection is established before any data is sent to the handle. The client application must first call tnssend() after tnsopen() to establish a connection to the server. It is an error if the client application calls tnsrecv() first, or if the server program calls tnssend() first.

Note that this also means that the tnssend() call may return errors related to connection establishment - so the first indication you get that, for instance, you've given the incorrect TNS address, is that an error occurs on the first tnssend() call, rhater than on the tnsopen() call as you may first expect.

Parameters

  handle(IN/OUT) - pointer to SQL*Net connection handle returned by 						tnsopen() 
  data(IN)      -     pointer to data to be sent
  length(IN/OUT) - pointer to the length of data to be sent in bytes and 						the actual number of bytes written on return.

Prerequisites The parameters must not be NULL.

Returns Upon successful completion a zero value is returned, and the actual number of bytes written is returned as the value pointed to by the length parameter. Otherwise, a positive SQL*Net API error number is returned.

TNSRECV

Synopsis

  int tnsrecv(handle, data, length)
  void *handle;
  void *data;
  size_t *length;

Description Receive data from the SQL*Net connection handle.

In the first call to tnsrecv() on the server side, the connection is established before data is received from the handle. The server must first call tnsrecv() after tnsopen() to accept the connection from the client.

Incoming connections are accepted by the SQL*Net Listener (tnslsnr), which automatically spawns off a copy of your server program when needed, and hands it the new connection. You must configure the network listener with the location of your server program for this to occur -- see the section on configuration below.

Parameters

  handle(IN/OUT) - pointer to SQL*Net connection handle returned by 						tnsopen()
  data(IN/OUT)   - pointer to buffer to receive data
  length(IN/OUT) - pointer to the length of buffer to receive data                   				and actual number of bytes received on return

Prerequisites All parameters must not be NULL.

Returns Upon successful completion a zero value is returned, and the actual number of bytes received is returned as the value pointed to by the length parameter. Otherwise, a positive SQL*Net API error number is returned.

TNSCONTROL

Synopsis

int tnscontrol (handle, cmd)
void *handle;
int cmd;

Description Set an option on a connection handle

Parameters

  handle (IN) 	pointer to TNS connection handle as returned by 						tnsopen()
  cmd (IN)		option to apply to the connection. Currently 							supported values are:
				TNSAPINONBLOCKING - set connection into 								nonblocking mode
				TNSAPIBLOCKING - set connection into blocking mode

Requires handle must not be NULL, and cmd must be one of the supported commands.

Returns A zero value is returned if option is successfully set.

**SQL*Net OPEN API Errors**

This section lists the error numbers which can be returned if one of the above function calls fails. Note that in some cases, connection-related errors may come back from a send or receive call, if the connection has not yet been established at that time.

20002 - SDFAIL_TNSAPIE - The underlying "send" command failed in tnssend().

20003 - RECVFAIL_TNSAPIE - The underlying "receive" command failed in tnsrecv().

20004 - INVSVROP_TNSAPIE - Operation is invalid as the server.

20005 - INVCLIOP_TNSAPIE - Operation is invalid as the client.

20006 - HDLUNINI_TNSAPIE - The connection should be initialized by calling tnsopen().

20007 - INHFAIL_TNSAPIE - Server failed in inheriting the connection from the listener.

20008 - ACPTFAIL_TNSAPIE - Server failed in accepting the connection request from the client.

20009 - NULHDL_TNSAPIE - A null handle was passed into the call, which is not allowed.

20010 - INVOP_TNSAPIE - An invalid operation called was passed into the call.

20011 - MALFAIL_TNSAPIE - A malloc failed in TNS API call.

20012 - NLINIFAIL_TNSAPIE - Failed in NL initialization.

20013 - NMTOOLONG_TNSAPIE - Service name is too long.

20014 - CONFAIL_TNSAPIE - Client connect request failed.

20015 - LSNFAIL_TNSAPIE - Server failed to listen for connect request.

20016 - ANSFAIL_TNSAPIE - Server failed to answer connect request.

20017 - NMRESFAIL_TNSAPIE - Failed to resolve service name.

20018 - WOULDBLOCK_TNSAPIE - operation would block.

20019 - CTLFAIL_TNSAPIE - control call failed.

20020 - TNSAPIE_ERROR - TNS error occurred.

20021 - INVCTL_TNSAPIE - invalid operation requested in control call.

Configuring the System to Use Your Application

In this release of SQL*Net OPEN, Oracle Network Manager cannot be used to configure applications you have developed using this API. You must configure SQL*Net yourself to recognize your application. This involves three steps:

1. Add the location of your server program to LISTENER.ORA, so that the network listener knows to start up your server if a connection request comes in for your service -- rather than starting up an Oracle database server.

To do this, first you must come up with a SID name for your service, similar to the one an Oracle database has. (Don't pick the same SID as your database.)

For example, say you are configuring a "chat" program. You could call the SID "chatsid". Place the program into an existing ORACLE_HOME, which we'll assume here is in /usr/oracle.

You would place the following entry in the LISTENER.ORA file for your listener:

SID_LIST_LISTENER =
  (SID_LIST =
    (SID_DESC =			
      (SID_NAME = chatsid)			/*your SID name*/
      (ORACLE_HOME = /usr/oracle)		/*your ORACLE_HOME name*/
      (PROGRAM = chatsvr)			/*the name of your server 	   						  program*/
    )

Note: There may be additional SIDs in the list as well, configured with Network Manager.

You need to restart the listener so it will recognize the new service.

2. Add the address of your application server to TNSNAMES.ORA, just like Network Manager would for a database server.

Let's assume that your listener is on the address:

(DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=unixhost)(PORT=1521)))

Also assume that you want people to refer to the service you created above as "chat".

You would add to the TNSNAMES.ORA file:

chat=(DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=unixhost)
  (PORT=1521))(CONNECT_DATA=(SID=chatsid)))

Note that the address contains the SID you configured in the LISTENER.ORA file above. Also note that the second line started with at least one space character, which indicates that it is a continuation line. In general, if you are editing a file that was originally created with Oracle Network Manager, you should follow its formatting conventions.

If you have a default domain, you need to name your service accordingly. For instance, chat.acme.com if your default domain is acme.com. Again, use the existing TNSNAMES.ORA file as a template -- if all the other service names end in a domain, you need to name your service name similarly.

3. Place the executable for your service in the appropriate location so the network listener can see it.

Your server program needs to go into the directory where your Oracle Server executable is. This is specific to your particular platform. On UNIX systems, it should go into the ORACLE_HOME directory that you indicated in the LISTENER.ORA file. So, in this example, you would place the program "chatsvr" in the location /usr/oracle/bin/chatsvr.

You also must ensure that your program has the correct permissions to be executed, if this is needed on your operating system.

Sample Programs

In this release, two sample applications are provided with your SQL*Net OPEN distribution. They are:

finger - The finger utility connects to a server which retrieves information about who is logged in. This is very simple pair of programs which demonstrate the basic steps involved in building a distributed application. The client program runs on both Solaris and Windows NT; the server is UNIX specific.

tftp - A client and server program are included which implement simple file transfer using the tftp protocol. This is a more extensive example. This demo was implemented for UNIX.

Prev Next

Library

Product

Contents

Index