Programming Component Interfaces in C++

This chapter discusses how to:

• Build the APIs for C++.

• Set up the C++ environment.

• Generate C++ runtime code templates.

• Understand the C++ template.

Building APIs for C++

If you plan to access your component interface from a C++ external application, you must create a component interface API. The APIs are in the form of C header files (*.h), which need to be included in the calling program.

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 C Header Files group box.

   For the target directory, enter the directory in which you want the C++ header file to be created, typically <PS_HOME>\bin\client\winX86.

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

   The peoplesoft_peoplesoft._i.h file that constitutes the bindings is built in the location that you specified. If the operation was successful, a Done message appears in the PeopleSoft Application Designer Build window.

Setting Up the C++ Environment

When deploying component interfaces on a local client machine with C++ bindings, you must have:

• The third-party C++ application.

• The Application server and database.

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

• Your compiler, configured for the C++ project.

Third-Party Applications

For applications written in C or C++, note that:

• The function names generated by the Build APIs process can be quite long. You may want to consider creating classes within your C++ code to mask this length throughout your program.

• When you create your installation for your C or C++ program, make sure that you include the setup of the path to the psapiadapter.dll.

Setting Up Client Machines to Access C++ APIs

To set up your client machine to access the component interface API using C++:

1. Install the PeopleSoft File Server.

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

2. Install the JVM supplied with the Sun Microsystems JDK. The JVM is located in the %PS_HOME%\JRE directory.

3. 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 install is done locally, the path is <PS_HOME>\jre\bin\client.

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

5. Set the environment variable PS_HOME to point to the installed PeopleSoft PeopleTools directory (for example, c:\pt849).

Configuring Compilers for C++ Projects

To configure a compiler for the C++ project:

Note. These instructions assume that you are using Microsoft Visual C++. If you use a different compiler, apply the equivalent settings for that product.

1. Create a new project in Microsoft Visual C++.

2. Select Tools, Options.

3. Select the Directories tab.

4. Click the New button in the Options dialog box.

5. Enter the path to the SDK include files, for example:

   C:\PT840\SDK\PSCOMPINTFC\SRC\C++\SAMPLES\INC

6. Click OK to save the options.

7. Open the Project Settings dialog box.

8. Select the C/C++ tab.

9. Select the General category.

10. Add PS_WIN32 to the preprocessor definitions.

11. Select the Link tab.

12. Select the Input category.

13. Specify the full path to psapiadapter.lib for the Object/library modules.

    This is typically <PS_HOME>\src\lib\psapiadapter.lib. Make sure that this is the only entry for psapiadapter.lib.

14. Click OK to save the settings.

Generating C++ Runtime Code Templates

To access a component interface through external APIs using C++, PeopleSoft Application Designer generates a template in the form of boilerplate C++ code that you can adapt to your purposes.

External C++ APIs are located in the <PS_CFG_HOME>\ExtAPI_C directory.

This section describes how to generate the template code.

To generate a C++ template for a component interface:

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

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

3. Select Generate C 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. Add the generated template file to the project.

   In Microsoft Visual C++:

   1. Open the project created earlier.

   2. Select Project, Add To Project, Files.

   3. Select the generated file.

   4. Click OK.

5. Edit the generated file and modify the source code to suit your needs.

6. Build the project to generate an executable (.exe) file.

Understanding the C++ Template

The C++ template can be used as a starting point for your C++ program. This section contains a skeleton of the generated C++ template for a component interface named SDK_BUS_EXP, which is part of the component interface SDK. The template has been edited for length.

Include all the required header files.

#ifdef PS_WIN32
#include "stdafx.h"
#endif
 
#include "cidef.h"
#include "apiadapterdef.h"
#include "PSApiAdapterInter.h"
#include "PSApiExternalLib.h"
#include "peoplesoft_peoplesoft_i.h"
#include <stdio.h>
#include <iostream.h>
#include <wchar.h>
 
HPSAPI_SESSION hSession;
TCHAR tmpValue[1024];
 
.....
 
