Building C/C++ Services

A C/C++ service is a Java service that calls a C program that you have created. Designer generates the Java code needed to successfully call the C program.

You use Designer to build a set of starter files that you can use to create a C/C++ service.

These files include:

  • A Java service that calls the C program that you have created.
  • A C/C++ source-code template that you use to create your C program.
  • A make file you use to compile the finished program and place it on the server.

The Java Code for a C/C++ Service

When you create a C/C++ service, Designer creates a Java service. This Java service calls the C program that you have created.

The C service is the means by which your C program is exposed to clients. The C service also supplies the input/output parameters for the C program, which makes it possible to include it in a flow service and link its inputs and output on the Pipeline view.

Designer generates all the Java code needed to successfully call your C program. You may add your own custom code to the C/C++ service editor if you want to execute any special procedures before or after executing the C program.

Overview of Building C/C++ Services

In Designer, you use the C/C++ service editor to build C/C++ services. For more information about the C/C++ service editor, see C/C++ Service Editor. The following are the basic tasks you perform to create a C/C++ service:

Task 1 Complete the prerequisite activities mentioned in Prerequisites for Building C/C++ Services.
Task 2 Use Designer to create the C/C++ service element. For more information, see Creating a C/C++ Service.
Task 3 Generate starter code for the service based on the declared input and output parameters. For more information, see Generating C/C++ Code from Service Input and Output Parameters.
Task 4 Add additional code or modify the generated code, if necessary. You can use the Integration Server C/C++API in your service. For more information, see webMethods Integration Server C/C++ API Reference .
Task 5 Specify service properties such as the run time settings, service retry, service auditing, and permissions using the Properties view. For more information, see Building Services.
Task 6 Provide classes required to compile the C/C++ service. You add any additional third-party classes to:
  • Service Development Project in Designer so that Designer can locally compile the service. For more information, see Adding Classes to the Service Development Project.
  • Integration Server so that the server can compile the service. For more information, see information about managing IS packages and how Integration Server stores IS package information in webMethods Integration Server Administrator’s Guide .
Task 7 Compile the C/C++ service. Designer automatically compiles the service when you save it. For more information, see Compiling the C/C++ Source Code.
Task 8 Debug the C/C++ service. The primary way to debug a C/C++ service is to debug the Java class associated with the C/C++ service that Designer maintains in a Service Development Project. For more information, see Debugging C/C++ Services.

Prerequisites for Building C/C++ Services

Keep the following points in mind when creating C/C++ services using the C/C++ service editor:

  • You must have a C/C++ compiler installed on the host where Integration Server is installed.
  • You must complete the procedures specified in Integration Server_directory /sdk/c/README and/or Integration Server_directory /sdk/cpp/doc/README to build the platform support libraries needed by Integration Server and Designer.
  • Designer must be connected to the Integration Server in which you want the C/C++ service to reside.
  • The package in which you want to create the service must already exist. For more information about creating a package, Creating a Package. (If you do not have Developer or Administrator privileges, ask your server administrator to do this.)

    The directory for this package must contain a “code/libs” directory. When you compile your C/C++ service, the make file places the compiled service (a DLL) in this directory. If the package does not already have a code/libs directory, create one before you begin building the service.

  • The folder in which you want to create the service must already exist. For more information, see Creating New Elements.
  • The specification that you want to use to define the inputs and outputs for the service must exist. For more information about specifying a specification, see Using a Specification as a Service Signature.
  • If you are running the Integration Server as an NT service, you must complete one of the following:
    • Set the Windows system environment variable PATH to include Integration Server_directory \lib

      -OR-

    • Copy the wmJNI.dll and wmJNIc.dll files located in Integration Server_directory \lib to the Integration Server_directory

C/C++ Service Editor

Use the Designer C/C++ service editor to create new C/C++ services and to edit existing C/C++ services.

The C/C++ service editor has four tabs:

  • Source tab contains the code for the C/C++ service. For more information about the Source tab, see Source Tab
  • Input/Output tab contains the input and output signature of the C/C++ service. For more information about declaring the input and output parameters for a service, see About the Service Signature.
  • Logged Fields tab indicates the input and output parameters for which Integration Server logs data. For more information about logging the contents of input and output fields, see Logging Input and Output Fields.
  • Comments tab contains the comments or notes, if any, for the C/C++ service.
