Mapping Parameters and Variables Overview

By PenchalaRaju.Yanamala

In the Designer, use mapping parameters and variables to make mappings more
flexible. Mapping parameters and variables represent values in mappings and
mapplets. If you declare mapping parameters and variables in a mapping, you
can reuse a mapping by altering the parameter and variable values of the
mapping in the session. This can reduce the overhead of creating multiple
mappings when only certain attributes of a mapping need to be changed.

When you use a mapping parameter or variable in a mapping, first you declare the mapping
parameter or variable for use in each mapplet or mapping. Then, you define a value for the
mapping parameter or variable before you run the session.

Use mapping parameters and variables in a mapping to incrementally extract

data. Use mapping parameters or variables in the source filter of a Source
Qualifier transformation to determine the beginning timestamp and end
timestamp for incrementally extracting data.

For example, you can create a user-defined mapping variable $

$LastUpdateDateTime that saves the timestamp of the last row the Integration
Service read in the previous session. Use $$LastUpdateDateTime for the
beginning timestamp and the built-in variable $$$SessStartTime for the end
timestamp in the source filter. Use the following filter to incrementally extract data
based on the SALES.sales_datetime column in the source:

SALES.sales_datetime > TO_DATE (‘$$LastUpdateDateTime’) AND

SALES.sales_datetime < TO_DATE (‘$$$SessStartTime’)
Mapping Parameters

A mapping parameter represents a constant value that you can define before
running a session. A mapping parameter retains the same value throughout the
entire session.

When you use a mapping parameter, you declare and use the parameter in a
mapping or mapplet. Then define the value of the parameter in a parameter file.
The Integration Service evaluates all references to the parameter to that value.

For example, you want to use the same session to extract transaction records for
each of the customers individually. Instead of creating a separate mapping for
each customer account, you can create a mapping parameter to represent a
single customer account. Then use the parameter in a source filter to extract only
data for that customer account. Before running the session, you enter the value
of the parameter in the parameter file.
To reuse the same mapping to extract records for other customer accounts, you
can enter a new value for the parameter in the parameter file and run the
session. Or, you can create a parameter file for each customer account and start
the session with a different parameter file each time using pmcmd. By using a
parameter file, you reduce the overhead of creating multiple mappings and
sessions to extract transaction records for different customer accounts. When you want to use the
same value for a mapping parameter each time you run the session, use the same parameter file
for each session run. When you want to change the value of a mapping parameter between
sessions you can perform one of the following tasks:

Update the parameter file between sessions.

Create a different parameter file and configure the session to use the new file.
Remove the parameter file from the session properties. The Integration Service
uses the parameter value in the pre-session variable assignment. If there is no
pre-session variable assignment, the Integration Service uses the configured
initial value of the parameter in the mapping.

Mapping Variables

Unlike a mapping parameter, a mapping variable represents a value that can

change through the session. The Integration Service saves the value of a
mapping variable to the repository at the end of each successful session run and
uses that value the next time you run the session.

When you use a mapping variable, you declare the variable in the mapping or
mapplet, and then use a variable function in the mapping to change the value of
the variable. At the beginning of a session, the Integration Service evaluates
references to a variable to determine the start value. At the end of a successful
session, the Integration Service saves the final value of the variable to the
repository. The next time you run the session, the Integration Service evaluates
references to the variable to the saved value. To override the saved value, define
the start value of the variable in a parameter file or assign a value in the pre-
session variable assignment in the session properties.

When you want to use the same value for a mapping parameter each time you run the session,
use the same parameter file for each session run. When you want to change the value of a
mapping parameter between sessions you can perform one of the following tasks:

Update the parameter file between sessions.

Create a different parameter file and configure the session to use the new file.
Remove the parameter file from the session properties. The Integration Service
uses the parameter value in the pre-session variable assignment. If there is no
pre-session variable assignment, the Integration Service uses the configured
initial value of the parameter in the mapping.

Mapping Variables
Unlike a mapping parameter, a mapping variable represents a value that can
change through the session. The Integration Service saves the value of a
mapping variable to the repository at the end of each successful session run and
uses that value the next time you run the session.

