EntireX Adapter Services

This document describes how to configure and manage EntireX Adapter services. EntireX Adapter services allow clients to interact with EntireX RPC servers, Natural RPC servers, ACI servers, ApplinX, IMS Connect, and CICS ECI using a configured adapter connection. EntireX Adapter services are available for synchronous and asynchronous RPC calls (RPC and reliable RPC).

The following topics are covered:


Before Configuring or Managing Adapter Services

Start of instruction setTo prepare configuration and management of EntireX Adapter services

  1. Start your Integration Server and the IS Administration Console, if they are not already running.

  2. Make sure you have webMethods administrator privileges so that you can access the EntireX Adapter's administrative screens. See the Administering webMethods Integration Server for information on setting user privileges.

  3. Using the IS Administration Console, make sure the WmEntireX package is enabled. See Enabling and Disabling Packages for instructions.

  4. Start the Designer if it is not already running.

  5. Make sure you are viewing the Designer in the Service Development perspective, as described in Switching Perspectives in the Designer help.

  6. Using the Designer, create a user-defined package to contain the service, if you have not already done so. Add a dependency on WmEntireX package (version *.*) to your user-defined package. When you configure adapter services, you should always define them in user-defined packages rather than in the WmEntireX package. See Package Management.

  7. Generate the adapter connection with the EntireX Workbench.

    Or:
    Using the IS Administration Console, configure an adapter connection to use with the adapter service. See EntireX Adapter Connections for instructions.

Configuring Adapter Services

The EntireX Adapter service enables you to send RPC calls to an EntireX RPC server or Natural RPC server. You configure EntireX Adapter services using a specific adapter connection. After you follow the steps in this section to configure the adapter service, you can invoke it from a flow or Java service. To use EntireX Adapter services, you provide values for the service's input signature in the pipeline. See Using Adapter Services.

Start of instruction setTo create EntireX Adapter services

  1. In the EntireX Workbench, select the Software AG IDL file to use.

  2. In the context menu, choose Generate webMethods IS Connection from Software AG IDL....

Using Adapter Services

Start of instruction setTo enable the EntireX Adapter service to send an RPC call to an EntireX RPC server

  • Provide values for the parameters in the service's input signature when configuring the adapter service within a flow service in the Designer. You can either map in values from the pipeline, or you can set constant values using the Pipeline View.

    This has the following effect on the input and output signature:

    • The input signature of an adapter service wraps all input parameters of the EntireX subprogram in the inRec.

      A parameter throwException is added to the signature. If this optional parameter is set to "true", errors are returned as exceptions and not by means of parameters in the output signature. A parameter $connectionname is added to the signature. If this optional parameter

      A parameter throwException is added to the signature. If this optional parameter is set to "true", errors are returned as exceptions and not by means of parameters in the output signature.

      A parameter $connectionname is added to the signature. If this optional parameter, is set to a connection name, it overrides the default connection name of the service.

      Depending on the connection type, adapter services have optional parameters that can be used to overwrite the corresponding values of the connection. These optional parameters are:

      • CICS ECI Connection
        • RACF user ID

        • RACF password/PassTicket

        • CICS Mirror Transaction ID

      • EntireX Direct RPC Connection
        • RPC library name

        • RPC user

        • RPC password

        • Server address

      • EntireX RPC Connection / EntireX Reliable RPC Connection
        • Logon user

        • Logon password

        • RPC library name

        • RPC user

        • RPC password

        • Server address

      • IMS Connect Connection
        • Logical terminal ID

        • RACF user ID

        • RACF password/PassTicket

        • RACF group name

        • RACF application name

        • IMS datastore ID

        • Maximum segment length

      • EntireX ACI Connection
        • Logon user

        • Logon password

      See EntireX Adapter Connections for details on the parameters.

    • The output signature of an adapter service wraps all output parameter of the EntireX subprogram in the outRec. Three parameters errorFlag, errorMessage (optional), and errorCode are added to the signature. If errorFlag is true, errorMessage contains the error message. errorCode contains "00000000" for a successful call, otherwise the EntireX message class (4 digits) and message code (4 digits).

Viewing Adapter Services

Use the Designer to view adapter services. Make sure you are viewing the Designer in the Service Development perspective, as described in Switching Perspectives in the Designer online help.