Note: You can use the Designer C/C++ service editor to edit the C/C++ services that you created in Developer. Additionally, you can use Designer to edit C/C++ services you created with your own IDE, provided that you properly commented them as described in Building Java Services in Your Own IDE and Adding Comments to Your Java Code for the jcode Utility.

Source Tab

You specify the code for the C/C++ service in the Source tab, which extends the standard Eclipse Java editor. Because the Eclipse Java editor requires source files to be in the local workspace, Designer also requires source files to be in the local workspace. To achieve this, Designer adds Java classes to a Service Development Project, which is a project with extensions to support Java services. For more information, see Service Development Projects in the Local Workspace.

The full capabilities of the Eclipse Java editor are available. These include source code formatting and code completion. However, unlike the Eclipse Java editor, the Designer C/C++ service editor protects the sections of a C/C++ service that contain required code to prevent structural damage to the service. The following illustrates the contents of the Source tab for a newly created service.

Package definition 
package orders.orderStatus;
Add additional imports here 
import com.wm.data.*;
 import com.wm.util.Values;
 import com.wm.app.b2b.server.Service;
 import com.wm.app.b2b.server.ServiceException;
 import com.wm.app.b2b.server.Session;
 import com.wm.util.JournalLogger;
 import com.wm.util.DebugMsg;
Class definition 
public final class checkStatus_SVC
Add extends and implements here  
Primary method definition 
{
    /**
      * The primary method for the C service
      *
      * @param in
       * 
       The input Values      * @return The output Values
      */
     public static final Values checkStatus(Values in)
 {
           // --- <<IS-GENERATED-CODE-1-START>> ---
           Values out = in;
           // --- <<IS-GENERATED-CODE-1-END>> ---
           out = ccheckStatus(Service.getSession(), in);
Add source code for the primary method here 
// --- <<IS-GENERATED-CODE-2-START>> ---
           return out;
 // --- <<IS-GENERATED-CODE-2-END>> ---
   }
Add shared code here 
// --- <<IS-BEGIN-SHARED-SOURCE-AREA>> ---0
    static {
      try {
       System.loadLibrary("orders_orderStatus");
       JournalLogger.log(DebugMsg.LOG_MSG,
             JournalLogger.FAC_PACKAGE,
             JournalLogger.INFO,
    "Loading
native library: orders_orderStatus");
         } catch (UnsatisfiedLinkError e)
 {
            JournalLogger.logError(DebugMsg.LOG_MSG,
            JournalLogger.FAC_PACKAGE,
                 e.getMessage());
         }
       }
       native static Values ccheckStatus(Session
 session, Values in);
 // --- <<IS-END-SHARED-SOURCE-AREA>> ---
Final “}” 
}

Protected Sections of a C/C++ Service

The C/C++ service editor protects certain sections of the C/C++ service and marks these sections by highlighting them in a different color. By default, it uses gray for the shading but you can update your preferences to select a different color. For more information, see Java/C Service Editors Preferences. The sections of the C/C++ service that the C/C++ service editor protects are:

  • Package definition, which is the required code that defines the Java package for the C/C++ service.
  • Class definition, which is the required code that defines the final class for the C/C++ service.
  • Primary method definition, which is the required code that defines the static and final method for the C/C++ service. It defines a single input parameter, a Values object.

    The Values object is the universal container that services use to receive input from and deliver output to other programs. It contains an ordered collection of key/value pairs on which a service operates. A Values object can contain any number of key/values pairs.

    You define the data to pass into the service via the Values object by defining input parameters on the Input/Output tab of the editor. You add code to the primary method that modifies the key/value pairs contained in the Values object. The Values object then becomes the output of the service. The service returns the output parameters you define on the Input/Output tab.

  • Final brace “}”. The C/C++ service editor does not allow you to add code after the final brace “}”.

Editable Sections of a C/C++ Service

