Programming Component Interfaces in COM

This chapter discusses how to:

• Build APIs for COM.

• Set up the COM environment.

• Generate a Visual Basic runtime code template.

• Understand the Visual Basic template.

Building APIs for COM

If you plan to access your component interface from a COM external application, you must create a component interface API. The generated APIs are in the form of registry entries and type library files.

To build the component interface bindings:

1. Open any component interface definition in PeopleSoft Application Designer.

   Use any component interface definition, because you can build APIs for all of them, regardless of which one is open.

2. Select Build, PeopleSoft APIs.

   The Build PeopleSoft API Bindings dialog box appears.

3. Select the Build check box in the COM Type Library group box.

   1. For the target directory, enter the directory in which you want the COM type library to be created, typically <PS_HOME>\bin\client\winX86.

   2. Enter the COM server DLL location to specify where the PeopleSoft API Adapter (psapiadapter.dll) is typically located: <PS_HOME>\bin\client\winX86.

4. (Optional) Select the AutoRegister check box to execute the registry file immediately upon building the API.

   This causes your client machine registry to be updated immediately without having to register the registry entry manually.

5. (Optional) Select the Clean-up Registry check box to clean up the registry if you previously generated the Peoplesoft_Peoplesoft.reg file.

   This is needed so that the older registry settings do not remain and conflict with settings made by the latest version.

6. Click OK to build the bindings that you selected.

   The files that constitute the bindings are built in the location that you specified. If the operation was successful, a Done message appears in the PeopleSoft Application Designer Build window and the client machine should contain a Peoplesoft_Peoplesoft.reg and PeopleSoft_PeopleSoft.tlb file.

Setting Up the COM Environment

When deploying component interfaces on a local client machine or web server with COM bindings, you need to have:

• The third-party COM application.

• The application server and database.

• The Java Virtual Machine (JVM) supplied the with Sun Microsystems Java Development Kit (JDK), found in the %PS_HOME%\JRE directory.

• A copy of the type library called PeopleSoft_PeopleSoft.tlb that you generated during the Build PeopleSoft API Bindings process.

  This type library is not specific to a single database instance—it is specific to those database objects.

• A copy of the registry file called PeopleSoft_PeopleSoft.reg that you generated during the Build PeopleSoft API Bindings process.

  This registry file is not specific to a single database instance.

To set up your client machine to access the component interface API, using COM:

Note. A reboot of the client machine may be required after you follow these steps.

1. Install the PeopleSoft file server.

   See PeopleSoft 8.51 Installation Guide, “Using the PeopleSoft Installer.”

2. Set the environment variable PATH to include the directory containing jvm.dll.

   For example, you might set it to c:\bea\jkd<version>\jre\bin\client; or, if the PeopleTools installation is done locally, the path is <PS_HOME>\jre\bin\client.

3. Set the environment variable CLASSPATH to include the file psjoa.jar (typically <PS_HOME>\class\psjoa.jar).

   Note. The following steps assume that you are using Microsoft Visual Basic. If you use a different compiler, apply the equivalent settings for that product.

4. Open the Visual Project File pscitester.vbp or sdk_bus_exp.vbp in Microsoft Visual Basic.

5. Select Project, References, and add the Peoplesoft_PeopleSoft.tlb type library.

Third-Party Application

Copy the type library and registry files to the directory containing the external API on each client machine from which you want to use the COM API.

Apply the API registry settings by double-clicking Peoplesoft_Peoplesoft.reg.

Warning! The registry file includes references to the external API and type library files and their locations on the original client machine where they were built, so those files must be in the same locations on the current client. If the directory structure is different, you must edit Peoplesoft_Peoplesoft.reg to reflect the current machine before you apply the registry settings.

• If your program is early-binding, the code contains a direct reference to the path of the type library.

  Therefore, as you deploy, you must have the type library in the same directory on each machine.

• If your program is late-binding, the code does not contain a reference to the path of the type library.

  The code looks in the registry for the path to the type library. Therefore, as you deploy, you can have the type library in different directories on each machine. You must update the registry settings as part of the deployment. This is a more flexible approach.

Generating Visual Basic Runtime Code Templates

When you want to access a component interface through external APIs by using Microsoft Visual Basic, PeopleSoft Application Designer generates a template in the form of boilerplate Visual Basic code that you can adapt to your purposes.

External COM APIs are located in the <PS_CFG_HOME>\ExtAPI_ COM directory.

This section describes how to generate the template code.

To generate a Visual Basic template for your component interface:

1. Open the desired component interface definition in PeopleSoft Application Designer.

2. Right-click anywhere in the definition view to display the menu.

3. Select Generate Visual Basic Template.

   When the template is successfully generated, a message appears stating the name and location of the template file.

   Note. The template file is generated in the directory specified by the TEMP or TMP system environment variable on your client machine.

4. Open the generated file and modify the source code as needed.

Understanding Visual Basic Templates

You can use the Visual Basic template as a starting point for your Visual Basic program. This section contains a skeleton of the generated Visual Basic template for a component interface named SDK_BUS_EXP, which is part of the component interface SDK. The template has been edited for length.

Declare the Session object.

Dim oSession As PeopleSoft_PeopleSoft.Session
.....
 
