Using service classes

You can use the methods available on the server component
to perform most server-side processing, including validation routines
and error handling. The Web DataWindow also provides another way
to add specialized processing.

To include server-side processing not available on the server
component, you can define one or more PowerBuilder custom class
user objects called service classes. These service classes are stored
in the same PBL or PBD as the DataWindow object for the server component.
They can be used whenever you want to include additional processing
on the server. For example, you might want to use this technique
to access the SQLPreview event so that you can examine the syntax
of a SQL statement before it is committed to the database.

Where you implement the code

The service classes implement user-defined events with prescribed
signatures. These events correspond to standard DataWindow events.
In the user-defined events, you perform the processing and specify
return codes that tell the server component whether to cancel the
corresponding DataWindow event.

In the server component, you set a property or call a method
that identifies these user objects as service classes for the server
component.

How the code is called

Service classes work like this:

1. Service classes are instantiated when the component is instantiated
   (if they are specified in an EAServer property)
   or when they are first registered by the SetServerServiceClasses
   method.
2. An event occurs in the server component for the
   DataStore.
3. The server component calls an event of the same
   name in each registered service class.
4. If the service class implements the event, the event
   script is executed and a return code is sent back to the server
   component.
5. If the event can be canceled via a return code and
   if any of the service classes returns that code, the event is canceled
   in the server component.

Figure 7-2: How service classes work

Defining a service class for PowerBuilder components

To create and register a service class for PowerBuilder
components:

1. In the PBL that contains the DataWindow
   object for the server component, define one or more PowerBuilder
   custom class user objects.

2. In each custom class user object, define one or
   more user-defined events. The event signatures must match one of
   these (all these events return a long):

   • DBError
     (long sqldbcode, string sqlerrtext, string sqlsyntax, DWBuffer buffer,
     long row, DataStore ds)
   • HTMLContextApplied (string action, DataStore ds)
   • RetrieveEnd (long rowcount, DataStore ds)
   • RetrieveStart (DataStore ds)
   • SQLPreview (SQLPreviewFunction request, SQLPreviewType sqltype,
     string sqlsyntax, DWBuffer buffer, long row, DataStore ds)
   • UpdateEnd (long rowsinserted, long rowsupdated,
     long rowsdeleted, DataStore ds)
   • UpdateStart (DataStore ds)

   The arguments are the same as those documented for the similarly
   named DataWindow events in the DataWindow Reference
   ,
   with the exception of the additional DataStore argument, which gives
   the user object access to the Web DataWindow data.

3. In the event script, use return codes to specify
   whether the server component should cancel the event.

   The return codes are also the same as those documented in
   the DataWindow Reference
   . Any of the service
   classes that implements the event can specify that the event be
   canceled.

4. Register the service classes for the component.

   There are two ways to make the user object available as a
   service class:

   • For any component in EAServer or another supported server
     such as COM+, call the SetServerServiceClasses method in
     the Web page template’s server-side script:
     PowerBuilder

     dwGen.SetServerServiceClasses

     1	dwGen.SetServerServiceClasses

     PowerBuilder

     ("uo_update_validate;uo_retrieve_process");

     1	("uo_update_validate;uo_retrieve_process");

   • For a custom component in EAServer,
     add this property in EAServer Manager:
     PowerBuilder

     com.sybase.datawindow.serverServiceClasses

     1	com.sybase.datawindow.serverServiceClasses

     Set its value to the list of user object names, with names
     separated by semicolons. For example:

     PowerBuilder

     uo_update_validate;uo_retrieve_process

     1	uo_update_validate;uo_retrieve_process

Using server component methods with the DTC If you are using the Web DataWindow DTC or the JSP Target
object model, you can use methods of the server component by using
the Component property. For example:

Example

Suppose that you want to check that data did not exceed a
budgeted total before it was updated in the database. You might
set up a service class that implements the UpdateStart event.

In the custom class user object in PowerBuilder, select Insert>Event
and declare a new event called UpdateStart that returns a long and
has one argument of type DataStore called ds:

This script for the UpdateStart event has a DataStore that
retrieves data from a budget table and compares it to the component’s
data:

Defining a service class for Java components

To create and register a service class for Java
components:

1. Make sure your Java service class is in
   the system classpath.

2. In your Java service class, define one or more
   methods. Method prototypes must match one of these (all event data
   types are in the powersoft.datawindow.event package):

   • DBError (DatabaseEvent event, DataStore ds)
   • RetrieveEnd (RetrieveEvent event, DataStore ds)
   • RetrieveStart (RetrieveEvent event, DataStore ds)
   • SQLPreview (DatabaseEvent event, DataStore ds)
   • UpdateEnd (UpdateEvent event, DataStore ds)
   • UpdateStart (UpdateEvent event, DataStore ds)

   The arguments are the same as those documented for the similarly
   named DataWindow, Java Edition events in the DataWindow
   Reference
   , with the exception of the additional DataStore
   argument, which gives the Java class access to the Web DataWindow
   data.

3. In the class methods, set the return codes to
   specify whether the server component should cancel the event.

   The return codes are also the same as those documented in
   the DataWindow Reference
   . Any of the service
   classes that implements the event can specify that the event be
   canceled.

4. Register the service classes for the component.

   There are two ways to make the Java class available as a service
   class:

   • For any component in EAServer or another supported server
     such as COM+, call the SetServerServiceClasses method in
     the Web page template’s server-side script:
     PowerBuilder

     dwGen.SetServerServiceClasses

     1	dwGen.SetServerServiceClasses

     PowerBuilder

     ("UpdateValidate;RetrieveProcess");

     1	("UpdateValidate;RetrieveProcess");

   • For a custom component in EAServer,
     add this property in EAServer Manager:
     PowerBuilder

     com.sybase.datawindow.serverServiceClasses

     1	com.sybase.datawindow.serverServiceClasses

     Set its value to the list of user object names, with names
     separated by semicolons. For example:

     PowerBuilder

     UpdateValidate;RetrieveProcess

     1	UpdateValidate;RetrieveProcess

Using server component methods with the DTC If you are using the Web DataWindow DTC or the Web Target
object model, you can use methods of the server component by using
the Component property. For example:

Example

Suppose that you want to check that data did not exceed a
budgeted total before it was updated in the database. You might
set up a service class that implements the UpdateStart event.

The method declaration would be:

The body of this method has a DataStore that retrieves data
from a budget table and compares it to the component’s
data:

---