You can modify the following sections of the C/C++ service:

  • imports, where you can specify the names of additional Java packages whose classes you want to make available to the current class.
    Note: By default, Designer adds some required imports that you cannot delete. Although you can remove the imports in the C/C++ service editor, Designer adds the required imports back when you save the service.
  • extends, where you can specify a super class for the implementation.
  • implements, where you can specify the Java interfaces that the C/C++ service implements.
    Note: You cannot enter or paste special characters including '{' in the extends or implements section of a C/C++ service.
  • source code, where you add the code for the primary C/C++ service method.
  • shared code, where you can specify declarations, methods that will be shared by all services in the current folder.
    Note: The shared code section of the C/C++ service editor contains the code that loads the library that contains the C/C++ program.

The toolbar and icons that the Source tab uses are the same as the buttons and icons used in the standard Eclipse Java editor. For a description, see the Eclipse Java Development User Guide.

Service Development Projects in the Local Workspace

Because the C/C++ service editor requires that some files exist in the local workspace, Designer creates a Service Development Project in the local workspace to store files associated with a C/C++ service. Also, if a C/C++ service requires additional class or jar files so that Designer can compile the service, you add class and jar files to the Service Development Project. Designer creates one Service Development Project per package containing a C/C++ service.

When you create a C/C++ service, Designer adds a Java class associated with the C/C++ service to a Service Development Project. If a Service Development Project does not already exist for a C/C++ service, Designer creates one. You can use the Project Explorer or Package Explorer to view the Service Development Projects.

About the Service Development Project Name

The Service Development Projects correspond to Integration Server packages. To ensure that the project names are unique, Designer uses the following naming convention, where packageName is the name of the IS package where the service resides, hostName is the host name of the Integration Server on which the service resides, and portNumber is the port number of the Integration Server:

<packageName>[<hostName>_<portNumber>]

For example, if the host name of the Integration Server is “ServerA”, its port is “5555” and the IS package is named “MyPackage”, the Service Development Project will have the following name:

MyPackage[ServerA_5555]

Format of a Service Development Project

The Service Development Project contains:

  • JRE system library
  • “src” folder that contains Java packages

    Designer creates Java packages that correspond to a C/C++ service's IS namespace and places them within the “src” folder of the project. For example, if a C/C++ service resides in the folder folderA.folderB, Designer creates the Java package “folderA.folderB” within the Service Development Project.

  • Default .jar files that Designer includes in the project’s classpath

    Designer adds several default .jar files to the project. These files are listed in uppercase (for example, IS_CLIENT and IS_SERVER).

  • “class” folder where you can add any additional Java classes that your C/C++ service require; see Adding Classes to the Service Development Project
  • “lib” folder where you can add any additional Java classes that are packaged in jar files; see Adding Classes to the Service Development Project
Note: You might still need to add additional classes and jar files to Integration Server so that Integration Server can compile the service. For more information about managing IS packages and how Integration Server stores IS package information, see webMethods Integration Server Administrator’s Guide .

The following shows the format of a Service Development Project and an example.

Format Example 
- projectName  
   + JRE System Library  
   - src  
      +javaPackageName(1)  
      .  
      .  
      .  
      +javaPackageName(n)  
   + classes  
   + defaultJarFile(1)  
   .  
   .  
   .  
   + defaultJarFile(n)  
   + lib
 
- MyPackage[ServerA_5555]  
   + JRE System Library  
   - src  
      - folderA  
      - folderA.folderB  
   + classes  
   + IS_CLIENT  
   + IS_SERVER  
   .  
   .  
   .  
   + lib

How C/C++ Services Are Organized on Integration Server

A C/C++ service is a public static method in a Java class file on Integration Server. C/C++ services follow a simple naming scheme:

  • The service name represents the Java method name.
  • The interface name represents the fully-qualified Java class name.

Because Java class names cannot contain the “.” character, services that reside in nested folders are implemented in a class that is scoped within a Java package. For example, a service named recording.accounts:createAccount is made up of a Java method called createAccount in a Java class called accounts within the recording package.

All C/C++ services that reside in the same folder are methods of the same class.

When you build a C/C++ service with Designer, the system automatically combines your service into the class file associated with the folder in which you created it.

Creating a C/C++ Service

About this task

Before you can create a C/C++ service, make sure the following conditions are true:
  • The Integration Server on which you want the C/C++ service to reside is running and connected to Designer.
  • You have locked all C/C++ services in the folder in which you want to create the new service. For more information, see Guidelines for Locking Java and C/C++ Services.
  • If you want to use Unicode characters in the C/C++ service, you need to change the text file encoding preference. To do so, in the Workspace preferences, select Other under Text file encoding and select or type a new encoding.

