Understanding SQL*Net

**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. Future versions of the API will add a "control" call to provide access to more advanced features of the SQL*Net transport.

Enhanced functionality will be available in future releases.

**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/include.

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