When you use a mapping variable, you declare the variable in the mapping or
mapplet, and then use a variable function in the mapping to change the value of
the variable. At the beginning of a session, the Integration Service evaluates
references to a variable to determine the start value. At the end of a successful
session, the Integration Service saves the final value of the variable to the
repository. The next time you run the session, the Integration Service evaluates
references to the variable to the saved value. To override the saved value, define
the start value of the variable in a parameter file or assign a value in the pre-
session variable assignment in the session properties.

Use mapping variables to perform incremental reads of a source. For example,

the customer accounts in the mapping parameter example above are numbered
from 001 to 065, incremented by one. Instead of creating a mapping parameter,
you can create a mapping variable with an initial value of 001. In the mapping,
use a variable function to increase the variable value by one. The first time the
Integration Service runs the session, it extracts the records for customer account
001. At the end of the session, it increments the variable by one and saves that
value to the repository. The next time the Integration Service runs the session, it
extracts the data for the next customer account, 002. It also increments the
variable value so the next session extracts and looks up data for customer
account 003.

Parameters and Variables

You can use parameters and variables in the SQL query, user-defined join,
source filter, and pre- and post-session SQL commands of a Source Qualifier
transformation. Use any parameter or variable type that you can define in the
parameter file. You can enter a parameter or variable within the SQL statement,
or you can use a parameter or variable as the SQL query. For example, you can
use a session parameter, $ParamMyQuery, as the SQL query, and set
$ParamMyQuery to the SQL statement in a parameter file.

The Integration Service first generates an SQL query and expands each
parameter or variable. It replaces each mapping parameter, mapping variable,
and workflow variable with its start value. Then it runs the query on the source
database.

When you use a string mapping parameter or variable in the Source Qualifier
transformation, use a string identifier appropriate to the source system. Most
databases use a single quotation mark as a string identifier. For example, to use
the string parameter $$IPAddress in a source filter for a Microsoft SQL Server
database table, enclose the parameter in single quotes as follows: ‘$$IPAddress.’

When you use a datetime mapping parameter or variable, or when you use the
built-in variable $$$SessStartTime, change the date format to the format used in
the source. The Integration Service passes datetime values to source systems as
strings in the SQL query.

Tip: To ensure the format of a datetime parameter or variable matches that used
by the source, validate the SQL query

When you use a string mapping parameter or variable in the Source Qualifier
transformation, use a string identifier appropriate to the source system. Most
databases use a single quotation mark as a string identifier. For example, to use
the string parameter $$IPAddress in a source filter for a Microsoft SQL Server
database table, enclose the parameter in single quotes as follows: ‘$$IPAddress.’

When you use a datetime mapping parameter or variable, or when you use the
built-in variable $$$SessStartTime, change the date format to the format used in
the source. The Integration Service passes datetime values to source systems as
strings in the SQL query.

Tip: To ensure the format of a datetime parameter or variable matches that used
by the source, validate the SQL query.
Using Mapping Parameters and Variables

You can create mapping parameters and variables in the Mapping Designer or Mapplet Designer. Once
created, mapping parameters and variables appear on the Variables tab of the Expression Editor. Use
them in any expression in the mapplet or mapping. The Designer validates mapping parameters and
variables in the Expression Editor of mapplets and mappings.

Use mapping parameters and variables in a source qualifier in a mapplet or

mapping. When you use mapping parameters and variables in a Source Qualifier
transformation, the Designer expands them before passing the query to the
source database for validation. This allows the source database to validate the
query.

When you create a reusable transformation in the Transformation Developer, use

any mapping parameter or variable. Since a reusable transformation is not
contained within any mapplet or mapping, the Designer validates the usage of
any mapping parameter or variable in the expressions of reusable
transformation. When you use the reusable transformation in a mapplet or
mapping, the Designer validates the expression again. If the parameter or
variable is not defined in the mapplet or mapping, or if it is used incorrectly in the
reusable transformation, the Designer logs an error when you validate the
mapplet or mapping.

When the Designer validates a mapping variable in a reusable transformation, it

treats the variable as an Integer datatype.

You cannot use mapping parameters and variables interchangeably between a

mapplet and a mapping. Mapping parameters and variables declared for a
mapping cannot be used within a mapplet. Similarly, you cannot use a mapping
parameter or variable declared for a mapplet in a mapping.