Chapter 18   The PeopleSoft Data Connector

The PeopleSoft Enterprise Data Connector (EDC) provides a wizard interface that lets you build a PeopleSoft-specific Data source object (DSO). You can then bind any SilverStream object to it using the standard SilverStream data access API. The DSO handles the underlying data access and manipulation seamlessly.

This chapter provides information about the following:

• SilverStream and PeopleSoft integration

• Creating a PeopleSoft DSO

• Invoking the PeopleSoft DSO

• Deploying a PeopleSoft DSO

SilverStream accesses PeopleSoft data using its DSO technology. DSOs are triggered business objects that let you access relational and non-relational data sources.

    For more information about SilverStream's DSO technology, see the chapter on data source business objects in the Programmer's Guide.

SilverStream and PeopleSoft integration   

The SilverStream Application Server acts as the client to the PeopleSoft Server. The following diagram illustrates this relationship.

At runtime, SilverStream tries to access the PeopleSoft Message Agents via the Java Message Agent API (JMAC) subsystem.

If SilverStream is not able to locate the JMAC subsystem, SilverStream attempts to access the the Message Agents via the C-based Message Agent API (PSMSG). SilverStream automatically translates the method calls as necessary.

JMAC and connection pools   

During the SilverStream installation, you can configure the SilverStream Server to connect to one or more PeopleSoft servers using the PeopleSoft connection pool. A connection pool is a collection of PeopleSoft JMAC connections that are configured to connect to a specific PeopleSoft server as a specific user.

The connection pool properties are stored in the registry. The pools are used by the PeopleSoft DSOs at runtime to communicate with the PeopleSoft Server. SilverStream supplies the objPSParams class which has methods that allow you to dynamically modify the user identity and connection pool specification during invocations of the PeopleSoft DSO.

SilverStream can support an unlimited number of PeopleSoft connection pools; however, using a very large number of connection pools would likely degrade performance, and is generally not recommended.

Connection pools are only available in installations where JMAC is available. If SilverStream is not able to locate the JMAC subsystem, SilverStream attempts to access the Message Agents via the native PSMSG API described earlier.

Creating a PeopleSoft DSO   

You use the SilverStream PeopleSoft DSO wizard (available from the Business Object Designer) to create the server-side objects that convert PeopleSoft JMAC data to a SilverStream DSO. Each time you run the wizard, SilverStream creates a single DSO object to which you can bind any SilverStream object. The DSO includes code in the General section and the invokeQuery() event.

CAUTION!   Do not modify the wizard-generated code or the DSO will not behave as expected

Before you begin, all of the necessary software must be installed and configured on both client and server machines, and that these machines can successfully communicate.

To build your PeopleSoft DSO:

1. Start the SilverStream Server and Designer.

2. Open the appropriate SilverStream database and choose Objects.

3. Choose the New icon.

   SilverStream displays the New Objects menu shown here:

   

4. Choose New PeopleSoft DSO.

   SilverStream launches the PeopleSoft DataSource Wizard shown here:

   

5. Accept the default JMAC connection pool, or uncheck the Use Default Pool check box and select a different pool from the drop-down list. Choose Next>.

   NOTE   Using a named pool has implications at deployment. If you use a named pool during development and publish the DSO to another server, that server must have a pool of the same name or your DSO will not function properly. If you build the DSO using the default pool, you will not encounter this error because the DSO will just use the default pool for the current server. You can control the pool against which the DSO is running by using the objPSParams described in the About the PeopleSoft API.

   

6. Specify the Message Agent against which this DSO should be built by:
   • Entering the name in the Message Agent text box, and choosing Next>.

   • Choosing a Message Agent from the list box, and choosing Next>.

     

7. Choose the message definitions for Select, Delete, Insert, and Update, or enter your own values, then choose Next>.

   

8. Specify a name for the DSO that the wizard creates, then choose Finish>. You can optionally specify a package in which the DSO should be created. If you do not specify a package, the wizard adds the DSO to the current package if one exists.

   When done, SilverStream updates the Main Designer to display the name of the PeopleSoft DSO that you just created.