Private Sub main()
   On Error GoTo ErrorHandler
   '***** Set Connect Parameters *****
   Dim strServerName As String, strServerPort As String, 
      strAppServerPath As String
   Dim strUserID As String, strPassword As String
   .....
 
   'Build Application Server Path
   strAppServerPath = strServerName & ":" & strServerPort

Note. To enable Jolt failover and load balancing in the PeopleSoft Internet Architecture, you can supply multiple application server domains for the strAppServerPath variable. Separate the domain names with a comma, and make sure no spaces are included, for example:

strAppServerPath = //APPSRVR1:8000,//APPSRVR2:9000

Create the PeopleSoft Session object to enable access to the PeopleSoft system. The Session object controls the environment and enables you to do error handling for all APIs from a central location.

   '***** Create PeopleSoft Session Object *****
   Set oSession = CreateObject("PeopleSoft.Session")

Connect to the Application server by using the Connect method.

   '***** Connect to the App Server *****
   If Not oSession.Connect(1, strAppServerPath, strUserID, strPassword, 0) Then
      Err.Raise 1001, "", "Unable to connect to Application Server"
      Call ErrorHandler()
      Exit Sub
   End If

Get a reference to the component interface providing its name. A runtime error occurs if the component interface does not exist.

   Dim oSdkBusExp As SDK_BUS_EXP
   Dim ciName As String
   ciName = "SDK_BUS_EXP"
   Set oSdkBusExp = oSession.GetCompIntfc(ciName)
   If oSdkBusExp Is Nothing Then
      Err.Raise 1001, "", "Unable to Get Component Interface " & ciName
      Call ErrorHandler()
      Exit Sub
   End If
 
   '***** Set the Component Interface Mode *****
   oSdkBusExp.InteractiveMode = False
   oSdkBusExp.GetHistoryItems = True
   oSdkBusExp.EditHistoryItems = False

Set the keys for the component interface. In this example, SDK_EMPLID is the Get key.

   '***** Set Component Interface Get/Create Keys *****
   Dim strSDK_EMPLID As String
   strSDK_EMPLID = InputBox("Enter SDK_EMPLID: ")
   oSdkBusExp.SDK_EMPLID = strSDK_EMPLID

The Get method retrieves data from the database associated with the key values.

   '***** Execute Get *****
   If Not oSdkBusExp.Get() Then
      Err.Raise 1001, "", "No rows exist for the specified keys. Failed to get the⇒
 Component Interface"     
 Call ErrorHandler()
      Exit Sub
   End If

Get and print properties at level 0.

   Debug.Print "oSdkBusExp.SDK_NAME: " & oSdkBusExp.SDK_NAME
   oSdkBusExp.SDK_NAME = <*>

Similar code is generated for the properties SDK_BIRTHDATE and SDK_DEPTID.

Get the collection at level 1 (SDK_BUS_EXP_PER).

   Dim oSdkBusExpPerCollection As 
      SDK_BUS_EXP_SDK_BUS_EXP_PERCollection
   Dim oSdkBusExpPer As SDK_BUS_EXP_SDK_BUS_EXP_PER
Set oSdkBusExpPerCollection = oSdkBusExp.SDK_BUS_EXP_PER

Get and print properties at level 1.

   Dim i17 As Integer
   For i17 = 1 To oSdkBusExpPerCollection.Count
      Set oSdkBusExpPer = oSdkBusExpPerCollection.Item(i17)
      Debug.Print "oSdkBusExpPer.SDK_EXP_PER_DT: " & 
         oSdkBusExpPer.SDK_EXP_PER_DT

Similar code is generated for the properties SDK_EMPLID and SDK_BUS_EXP_SUM in the SDK_BUS_EXP_PER collection.

Get collection at level 2 (SDK_BUS_EXP_DTL).

Dim oSdkBusExpDtlCollection As 
   SDK_BUS_EXP_SDK_BUS_EXP_PER_SDK_BUS_EXP_DTLCollection
Dim oSdkBusExpDtl As 
   SDK_BUS_EXP_SDK_BUS_EXP_PER_SDK_BUS_EXP_DTL
Set oSdkBusExpDtlCollection = oSdkBusExpPer.SDK_BUS_EXP_DTL

Get and print properties at level 2.

Dim i211 As Integer 
For i211 = 1 to oSdkBusExpDtlCollection.Count
Set oSdkBusExpDtl = oSdkBusExpDtlCollection.Item(i211)
Debug.Print "oSdkBusExpDtl.SDK_CHARGE_DT: " & 
   oSdkBusExpDtl.SDK_CHARGE_DT

Similar code is generated for the properties SDK_EMPID, SDK_EXP_PER_DT, SDK_EXPENSE_CD, SDK_EXPENSE_AMT, SDK_CURRENCY_CD, SDK_BUS_PURPOSE, and SDK_DEPTID.

      Next
   Next

Disconnect from the Application server by using the disconnect method of the Session object. This method clears the buffers and releases the memory.

   '***** Disconnect from the App Server *****
   If Not oSession Is Nothing Then
      oSession.Disconnect
      Set oSession = Nothing
   End If
   Exit Sub
.....
End Sub