void main(int argc, char* argv[])
{
   //***** Set Connect Parameters *****
   TCHAR strServerName[40], strServerPort[10], strAppServerPath[80];
   TCHAR strUserID[80], strPassword[80];
   .....
 
   //Build Application Server Path
   _stprintf(strAppServerPath, _T("%s:%s"), 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 that 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 perform error handling for all APIs from a central location.

   //***** Create PeopleSoft Session *****
   PSAPIVARBLOB ExternalAuth;
   memset(&ExternalAuth, 0, sizeof(PSAPIVARBLOB));
   hSession = PSApiCreateSession();
   if (!hSession)
   {
      wprintf(L"\nUnable to Create Session\n");
      return;
   }

Connect to the Application server by using the Session_Connect() function.

   //***** Connect to the App Server *****
   if (!Session_Connect(hSession, 1, strAppServerPath, strUserID, strPassword,⇒
 ExternalAuth))
   {
      wprintf(L"\nUnable to Connect to Application Server\n");
      ErrorHandler();
      return;
   }

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

   //***** Get Component Interface *****
   HPSAPI_SDK_BUS_EXP hSdkBusExp;
   TCHAR ciName[30];
   _tcscpy(ciName, _T("SDK_BUS_EXP"));
   hSdkBusExp = (HPSAPI_SDK_BUS_EXP) Session_GetCompIntfc(hSession, 
      ciName);
   if (!hSdkBusExp)
   {
      wprintf(L"\nUnable to Get Component Interface %s\n", ciName);
      ErrorHandler();
      return;
   }
 
   //***** Set the Component Interface Mode *****
   SdkBusExp_SetInteractiveMode(hSdkBusExp, false);
   SdkBusExp_SetGetHistoryItems(hSdkBusExp, true);
   SdkBusExp_SetEditHistoryItems(hSdkBusExp, false);

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

   //***** Set Component Interface Get/Create Keys *****
   TCHAR strSdkEmplid[80];
   wprintf(L"\nEnter SdkEmplid: ");
   _getts(strSdkEmplid);
   SdkBusExp_SetSdkEmplid(hSdkBusExp, strSdkEmplid);

The <CI_NAME>_Get() function retrieves data from the database associated with the key values.

   //***** Execute Get *****
   if (!SdkBusExp_Get(hSdkBusExp))
   {
      wprintf(L"\nUnable to Get Component for the Search keys provided.\n");
      ErrorHandler();
      return;
   }

Get and print properties at level 0.

   wprintf(L"SdkBusExp.SdkName: %s\n", 
      printProperty(SdkBusExp_GetSdkName(hSdkBusExp), tmpValue));

Similar code is generated for the properties SDK_BIRTHDATE and SDK_DEPTID.

Get collection at level 1 (SDK_BUS_EXP_PER).

   HPSAPI_SDK_BUS_EXP_SDK_BUS_EXP_PERCOLLECTION 
      hSdkBusExpSdkBusExpPerCollection;
   HPSAPI_SDK_BUS_EXP_SDK_BUS_EXP_PER hSdkBusExpSdkBusExpPer;
   hSdkBusExpSdkBusExpPerCollection = 
       SdkBusExp_GetSdkBusExpPer(hSdkBusExp);

Get and print properties at level 1.

   for (int i17 = 0; i17 < SdkBusExpSdkBusExpPerCollection_GetCount
                         (hSdkBusExpSdkBusExpPerCollection); i17++)
   {
      hSdkBusExpSdkBusExpPer = SdkBusExpSdkBusExpPerCollection_Item
                          (hSdkBusExpSdkBusExpPerCollection, i17);
      wprintf(L"oSdkBusExpSdkBusExpPer.SdkExpPerDt: %s\n", 
         printProperty
      (SdkBusExpSdkBusExpPer_GetSdkExpPerDt(hSdkBusExpSdkBusExpPer), 
         tmpValue));

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).

      HPSAPI_SDK_BUS_EXP_SDK_BUS_EXP_PER_SDK_BUS_EXP_DTLCOLLECTION 
         hSdkBusExpSdkBusExpPerSdkBusExpDtlCollection;
      HPSAPI_SDK_BUS_EXP_SDK_BUS_EXP_PER_SDK_BUS_EXP_DTL 
         hSdkBusExpSdkBusExpPerSdkBusExpDtl;
      hSdkBusExpSdkBusExpPerSdkBusExpDtlCollection = 
      SdkBusExpSdkBusExpPer_GetSdkBusExpDtl(hSdkBusExpSdkBusExpPer);

Get and print properties at level 2.

      for (int i211 = 0; i211 < 
          SdkBusExpSdkBusExpPerSdkBusExpDtlCollection_GetCount
         (hSdkBusExpSdkBusExpPerSdkBusExpDtlCollection); i211++)
      {
         hSdkBusExpSdkBusExpPerSdkBusExpDtl = 
            SdkBusExpSdkBusExpPerSdkBusExpDtlCollection_Item
            (hSdkBusExpSdkBusExpPerSdkBusExpDtlCollection, i211);
 
         wprintf(L"oSdkBusExpSdkBusExpPerSdkBusExpDtl.SdkChargeDt: 
            %s\n", printProperty
            (SdkBusExpSdkBusExpPerSdkBusExpDtl_GetSdkChargeDt
           (hSdkBusExpSdkBusExpPerSdkBusExpDtl), tmpValue));

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.

      }
   }

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 *****
   Session_Disconnect(hSession);
 
   return;
}