To create a C/C++ service

Procedure

  1. In the Package Navigator view of Designer, select File > New > C Service.
  2. In the New C Service dialog box, select the folder in which you want to save the service.
  3. In the Element name field, type the name for the C/C++ service.
  4. If you have a template you want to use to initialize a default set of properties for the service, select it from the Choose template list. If you want to apply the default properties to the service, select Default from the Choose template list. Click Next.
  5. Select the platform that describes the machine on which your Integration Server is running (Designer needs to know this in order to build the right make file). Click Next.
  6. Select the specification that defines the inputs and outputs for this service.
  7. Click Finish. Designer refreshes the Package Navigator view and displays the new service in the C/C++ service editor.
  8. Specify service properties using the Properties view.
    To... See...
    Specify the service run-time parameters About Service Run-Time Parameters
    Configure the service to retry automatically if the service fails because of an ISRuntimeException About Automatic Service Retry
    Track when the service is started and completed and whether the service succeeded or failed About Service Auditing
    Assign a universal name to the service About Universal Names for Services or Document Types
    Assign an output template to the service About Service Output Templates
  9. Optionally, generate starter code for the service based on the declared input and output parameters.

    Designer adds initial code to the C/C++ service. For all C/C++ services, Designer adds the package definition, class definition, primary method definition, and a minimum set of imports. If the service is the second or subsequent C/C++ service created in the same IS folder, Designer also adds any shared code defined in other C/C++ services in the IS folder, additional imports, extends, and implements.For more information, see Generating C/C++ Code from Service Input and Output Parameters.

  10. Add and modify the code on the Source tab. You can specify declarations, methods to the initial code that Designer generates.

    You can use the webMethods Integration Server Java API in your service. For more information, see webMethods Integration Server Java API Reference .

  11. Optionally, specify usage notes or comments in the Comments tab.
  12. Select File > Save.

    Designer compiles the C/C++ service on Integration Server and displays the compilation error messages from the server. Designer also writes the error messages to the Designer log file making them visible within the Error Log view.

    When you create a C/C++ service, Designer generates a source code file and a make file and places these files in the following directory:

    Integration Server_directory \instances\instance_name\packages\packageName\code\source

    The names of the files will match the service name you specified in Designer. The source code file will be named <servicename>.c and the make file will be <servicename>.mak.

    Designer also compiles the C/C++ service locally in the Service Development Project. Additionally, if the workspace preference Build Automatically is selected, Designer rebuilds other classes in the Service Development Project at the same time. Designer adds compilation errors from the local compilation to the Problems view. If Problems view is not already open, you can open it by selecting Window > Show View > Problems. To view the line of code that caused the error, double click on the error in the Problems view and Designer shifts focus to the C/C++ service editor, with the cursor positioned at the line of code that caused the error. For more information, see Compiling the C/C++ Source Code.
    Note: If your C/C++ service requires additional classes to compile, you must add them, either as individual class files or in jar files, to both the Service Development Project and to Integration Server. If you have set up IS package dependencies for a C/C++ service and if the service requires classes or jar files in these IS packages to compile, you must manually add the classes or jar files to Service Development Project. For more information, see Adding Classes to the Service Development Project. For more information about adding classes to Integration Server and how Integration Server stores package information, see webMethods Integration Server Administrator’s Guide .

Editing an Existing C/C++ Service

You can use the Designer C/C++ service editor to edit C/C++ services that were created in Designer or Developer. Additionally, you can use Designer to edit C/C++ services you created with your own IDE, provided that you properly commented them as described in Building Java Services in Your Own IDE and Adding Comments to Your Java Code for the jcode Utility.

Keep the following points in mind when editing an existing C/C++ service:

  • You have the C/C++ service locked for edit. If you attempt to edit a C/C++ service that you have not locked for edit, you can still open it in the C/C++ service editor. However, the source code, properties, inputs, and outputs will be read only.
  • If you want to use Unicode characters in the C/C++ service, you need to change the text file encoding preference. To do so, in the Workspace preferences, select Other under Text file encoding and select or type a new encoding.
