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.
About this task
To create a new parallel routine:
Procedure
- Do one of:
- Choose from the Designer menu. The
New dialog box appears.
- Open the Routine folder and select the
Parallel Routine icon.
- Click OK. The Parallel
Routine dialog box appears, with the General page
on top.
Or:
- Select a folder in the repository tree.
- Choose from the pop-up
menu. The Parallel Routine dialog box appears, with the General page on top.
- 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.
- 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.
- 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.
- When you are happy with your routine definition,
Click OK. The Save As dialog
box appears.
- Select the folder in the repository tree
where you want to store the routine and click OK.