Invoking the PeopleSoft DSO   

You bind to and invoke the PeopleSoft DSO in the same way that you invoke all other types of SilverStream DSOs. You can:

• Bind to the DSO using SilverStream's form or page wizard

  SilverStream generates the DSO invocation automatically. Using the Form or Page Wizard is probably the easiest way to bind to the DSO, because SilverStream generates the method calls that invoke the DSO and retrieve the data. It calls the methods in the FormActivate events for forms, and the PageLoaded event for pages.

  See the following section for information about modifying the default invocation to allow parameter passing or other customizations.

• Bind to the DSO programmatically

  Binding programmatically is more work, but provides much more flexibility. See the following section for the details.

Binding programmatically   

To bind to and invoke the DSO programmatically, you must:

1. Choose an appropriate event

2. Construct an objPSParams object that contains any data that you need to pass to the Message Agent. (This is not necessary if the Message Agent does not take any parameters.)

3. Call invokeQuery() on the DSO. You will pass null if the Message Agent does not take any parameters or the objPSParams object constructed in the previous step.

4. Call gotoFirst() on the DSO

In the simplest case, you would have a DSO that did not require any parameters because the Message Agent does not require them. You could simply call invokeQuery() passing null on the DSO as shown here:

  PSDSO.invokeQuery(null); 

If the Message Agent does require information, you pass it using the ObjPSParams.setField() method. The following example shows how to pass an EMPLID parameter with a value of 8887 to the DSO.

  objPSParams opp = new objPSParams(); 
  opp.setField("EMPLID", "8887"); 
  PsParamData.invokeQuery(opp); 

Adding the PeopleSoftServ.JAR

Any PeopleSoft DSO that you create using this wizard requires access to some additional classes which SilverStream supplies. The JAR is called PeopleSoftServ.JAR. You can find this JAR in the SilverMaster database.

You need to add this JAR file to the calling form, page, or business object. You use the File>JAR Files... menu option in the appropriate designer environment.

CAUTION!   Do not change or modify the files in this JAR

About the PeopleSoft API   

The PeopleSoft API includes the following classes:

• objPSParams

• objJmacPoolMgr

About objPSParams

The following table describes how you can use the objPSParams class:

Task	Method declaration
Pass parameters to the DSO	void setField(String name, String value) name is the name of the MessageAgent parameter to pass value is the value of the MessageAgent parameter you are passing to the DSO
Change the caller identity	void setUser(String userName, String pwd) userName is the new identity pwd is the corresponding password
Change the connection pool from the default or from the one it was built against	void setPoolName(String pool) pool is the name of a valid PeopleSoft connection pool. This method is useful when the PeopleSoft Server has failed or if you are deploying a single DSO in multiple environments

About objJmacMgr

The following table describes how you can use the objJmacMgr class:

Task	Method declaration
Obtain the name of the default pool for the server	String getDefaultPool()
Obtain the number of pools that are present on the server.	int getPoolCount() A return value of 0 indicates that JMAC is not available
Obtain a list of Strings representing the names of available pools	Enumeration getPoolNames()
Determine if a pool with the given name is present	boolean poolIsPresent(String name)

Deploying a PeopleSoft DSO   

To deploy a PeopleSoft DSO:

1. Install the PeopleSoft client software on the target server (if not already installed).

2. Install the PeopleSoft DataConnector on the target server (if not already installed).

3. Publish your PeopleSoft DSO object(s).

4. Publish forms and pages.

Considerations for publishing

When you publish the DSO, the original objects will reference the PeopleSoftServ.JAR that exists in the SilverMaster Database. If SilverMaster is named differently on the source and target server, then each of the PeopleSoft DSOs must be modified, otherwise they will not be able to compile.

Note also that use of named JMAC connection pools are also considerations during Publishing. They are described in the section Creating a PeopleSoft DSO.

SilverJRunner, Web pages, and applets require no software installation.