Important: Software AG recommends that you do not update the service signature of the C/C++ service in the Input/Output tab of the C/C++ service editor.

Generating C/C++ Code from Service Input and Output Parameters

About this task

If you know the set of input and output parameters that a C/C++ service will use before you start coding it, you can declare the service’s input/output parameters first and generate C/C++ code from it. The generated code obtains the specified input values from the service’s input signature and assigns them to variables in your service. It also puts the set of output values into the output signature.

You do not have to generate code for all the input and output parameters. You can choose to generate code for only the input parameters, only the output parameters, or you can select one or more input/output parameters for which to generate code.

When Designer generates code from the service input/output parameters, it puts the code on the clipboard. From there, you can paste it into your service and modify it as necessary.

Generating the code from the service input and output parameters is an optional task. It helps save time when you are reusing the input and output parameters of a C/C++ service.

To generate starter code from a C/C++ service’s input/output parameters

Procedure

  1. In the Service Development perspective, open the C/C++ service by double clicking it in the Package Navigator view.
  2. If you want to generate code for a subset of the input/output parameters, on the Input/Output tab, select the parameters for which you want to generate code. To select more than one variable, press the CTRL key as you select parameters.
  3. Right click in the editor to view the context menu, and select Generate Code.
  4. In the Code Generation dialog box, select For implementing this service and click Next.
  5. For Specification, select the Input and/or Output check boxes to select the parameters for which you want to generate code.
  6. For Which fields? select one of the following:
    • All fields if you want to generate code for all of the parameters identified by your Specification selection.
    • Selected fields if you want to generate code for only the parameters you selected before starting the code generation.
  7. Click Finish. Designer generates code and places it on the clipboard.
  8. Select the Source tab.
  9. Paste the contents of the clipboard into your source code.
  10. Save the C/C++ service.

Adding Classes to the Service Development Project

About this task

If a C/C++ service requires additional classes to compile, you must add them to the following locations:
  • Service Development Project in the local workspace so that Designer can compile the service.
  • Integration Server so that the server can compile the service. Designer does not automatically propagate classes that you add to the Service Development Project to Integration Server; you must add them to Integration Server manually. For more information about adding classes to Integration Server, see information about managing IS packages and how Integration Server stores IS package information in webMethods Integration Server Administrator’s Guide .

Keep the following points in mind when adding classes to the Service Development Project:

  • You add individual class files to the “classes” folder of the Service Development Project.
  • If you have Java classes that are packaged together in jar files, you add the jar files to the “lib” folder of the Service Development Project.
  • If you have set up IS package dependencies for a C/C++ service and if the service requires classes or jar files in these IS packages to compile, you must manually add the classes or jar files to Service Development Project.

To add classes and jar files to the Service Development Project

Procedure

  1. Open the Project Explorer view.
  2. Expand the Service Development Project for the C/C++ service.
  3. If you want to add class files to the Service Development Project, drag them from the file system into the “classes” folder of the Service Development Project in the Project Explorer view.

    When adding class files, ensure that you keep the structure of the Java package intact. For example, if you want to add com.accounting.orders.statusClass.class, you must first create the “com”, “accounting”, and “orders” folders within the “classes” folder as shown below: 

    - classes  
  - com  
    - accounting  
      - orders

    Then add the statusClass.class file to the “orders” folder.

    Important: Do not maintain the Java source files for these classes within the Service Development Project.
  4. If you want to add jar files to the Service Development Project, drag them from the file system into the “lib” folder of the Service Development Project in the Project Explorer view.

    If you have the Build automatically Workspace preference selected, after adding new class and/or jar files to the Service Development Project, Designer automatically rebuilds the project. If you have the Build automatically preference turned off, you can force a rebuild by selecting Project > Build Project. You set the Build automatically preference using Window > Preferences > General > Workspace.

    After the project is rebuilt, Designer removes the compilation errors, if any, from the Problems view. However, the errors might still exist for the Folder class that resides in Integration Server.

    To correct the error, first, ensure that Integration Server has access to the required class and jar files. Then, open the C/C++ service in the Designer and save it again to force the compilation of the service on Integration Server.

Building the C/C++ Source Code

About this task

