Working with Session Parameters

By PenchalaRaju.Yanamala

Session parameters represent values that can change between session runs,
such as database connections or source and target files.

Session parameters are either user-defined or built-in. Use user-defined session

parameters in session or workflow properties and define the values in a
parameter file. When you run a session, the Integration Service matches
parameters in the parameter file with the parameters in the session. It uses the
value in the parameter file for the session property value. In the parameter file,
folder and session names are case sensitive.

For example, you can write session logs to a log file. In the session properties,
use $PMSessionLogFile as the session log file name, and set
$PMSessionLogFile to TestRun.txt in the parameter file. When you run the
session, the Integration Service creates a session log named TestRun.txt.

User-defined session parameters do not have default values, so you must define
them in a parameter file. If the Integration Service cannot find a value for a user-
defined session parameter, it fails the session, takes an empty string as the
default value, or fails to expand the parameter at run time.

You can run a session with different parameter files when you use pmcmd to
start a session. The parameter file you set with pmcmd overrides the parameter
file in the session or workflow properties.

Use built-in session parameters to get run-time information such as folder name,
service names, or session run statistics. You can use built-in session parameters
in post-session shell commands, SQL commands, and email messages. You can
also use them in input fields in the Designer and Workflow Manager that accept
session parameters. The Integration Service sets the values of built-in session
parameters. You cannot define built-in session parameter values in the
parameter file. The Integration Service expands these parameters when the
session runs.

Table 7-3 describe the user-defined session parameters:

Table 7-3. User-Defined Session Parameters

Parameter Naming Convention Description
Type
Session Log $PMSessionLogFile Defines the name of the session log
File between session runs.
Number of $DynamicPartitionCount Defines the number of partitions for a
Partitions session.
Source File* $InputFileName Defines a source file name.
Lookup File* $LookupFileName Defines a lookup file name.
Target File* $OutputFileNames Defines a target file name.
Reject File* $BadFileName Defines a reject file name.
Database $DBConnectionName Defines a relational database connection
Connection* for a source, target, lookup, or stored
procedure.
External $LoaderConnectionName Defines external loader connections.
Loader
Connection*
FTP $FTPConnectionName Defines FTP connections.
Connection*
Queue $QueueConnectionName Defines database connections for
Connection* message queues.
Source or $AppConnectionName Defines connections to source and
Target target applications.
Application
Connection*
General $ParamName Defines any other session property. For
Session example, you can use this parameter to
Parameter* define a table owner name, table name
prefix, FTP file or directory name, lookup
cache file name prefix, or email address.
You can use this parameter to define
source, lookup, target, and reject file
names, but not the session log file name
or database connections.

* Define the parameter name using the appropriate prefix, for example,
$InputFileMySource.

Table 7-4 describes the built-in session parameters:

Table 7-4. Built-in Session Parameters

Parameter Naming Convention Description
Type
Folder name $PMFolderName Returns the folder
name.
Integration $PMIntegrationServiceName Returns the
Service name Integration Service
name.
Mapping $PMMappingName Returns the
name mapping name.
Repository $PMRepositoryServiceName Returns the
Service name Repository Service
name.
Repository $PMRepositoryUserName Returns the
user name repository user
name.
Session $PMSessionName Returns the
name session name.
Session run $PMSessionRunMode Returns the
mode session run mode
(normal or
recovery).
Source $PMSourceQualifierName@numAffectedRows Returns the
number of number of rows the
affected Integration Service
rows* successfully read
from the named
Source Qualifier.
Source $PMSourceQualifierName@numAppliedRows Returns the
number of number of rows the
applied rows* Integration Service
successfully read
from the named
Source Qualifier.
Source $PMSourceQualifierName@numRejectedRows Returns the
number of number of rows the
rejected Integration Service
rows* dropped when
reading from the
named Source
Qualifier.
Source table $PMSourceName@TableName Returns the table
name* name for the
named source
instance.
Target $PMTargetName@numAffectedRows Returns the
number of number of rows
affected affected by the
rows* specified operation
for the named
target instance.
Target $PMTargetName@numAppliedRows Returns the
number of number of rows the
applied rows* Integration Service
successfully
applied to the
named target
instance.
Target $PMTargetName@numRejectedRows Returns the
number of number of rows the
rejected Integration Service
rows* rejected when
writing to the
named target
instance.
Target table $PMTargetName@TableName Returns the table
name* name for the
named target
instance.
Workflow $PMWorkflowName Returns the
name workflow name.
Workflow run $PMWorkflowRunId Returns the
ID workflow run ID.
Workflow run $PMWorkflowRunInstanceName Returns the
instance workflow run
name instance name.