Start of instruction setTo view a service

  1. In the Designer Package Navigator view, expand the package and folder that contain the service you want to view.

  2. Select the service you want to view. The Designer displays the service in the Service Editor.

    As a result, the Adapter Service Editor for the EntireX Adapter service appears.

    Notes:

    1. You can select the Adapter Settings tab at any time to confirm adapter service properties such as the Adapter Name, Adapter Connection Name, and Adapter Service Template, as necessary.
    2. On the RPC Call tab, the EntireX Subprogram Name field holds the name of the IDL program called by this service. The tables Input Parameter and Output Parameter display names, the IDL types, and the parameter types in the pipeline.
    3. The Input/Output tab shows the service's input and output signatures. To use the EntireX Adapter service, you provide values for the signature input within the service pipeline in the Designer. See Using Adapter Services for instructions on using the EntireX Adapter service.
    4. For information on configuring the Input/Output and Adapter Settings tabs, see webMethods Service Development Help. These tabs apply to all services that you configure using the Designer. The information on Audit and Permissions appears in the Properties panel. For the results, see the Results panel.

Deleting Adapter Services

Use the Designer to delete adapter services. Make sure you are viewing the Designer in the Service Development perspective, as described in Switching Perspectives in the Designer online help.

Start of instruction setTo delete a service

  1. In the Designer Package Navigator view, expand the package and folder that contain the service you want to delete.

  2. Right-click the service and then click Delete.

Runtime Connection Allocation for Adapter Services

Adapter services of the EntireX Adapter are enabled for dynamically selecting a connection node. The connection name may be specified on the pipeline in the $connectionName field. This field has to be part of the services input signature. If $connectionName is not specified, the default connection name is used, usually the connection used to create the service.

See chapter 8 in webMethods Adapter Development Kit User's Guide , version 6.5 for more details on connection selection.

Connection selection is applicable to services that are generated with the EntireX Adapter (version 8.0 or higher) and helps to:

  • Switch between development and test environment
    • Generate the connections and services as usual.

    • Design your services that call the adapter services to set $connectionName to one single connection.

    • Then you can switch to a different environment by changing this single connection to a different resource.

  • Reduce the number of connection pools
    • Generate the connections and services as usual.

    • Then for each IDL library one connection is generated and one connection pool is used at runtime.

    • Design your services that call the adapter services to set $connectionName to one single connection.

    • This reduces the connection pools to a single pool associated with this connection.

Configure the Formatting of Decimal and Alphanumeric Parameters

Adapter services have two parameters to configure the formatting of decimal parameters (IDL data types N, NU, P and PU, and alphanumeric parameters of fixed length (IDL data types A, K, and U).

To set these options, use the Designer and open the adapter service for the EntireX Adapter. In RPC Call, select Parameters for Decimal Numbers (N/P) or Parameters for fixed length Strings (A/K/U).

The following tables give an overview of parameters to be configured:

  • Parameters for Decimal Numbers (N/P)
    (As an example, we use the value "3.14 " for a parameter defined as N7.2 in the IDL.)

    Parameter Example
    Remove leading zeros & keep decimal point (default) 3.14
    Remove leading zeros & remove decimal point 314
    Keep leading zeros & keep decimal point 0000003.14
    Keep leading zeros & remove decimal point 000000314
  • Justify Decimal Numbers (N/P)

    Note:
    This parameter is highly deprecated and should be only used for compatibility with webMethods Mainframe.

    Parameter Explanation
    not justified (default) The field formatting is unchanged.
    left justified The numeric field is left justified.
    right justified The numeric field is right justified.
  • Parameters for fixed length Strings (A/K/U)
    Parameter Explanation
    Remove whitespace characters (default) Trim leading and trailing whitespace characters.
    Keep whitespace characters Format the string with the defined number of characters.
  • Justify fixed length Strings (A/K/U)

    Note:
    This parameter is highly deprecated and should be only used for compatibility with webMethods Mainframe.

    Parameter Explanation
    not justified (default) The field formatting is unchanged.
    left justified The string field is left justified.
    right justified The string field is right justified.

Configuring Null Value Suppression

Null value suppression (NVS) allows you to suppress parameters with no specified value. Suppressed parameters will not appear in the result of the adapter service call. Null value suppression is available for the following IDL data types:

  • all string data types

  • groups and structures

  • arrays

To activate NVS in the context of adapter services, modify each adapter service separately, using Designer. For each adapter service, select Null Value Suppression in RPC Call. You can fine-tune NVS with the following suppression modes:

Suppression Mode Explanation
No suppression (default) No suppression, all parameters are present in the output structure.
Suppress null elements String parameters with empty strings are suppressed, empty structures and arrays are suppressed.
Suppress null elements and trim array cells at end Same as above. In addition, all empty array elements at the end of the array will be removed from the array.
Suppress null elements and trim array cells at end containing null elements and zero numbers Same as above. In addition, numbers of numeric/decimal type (I1, I2, I4, N, P) with the value zero are treated as an empty value.

A string parameter is suppressed if the assigned string is:

  • of type variable length (AV/KV/UV) and the string is empty (same for variable length strings with a maximum length).

  • of type fixed length (A/K/V) and the parameter Remove whitespace characters is enabled, and trimming the leading and the trailing whitespace characters would result in an empty string.