Creating a parallel routine

You can define a parallel routine to be executed before or after a processing stage in the job flow, or as part of an expression in a Transformer stage.

Procedure

  1. Do one of:
    1. Choose File > New from the Designer menu. The New dialog box appears.
    2. Open the Routine folder and select the Parallel Routine icon.
    3. Click OK. The Parallel Routine dialog box appears, with the General page on top.

      Or:

    4. Select a folder in the repository tree.
    5. Choose New > Parallel Routine from the pop-up menu. The Parallel Routine dialog box appears, with the General page on top.
  2. Enter general information about the routine as follows:
    • Routine name. Type the name of the routine. Routine names can be any length. They must begin with an alphabetic character and can contain alphanumeric and period characters.
    • Type. Choose External Function if this routine is calling a function to include in a transformer expression. Choose External Before/After Routine if you are defining a routine to execute as a processing stage before/after routine.
    • Object Type. Choose Library or Object. This option specifies how the C function is linked in the job. If you choose Library, the function is not linked into the job and you must ensure that the shared library is available at run time. For the Library invocation method, the routine must be provided in a shared library rather than an object file. If you choose Object the function is linked into the job, and so does not need to be available at run time. The routine can be contained in a shared library or an object file. Note, if you use the Object option, and subsequently update the function, the job must be recompiled to pick up the update. If you choose the Library option, you must enter the path name of the shared library file in the Library path field. If you choose the Object option you must enter the path name of the object file in the Library path field.
    • External subroutine name. The C function that this routine is calling (must be the name of a valid routine in a shared library).
    • Return Type. Choose the type of the value that the function returns. The drop-down list offers a choice of native C types. This option is unavailable for External Before/After Routines, which do not return a value. Note the actual type definitions in function implementations might vary depending on platform type. This consideration particularly applies to `long' and `unsigned long' C native types. These types should be defined as `long long' and `unsigned long long' in the actual code. Similarly a return type of `char' should be defined as `signed char' in the code on all platforms.
    • Library path. If you have specified the Library option, type or browse on the computer that hosts the engine tier for the path name of the shared library, or library archive, that contains the function. This path name is used at compile time to locate the function. The path name must be the exact name of the library or library archive, and must have the prefix lib and the appropriate suffix. For example, /disk1/userlibs/libMyFuncs.so, c:\mylibs\libMyStaticFuncs.lib, /disk1/userlibs/libMyLibArchive.a. Suffixes are as follows:
      • Solaris - .so or .a
      • AIX - .so or .a
      • HPUX - .sl or .a
      • Windows - .lib
      • Linux - .so or .a

      The suffix .a denotes a library archive. On AIX systems, the suffix .a can denote a library or a library archive.

      For Windows systems, note that the Library path identifies a .lib file, but at run time a .dll file is used. The compiled .dll file must be in the load library search path at run time.

      If you have specified the Object option, enter the path name of the object file. Typically the file is suffixed with .o for UNIX or Linux systems, or .o or .obj for Windows systems. This file must exist and be a valid object file for the linker. There are no restrictions on the file name, other than the suffix.

    • Short description. Type an optional brief description of the routine.
    • Long description. Type an optional detailed description of the routine.
  3. Next, select the Creator page to enter creator information:

    The Creator page allows you to specify information about the creator and version number of the routine, as follows:

    • Vendor. Type the name of the company who created the routine.
    • Author. Type the name of the person who created the routine.
    • Version. Type the version number of the routine. This is used when the routine is imported. The Version field contains a three-part version number, for example, 3.1.1. The first part of this number is an internal number used to check compatibility between the routine and the IBM® InfoSphere® DataStage® system, and cannot be changed. The second part of this number represents the release number. This number should be incremented when major changes are made to the routine definition or the underlying code. The new release of the routine supersedes any previous release. Any jobs using the routine use the new release. The last part of this number marks intermediate releases when a minor change or fix has taken place.
    • Copyright. Type the copyright information.
  4. The last step is to define routine arguments by selecting the Arguments page.

    The underlying functions for External Functions can have any number of arguments, with each argument name being unique within the function definition. The underlying functions for External Before/After routines can have up to eight arguments, with each argument name being unique within the function definition. In both cases these names must conform to C variable name standards.

    Expected arguments for a routine appear in the expression editor, or on the Triggers page of the transformer stage Properties dialog box, delimited by % characters (for example, %arg1%). When actually using a routine, substitute the argument value for this string.

    Fill in the following fields:

    • Argument name. Type the name of the argument to be passed to the routine.
    • I/O type. All arguments are input arguments, so the I/O type can only be set to I.
    • Native type. Offers a choice of the C native types in a drop-down list. Note that the actual type definitions in function implementations might vary depending on platform type. This particularly applies to `long' and `unsigned long' C native types. This consideration particularly applies to `long' and `unsigned long' C native types. These types should be defined as `long long' and `unsigned long long' in the actual code. Similarly a return type of `char' should be defined as `signed char' in the code on all platforms.
    • Description. Type an optional description of the argument.
  5. When you are happy with your routine definition, Click OK. The Save As dialog box appears.
  6. Select the folder in the repository tree where you want to store the routine and click OK.