When you create a C/C++ service, Designer generates a source code file and a make file and places these files in the following directory:

Integration Server_directory \instances\instance_name\packages\packageName\code\source

The names of the files will match the service name you specified in Designer. The source code file will be named <servicename>.c and the make file will be <servicename>.mak.

You create the C/C++ program in the serviceNameImpl.c file, not the original file. The serviceNameImpl.c file is the file in which the make file expects to find your source code. This step is taken to maintain a copy of the original source file to which you can refer, or revert to, during the development process.

To build the C/C++ source code

Procedure

  1. Locate the source code and make files. The source code file will be named <servicename>.c and the make file will be <servicename>.mak.
  2. Copy the source code file to a new file (in the same directory) with the following file name:

    serviceNameImpl.c

    For example, if your service name is PostPO, you would create a copy of PostPO.c and name it PostPOImpl.c.

  3. Edit the serviceNameImpl.c file as necessary to build your service.

    This file contains instructive comments that will guide the development process. You can also refer to webMethods Integration Server C/C++ API Reference for information about how to use the webMethods C/C++ API to make the data in your service available to other services.

  4. Edit the make file to customize it for your development environment. Set the following path settings:
    Set... To...
    JDKDIR The directory that contains the Java Development Kit.
    SEVRDIR The directory in which webMethods Integration Server is installed.
    Important: The source code file serviceName.c contains code based on the specification you used to define the inputs and outputs for the service. If you edit the specification, you need to regenerate the source code file. Designer does not update the serviceName.c file automatically. For more information about generating source code files for a C/C++ service, see Creating a C/C++ Service.
  5. After you finish coding your service, run your make file to compile it. Following is a typical make command:

    make –f SalesTax.mak

    The make file compiles your program and puts the finished DLL in the code\libs directory in the package in which the service resides. If this directory does not exist when you run the make file, your program will not compile successfully.

  6. Once your program compiles successfully, restart Integration Server to reload the code\libs directory. This makes the service available for execution and allows you to test it with Designer. For details on testing, see Debugging C/C++ Services.

Compiling the C/C++ Source Code

About this task

When you save a C/C++ service, Designer automatically compiles the C/C++ service in the Service Development Project and on Integration Server.

Keep the following points in mind when you are compiling a C/C++ service:

  • You must add any additional Java classes that the C/C++ service requires to both the Service Development Project and to Integration Server. For more information, see Adding Classes to the Service Development Project. For more information about adding classes to Integration Server, see information about managing IS packages and how Integration Server stores IS package information in webMethods Integration Server Administrator’s Guide .
  • Make sure you have a C/C++ compiler installed on the host where Integration Server is installed.
  • When compiling the C/C++ service locally, Designer uses the default Java compiler settings. You can update these settings by updating the Service Development Project’s Java Compiler properties.
  • By default, the Service Development Project uses the default JRE that is configured for Designer. You can configure a different JRE using the Service Development Project’s Java Build Path properties and setting a new JRE on the Libraries tab.

To compile a C/C++ service

Procedure

  1. If the service is not open in the C/C++ service editor, open it by double clicking the C/C++ service in the Package Navigator view.
  2. Select File > Save to save and compile the C/C++ service.

Results

Designer displays compilation errors from compiling the service in:

  • Problems view for compilation errors from locally compiling the service

    If Problems view is not already open, you can open it by selecting Window > Show View > Problems.

    To view the line of code that caused the error, double click on the error in the Problems view. Designer shifts focus to the C/C++ service editor, with the cursor positioned at the line of code that caused the error.

  • Compiler Messages window for compilation errors from Integration Server

    Designer writes the error messages from the server to the Designer log file, making them visible within the Error Log View.

    If you receive errors because the Java compiler cannot be found in Integration Server, ensure you have a Java compiler installed on the same machine as Integration Server and that you have added the location of the Java compiler to the system path.

Performance When Compiling a C/C++ Service

When Designer compiles the service locally, by default, it also rebuilds other classes in the Service Development Project. If you notice slower performance when you save the service, you can prevent Designer from rebuilding the other classes by updating the workspace preferences. Note that sometimes it is only the first attempt to save a C/C++ service that takes a long time and future compilations might go faster.