* Define the parameter name using the appropriate prefix and suffix. For example,
for a source instance named “Customers,” the parameter for source table name is
$PMCustomers@TableName. If the Source Qualifier is named “SQ_Customers,”
the parameter for source number of affected rows is
$PMSQ_Customers@numAffectedRows.

Changing the Session Log Name

You can configure a session to write log events to a file. In the session
properties, the Session Log File Directory defaults to the service process
variable, $PMSessionLogDir. The Session Log File Name defaults to
$PMSessionLogFile.

In a parameter file, you set $PMSessionLogFile to TestRun.txt. In the

Administration Console, you defined $PMSessionLogDir as
\\server\infa_shared\SessLogs. When the Integration ServiceIntegration Service
runs the session, it creates a session log file named TestRun.txt in the
\\server\infa_shared\SessLogs directory.

Changing the Target File and Directory

Use a target file parameter in the session properties to change the target file and
directory for a session. You can enter a path that includes the directory and file
name in the Output Filename field. If you include the directory in the Output
Filename field you must clear the Output File Directory. The Integration Service
concatenates the Output File Directory and the Output Filename to determine the
target file location.

For example, a session uses a file parameter to read internal and external
weblogs. You want to write the results of the internal weblog session to one
location and the external weblog session to another location.

In the session properties, you name the target file $OutputFileName and clear
the Output File Directory field. In the parameter file, set $OutputFileName to
E:/internal_weblogs/November_int.txt to create a target file for the internal
weblog session. After the session completes, you change $OutputFileName to
F:/external_weblogs/November_ex.txt for the external weblog session.

You can create a different parameter file for each target and use pmcmd to start
a session with a specific parameter file. This parameter file overrides the
parameter file name in the session properties.

Changing Source Parameters in a File

You can define multiple parameters for a session property in a parameter file and
use one of the parameters in a session. You can change the parameter name in
the session properties and run the session again with a different parameter
value.
For example, you create a session parameter named $InputFile_Products in a
parameter file. You set the parameter value to “products.txt.” In the same
parameter file, you create another parameter called $InputFile_Items. You set
the parameter value to “items.txt.”

When you set the source file name to $InputFile_Products in the session
properties, the Integration Service reads products.txt. When you change the
source file name to $InputFile_Items, the Integration Service reads items.txt.

Changing Connection Parameters

Use connection parameters to rerun sessions with different sources, targets,

lookup tables, or stored procedures. You create a connection parameter in the
session properties of any session. You can reference any connection in a
parameter. Name all connection session parameters with the appropriate prefix,
followed by any alphanumeric and underscore character.

For example, you run a session that reads from two relational sources. You
access one source with a database connection named “Marketing” and the other
with a connection named “Sales.” In the session properties, you create a source
database connection parameter named $DBConnection_Source. In the
parameter file, you define $DBConnection_Source as Marketing and run the
session. Set $DBConnection_Source to Sales in the parameter file for the next
session run.

If you use a connection parameter to override a connection for a source or target, you can
override the connection attributes in the parameter file. You can override connection
attributes when you use a non-relational connection parameter for a source or target
instance. When you define the connection in the parameter file, the Integration Service
searches for specific, user-defined session parameters that define the connection
attributes. For example, you create an FTP connection parameter called
$FTPConnectionMyFTPConn and define it in the parameter file. The Integration Service
searches the parameter file for the following parameters:

$Param_FTPConnectionMyFTPConn_Remote_Filename
$Param_FTPConnectionMyFTPConn_Is_Staged
$Param_FTPConnectionMyFTPConn_Is_Transfer_Mode_ASCII

If you do not define a value for any of these parameters, the Integration Service
uses the value defined in the connection object.

The connection attributes you can override are listed in the following template
file:

<PowerCenter Installation Directory>/server/bin/ConnectionParam.prm

Related Topics: 
Overriding Connection Attributes in the Parameter File

Getting Run-Time Information

