Open Server API

Adaptive Server uses the Open Server API, which allows users to run the system ESPs provided with Adaptive Server. Users can also use the Open Server API to implement their own ESPs.

Table 18-1 lists the Open Server routines required for ESP development. For complete documentation of these routines, see the Open Server Server-Library/C Reference Manual.

Table 18-1: Open Server routines for ESP support

Function

Purpose

srv_bind

Describes and binds a program variable to a parameter

srv_descfmt

Describes a parameter

srv_numparams

Returns the number of parameters in the ESP client request

srv_senddone

Sends results completion message

srv_sendinfo

Sends messages

srv_sendstatus

Sends status value

srv_xferdata

Sends and receives parameters or data

srv_yield

Suspends execution of the current thread and allows another thread to execute

After an ESP function has been written, compiled, and linked into a DLL, you can create an ESP for the function using the as external name clause of the create procedure command:

create procedure procedure_name [parameter_list]
     as external name dll_name

procedure_name is the name of the ESP, which must be the same as the name of its implementing function in the DLL. ESPs are database objects, and their names must follow the rules for identifiers.

dll_name is the name of the DLL in which the implementing function is stored. The naming conventions for DLL are platform-specific.

Table 18-2: Naming conventions for DLL extensions

Platform

DLL extension

HP 9000/800 HP-UX

.sl

Sun Solaris

.so

Windows

.dll

The following statement creates an ESP named getmsgs, which is in msgs.dll. The getmsgs ESP takes no parameters. This example is for a Windows Adaptive Server:

create procedure getmsgs 
as external name "msgs.dll"

The next statement creates an ESP named getonemsg, which is also in msgs.dll. The getonemsg ESP takes a message number as a single parameter.

create procedure getonemsg @msg int
as external name "msgs.dll"

When Adaptive Server creates an ESP, it stores the procedure’s name in the sysobjects system table, with an object type of “XP” and the name of the DLL containing the ESP’s function in the text column of the syscomments system table.

Execute an ESP as if it were a user-defined stored procedure or system procedure. You can use the keyword execute and the name of the stored procedure, or just give the procedure’s name, as long as it is submitted to Adaptive Server by itself or is the first statement in a batch. For example, you can execute getmsgs in any of these ways:

getmsgs
execute getmsgs
exec getmsgs

You can execute getonemsg in any of these ways:

getonemsg 20
getonemsg @msg=20
execute getonemsg 20
execute getonemsg @msg=20
exec getonemsg 20
exec getonemsg @msg=20