If you want to turn off the rebuild of other classes in the Service Development Project, select Window > Preferences > General > Workspace and clear the Build Automatically check box. This preference affects all projects in the workspace. If you turn off automatic builds, you can manually force a build by selecting Project > Build Project.

Generating Code a C/C++ Service Can Use to Invoke a Specified Service

About this task

You can have Designer generate the code that invokes a selected service, which you can then add to a C/C++ service. Designer generates code that:

  • Creates a Values object based on the service’s declared input parameters
  • Invokes the selected service passing it the Values object and catching exceptions
  • Retrieves the returned Values object from the selected service
  • Uses the key/value pairs in the returned Values object to assign variables based on the declared output parameters of the selected service

You do not have to generate code for all the input and output parameters. You can select to generate code for only the input parameters, only the output parameters, or you can select one or more input/output parameters for which to generate code.

When Designer generates code from the service input/output parameters, it puts the code on the clipboard. From there, you can paste it into a C/C++ service and modify it as necessary.

To generate code to invoke a service

Procedure

  1. In the Package Navigator view, open the service that you want to invoke.
  2. If you want to generate code for a subset of the input/output parameters, on the Input/Output tab, select the parameters for which you want to generate code. To select more than one variable, press the CTRL key as you select parameters.
  3. In the editor, right click the service to view the context menu, and select Generate Code.
  4. In the Code Generation window, select For calling this service from another service and click Next.
  5. For Specification, select the Input and/or Output check boxes to reflect the parameters for which you want to generate code.
  6. For Which Fields? select one of the following:
    • All Fields if you want to generate code for all of the parameters identified by your Specification selection.
    • Selected Fields if you want to generate code for only the parameters you selected before starting the code generation.
  7. Click Finish. Designer generates code and places it on the clipboard.
  8. Paste the contents of the clipboard into a C/C++ service.

Debugging C/C++ Services

A C/C++ service is a Java service that calls the C program that you have created. Designer generates the Java code needed to successfully call your C program. In Designer, the primary way to debug a C/C++ service is to debug the Java class associated with the C/C++ service that Designer maintains in a Service Development Project.

When debugging a C/C++ service in this way, you can debug the primary method and shared code of the Java class that represents the C/C++ service. To debug the Java class, you launch it in debug mode and use the JDT debugger to suspend/resume the execution of the Java class, inspect variables, and evaluate expressions.

The actions you take when debugging a C/C++ service are:

  • Optionally set breakpoints to identify locations where you want the debugger to suspend execution when running the Java class in debug mode. For more information, see How to Suspend Execution of a Java Class while Debugging.
  • Generate a test harness, which is a Java class that you generate for the C/C++ service you want to debug. The logic that Designer generates for the test harness sets up the inputs, invokes the Java class, and displays the outputs.
  • Optionally create a Java Application launch configuration to configure settings for debugging the Java class. For example, you might want to set JVM arguments to match the settings Integration Server uses so that your test more closely matches how the C/C++ service would execute in Integration Server. For more information, see About Java Application Launch Configuration. If you do not create a launch configuration, Designer creates one on the fly and saves it locally in an unexposed location of your workspace.
  • Launch the test harness in debug mode. The test harness prompts for input values and then launches the Java class you want to debug in debug mode.

    By default, the debugger executes the Java class using the JRE in the Service Development Project where the C/C++ service resides. You can change the Service Development Project’s JRE by updating the project’s Java Build Path property. You can also specifically identify the JRE to use for debugging by identifying the JRE in the Java Application launch configuration.

    If the Java class being debugged invokes a service, the invoked service runs in Integration Server. The debugger treats the statement to invoke a service like any executable line of code in the Java class; that is, you can Step Over it and see results from it. You cannot use the debugger to Step Into the invoked service.

    If the debugger suspends execution of the service, Designer switches to the Debug perspective. The Debug view will show the test harness class and be positioned at the statement where the execution was suspended. You can use the other views in the Debug perspective to inspect the state of the C/C++ service to this point. You can use the actions in the Debug view toolbar to resume the execution. For more information about suspending execution, see How to Suspend Execution of a Java Class while Debugging.

    When the execution of the C/C++ service completes, the debugger displays a window that contains the service results.

For more information about debugging the C/C++ service by debugging its Java wrapper, see Debugging Java Services.