Use built-in session parameters to get run-time information such as folder name,
Integration Service name, and source and target table name. You can use built-in
session parameters in post-session shell commands, SQL commands, and email
messages. You can also use them in input fields in the Designer and Workflow
Manager that accept session parameters.

For example, you want to send a post-session email after session

“s_UpdateCustInfo” completes that includes session run statistics for Source
Qualifier “SQ_Customers” and target “T_CustInfo.” Enter the following text in the
body of the email message:

Statistics for session $PMSessionName

Integration service: $PMIntegrationServiceName

Source number of affected rows: $PMSQ_Customers@numAffectedRows

Source number of dropped rows: $PMSQ_Customers@numRejectedRows

Target number of affected rows: $PMT_CustInfo@numAffectedRows

Target number of applied rows: $PMT_CustInfo@numAppliedRows

Target number of rejected rows: $PMT_CustInfo@numRejectedRows

You can also use email variables to get the session name, Integration Service
name, number of rows loaded, and number of rows rejected.

Related Topics: 
Working with Post-Session Email

Rules and Guidelines

Session file parameters and database connection parameters provide the

flexibility to run sessions against different files and databases.

Use the following rules and guidelines when you create file parameters:

When you define the parameter file as a resource for a node, verify the
Integration Service runs the session on a node that can access the parameter
file. Define the resource for the node, configure the Integration Service to check
resources, and edit the session to require the resource.
When you create a file parameter, use alphanumeric and underscore
characters. For example, to name a source file parameter, use $InputFileName,
such as $InputFile_Data.
All session file parameters of a particular type must have distinct names. For
example, if you create two source file parameters, you might name them
$SourceFileAccts and $SourceFilePrices.
When you define the parameter in the file, you can reference any directory local
to the Integration Service.
Use a parameter to define the location of a file. Clear the entry in the session
properties that define the file location. Enter the full path of the file in the
parameter file.
You can change the parameter value in the parameter file between session
runs, or you can create multiple parameter files. If you use multiple parameter
 files, use the pmcmd Startworkflow command with the -paramfile or
-localparamfile options to specify which parameter file to use.

Use the following rules and guidelines when you create database connection parameters:

You can change connections for relational sources, targets, lookups, and stored
procedures.
When you define the parameter, you can reference any database connection in
the repository.
Use the same $DBConnection parameter for more than one connection in a
session.

Mapping Parameters and Variables in Sessions

Use mapping parameters in the session properties to alter certain mapping

attributes. For example, use a mapping parameter in a transformation override to
override a filter or user-defined join in a Source Qualifier transformation.

If you use mapping variables in a session, you can clear any of the variable
values saved in the repository by editing the session. When you clear the
variable values, the Integration Service uses the values in the parameter file the
next time you run a session. If the session does not use a parameter file, the
Integration Service uses the values assigned in the pre-session variable
assignment. If there are no assigned values, the Integration Service uses the
initial values defined in the mapping.

To view or delete values for mapping variables saved in the repository:

In the Navigator window of the Workflow Manager, right-click the Session task
1.and select View Persistent Values.
You can see the variable name and value.
2.Click Delete Values to delete existing variable values.
3.Click OK.

Assigning Parameter and Variable Values in a Session

You can update the values of certain parameters and variables before or after a
non-reusable session runs. This allows you to pass information from one session
to another within the same workflow or worklet. For example, you have a
workflow that contains two sessions that need to increment the same counter.
You can increment the counter in the first session, pass the updated counter
value to the second session, and increment the counter again in the second
session. Or, you have a worklet that contains sessions that access the same web
site. You can configure the first session to get a session ID from the web site and
then pass the session ID value to subsequent sessions.

You can also pass information from a session to a worklet or from a worklet to a
session as long as the session and worklet are in the same workflow or parent
worklet. For more information about passing information between worklets, see
Assigning Variable Values in a Worklet.

Note: You cannot assign parameters and variables in reusable sessions.

The types of parameters and variables you can update depend on whether you assign
them before or after a session runs. You can update the following types of parameters and
variables before or after a session runs:

Pre-session variable assignment. You can update mapping parameters,

