Managing client connections

To allow the server to handle client connections successfully,
you need to write some logic to specify how and when the server
will begin listening for connections. In addition, you need to add
logic to handle client requests for services.

Version 5 clients cannot connect to Version 6 or 7
servers Because of architectural changes made in PowerBuilder Version
6, client applications written in Version 5 cannot connect to server
applications written in Version 6 or 7.

Listening for clientconnections

You use the Transport
object to listen for client connections. The Transport object
is a nonvisual object that is very similar to the Transaction object.

Declaring the transport variable

Unlike
the Transaction object, the Transport object is not a built-in global object;
therefore you need to declare a variable of type transport. Typically,
you will want this to be a global or instance variable.

Starting the listener

To begin listening for client connections, you need to execute
the PowerScript statements required to perform these operations:

1. Instantiate the Transport
   object.
2. Set properties for the Transport object.
3. Invoke the Listen function to begin listening.
4. (Optional) Check for errors.

You can perform these operations in a single script or in
several separate scripts, but they must be performed in the order
listed above.

Example The following script instantiates the mytransport Transport
object and sets the transport properties to identify the communications
driver and the server application. Then, the script invokes the
Listen function to begin listening for client connections. After
invoking the Listen function, the script checks for errors. If an
error occurs, it displays a message box to inform the system administrator
of the condition that caused the error. This example uses the WinSock
driver:

WinSock name resolution

To identify the server application, you specify a value for
the Application property of the Transport object. When you use the
WinSock driver, you can specify the port number for the server directly
or provide a service name. If you specify a service name, PowerBuilder
uses your TCP/IP network settings to determine the port
number for the server. In this case, PowerBuilder will use standard
name resolution procedures such as DNS, WINS, and the services file.

Updating the services file

If you use the services file for name resolution, you need
to be sure to use the correct format for the entries you add. For
example, to identify the dpbserv service, you could include the
following entry in the services file:

Line must be terminated with a carriage return or linefeed If you add the entry to the end of the services file, you
need to press return after the final entry. Otherwise,
the final entry will not be recognized.

The location of the services file depends on which TCP/IP
implementation and operating system you use.

Establishing multiple listeners

PowerBuilder allows you to instantiate multiple Transport
objects. This makes it possible for you to establish multiple listeners
in a single server application. For example, you could instantiate
two separate Transport objects to allow a server application to
listen for client connections through two different communications
drivers.

Testing locally

When you test an application by using the Local driver, PowerBuilder
emulates the remote server. Therefore, you do not have to create
a Transport object or perform any of the activities associated with
using Transport objects. If you issue the Listen function while
using the Local driver, the request will fail.

Handling client requests

Whenever a client application makes a request to connect to
a server application, the server can validate the request. If the
client has the proper authority to establish a connection, the server
can permit the request and grant the appropriate connection privileges.
If the client does not have the proper authority, the server can
reject the request.

Writing scripts to handle connections

To handle client requests for connections, you can write scripts
for the ConnectionBegin and ConnectionEnd events of the server’s
Application object. The script for the ConnectionBegin event can
specify the privileges for each connection by returning one of three
enumerated values (ConnectPrivilege!, ConnectWithAdminPrivilege!,
or NoConnectPrivilege!).

Connecting to the database

If the server application will access a database, you may
want to include the logic to connect to the database in the ConnectionBegin
event and to disconnect from the database in the ConnectionEnd event.

Example

The following example shows a script for the ConnectionBegin
event. To validate client connections, the script tests the values
of userid and password, which are arguments passed to the ConnectionBegin
event. Depending on the userid and password values, the script returns
an enumerated value that specifies the privileges for the connection.
To connect to the database, the script assigns the value of connectstring,
another argument of the ConnectionBegin event, to the dbparm property
of the Transaction object:

---