mapping variables, and session parameters before a session runs. You can
assign these parameters and variables the values of workflow or worklet
variables in the parent workflow or worklet. Therefore, if a session is in a worklet
within a workflow, you can assign values from the worklet variables, but not the
workflow variables.
You cannot update mapplet variables in the pre-session variable assignment.
Post-session on success variable assignment. You can update workflow or
worklet variables in the parent workflow or worklet after the session completes
successfully. You can assign these variables the values of mapping parameters
and variables.
Post-session on failure variable assignment. You can update workflow or
worklet variables in the parent workflow or worklet when the session fails. You
can assign these variables the values of mapping parameters and variables.

You assign parameters and variables on the Components tab of the session
properties.

Passing Parameter and Variable Values between Sessions

You can assign parameter and variable values in a session to pass values from
one session to any subsequent session in the same workflow or worklet. For
example, a workflow contains two sessions s_NewCustomers and
s_MergeCustomers. Session s_MergeCustomers needs to use the value of a
mapping variable updated in s_NewCustomers.
 Configure the workflow to use a user-defined workflow variable, for example, $
3.$PassCountValue.
Configure session s_NewCustomers to assign the value of mapping variable $
$Count1 to workflow variable $$PassCountValue after the session completes
4.successfully.
Configure session s_MergeCustomers to assign the value of workflow variable
5.$$PassCountValue to mapping variable $$Count2 before the session starts.
Related Topics: 
User-Defined Workflow Variables

Configuring Parameter and Variable Assignments

Assign parameters and variables on the Components tab of the session properties. Assign
values to the following types of parameters and variables before or after a session runs:

Pre-session variable assignment. Assign values to mapping parameters,

mapping variables, and session parameters. You update these parameters and
variables with the values of parent workflow or worklet variables.
Post-session variable assignment. Assign values to workflow and worklet
variables. You update these variables with the values of mapping parameters or
variables.

Mapping parameters and variables have different datatypes than workflow and
worklet variables. When you assign parameter and variable values in a session,
the Integration Service converts the datatypes as shown in Table 7-5 and Table
7-6.

Table 7-5 describes datatype conversion when you assign workflow or worklet
variable values to mapping parameters or mapping variables:

Table 7-5. Datatype Conversion for Pre-Session Variable Assignment

Workflow/Worklet Variable Datatype Mapping Parameter/Variable Datatype
Date/Time Date/Time
Double Double
Integer Integer
NString NString

Table 7-6 describes datatype conversion when you assign mapping parameter or
variable values to workflow or worklet variables:

Table 7-6. Datatype Conversion for Post-Session Variable Assignment

Mapping Parameter/Variable Datatype Workflow/Worklet Variable Datatype
Date/Time Date/Time
Decimal NString*
Double Double
Integer Integer
NString NString
NText NString
Real Double
Small integer Integer
String NString
Text NString

* There is no workflow or worklet variable datatype for the Decimal datatype. The
Integration Service converts Decimal values in mapping parameters and variables
to NString values in workflow and worklet variables.

To assign parameters and variables in a session:

1.Edit the session for which you want to assign parameters and variables.
2.Click the Components tab.
Select the variable assignment
3. type:
Pre-session variable assignment. Assign values to mapping
parameters, mapping variables, and session parameters before a
session runs.
Post-session on success variable assignment. Assign values to parent
workflow or worklet variables after a session completes successfully.
Post-session on failure variable assignment. Assign values to parent
workflow or worklet variables after a session fails.
Click the Open button in the variable assignment field. The Pre- or Post-
4.Session Variable Assignment dialog box appears.
In the Pre- or Post-Session Variable Assignment dialog box, click the add
5.button to add a variable assignment row.
Click the open button in the Mapping Variables/Parameters and Parent
Workflow/Worklet Variables fields to select the parameters and variables
whose values you want to read or assign. To assign values to a session
parameter, enter the parameter name in the Mapping Variables/Parameters
6.field. The Workflow Manager does not validate parameter names.
The Workflow Manager assigns values from the right side of the assignment statement to
parameters and variables on the left side of the statement. So, if the variable assignment
statement is “$$Counter_MapVar=$$Counter_WFVar,” the Workflow Manager assigns
the value of $$Counter_WFVar to $$Counter_MapVar.
Repeat steps 5 to 6 to add more variable assignment statements. To delete a
variable assignment statement, click one of the fields in the assignment
7.statement, and click the delete button.
8.Click OK.