24222825 custom transformation overview

Upload: natalinunez

Post on 03-Jun-2018

217 views

Category:

Documents


0 download

TRANSCRIPT

  • 8/12/2019 24222825 Custom Transformation Overview

    1/77

    Custom Transformation Overview

    Transformation type:Active/PassiveConnected

    Multigroup External Procedure transformations operate in conjunction with

    procedures you create outside of the Designer interface to extend PowerCenterfunctionality. ou can create a Multigroup External Procedure transformation and!ind it to a procedure that you develop using the functions descri!ed in Custom"ransformation #unctions.

    $se the Multigroup External Procedure transformation to create transformationapplications% such as sorting and aggregation% which re&uire all input rows to !eprocessed !efore outputting any output rows. "o support this process% the inputand output functions occur separately in Multigroup External Proceduretransformations compared to External Procedure transformations.

    "he 'ntegration (ervice passes the input data to the procedure using an inputfunction. "he output function is a separate function that you must enter in theprocedure code to pass output data to the 'ntegration (ervice. 'n contrast% in theExternal Procedure transformation% an external procedure function does !othinput and output% and its parameters consist of all the ports of the transformation.

    ou can also use the Multigroup External Procedure transformation to create atransformation that re&uires multiple input groups% multiple output groups% or!oth. A group is the representation of a row of data entering or leaving atransformation. #or example% you might create a Multigroup External Proceduretransformation with one input group and multiple output groups that parses )M*data. +r% you can create a Multigroup External Procedure transformation with twoinput groups and one output group that merges two streams of input data intoone stream of output data.

    Working with Transformations Built On the Custom Transformation

    ou can !uild transformations using the Custom transformation. (ome of thePowerCenter transformations are !uilt using the Custom transformation. ,ulesthat apply to Custom transformations% such as !loc-ing rules% also apply totransformations !uilt using Custom transformations. #or example% when youconnect a Custom transformation in a mapping% you must verify that the data canflow from all sources in a target load order group to the targets without the'ntegration (ervice !loc-ing all sources. (imilarly% you must also verify this fortransformations !uilt using a Custom transformation.

    "he following transformations that ship with 'nformatica products are !uilt usingthe Custom transformation

    ""P transformation with PowerCenter

  • 8/12/2019 24222825 Custom Transformation Overview

    2/77

    0ava transformation with PowerCenter(1* transformation with PowerCenter$nion transformation with PowerCenter$nstructured Data transformation with PowerCenter)M* Parser transformation with PowerCenter)M* 2enerator transformation with PowerCenter(AP/A*E3'Doc3'nterpreter transformation with PowerExchange for (AP4et5eaver my(AP +ption

    (AP/A*E3'Doc3Prepare transformation with PowerExchange for (AP4et5eaver my(AP +ption6AP'/,#C transformation with PowerExchange for (AP 4et5eaver my(AP+ption5e! (ervice Consumer transformation with PowerExchange for 5e! (ervices

    Code Page Compatibility

    5hen the 'ntegration (ervice runs in A(C'' mode% it passes data to theMultigroup External Procedure transformation procedure in A(C''. 5hen the'ntegration (ervice runs in $nicode mode% it passes data to the procedure in

    $C(78.

    $se the '4#A3C"Change(tringMode9: and '4#A3C"(etDataCodePage'D9:functions in the Multigroup External Procedure transformation procedure code tore&uest the data in a different format or in a different code page.

    "he functions you can use depend on the data movement mode of the'ntegration (ervice

    ASC mode!$se the '4#A3C"Change(tringMode9: function to re&uest thedata in $C(78. 5hen you use this function% the procedure must pass only A(C''

    characters in $C(78 format to the 'ntegration (ervice. ou cannot use the'4#A3C"(etDataCodePage'D9: function to change the code page when the'ntegration (ervice runs in A(C'' mode."ni#ode mode!$se the '4#A3C"Change(tringMode9: function to re&uest thedata in M6C( 9multi7!yte character set:. 5hen the procedure re&uests the datain M6C(% the 'ntegration (ervice passes data in the 'ntegration (ervice codepage. $se the '4#A3C"(etDataCodePage'D9: function to re&uest the data in adifferent code page from the 'ntegration (ervice code page. "he code page youspecify in the '4#A3C"(etDataCodePage'D9: function must !e two7waycompati!le with the 'ntegration (ervice code page.

    $ote: ou can also use the '4#A3C",e!ind'nputData"ype9: function to changethe format for a specific port in the Multigroup External Procedure transformation.

    %istributing Custom Transformation Pro#edures

    ou can copy a Multigroup External Procedure transformation from onerepository to another. 5hen you copy a Multigroup External Proceduretransformation !etween repositories% you must verify that the 'ntegration (ervice

  • 8/12/2019 24222825 Custom Transformation Overview

    3/77

    machine the target repository uses contains the Multigroup External Proceduretransformation procedure.

    Creating Custom Transformations

    ou can create reusa!le Multigroup External Procedure transformations in the"ransformation Developer% and add instances of the transformation to mappings.ou can create non7reusa!le Multigroup External Procedure transformations in

    the Mapping Designer or Mapplet Designer.

    Each Multigroup External Procedure transformation specifies a module and aprocedure name. ou can create a Multigroup External Procedure transformation!ased on an existing shared li!rary or D** containing the procedure% or you cancreate a Multigroup External Procedure transformation as the !asis for creatingthe procedure. 5hen you create a Multigroup External Procedure transformationto use with an existing shared li!rary or D**% ma-e sure you define the correctmodule and procedure name.

    5hen you create a Multigroup External Procedure transformation as the !asis for

    creating the procedure% select the transformation and generate the code. "heDesigner uses the transformation properties when it generates the procedurecode. 't generates code in a single directory for all transformations sharing acommon module name.

    "he Designer generates the following files

    m&'module&name(!#!Defines the module. "his file includes an initiali;ationfunction% m3

  • 8/12/2019 24222825 Custom Transformation Overview

    4/77

    include an )M* writer procedure and an )M* parser procedure in the samemodule.ou can !ind one shared li!rary or D** to multiple Multigroup ExternalProcedure transformation instances if you write the procedure code to handlemultiple Multigroup External Procedure transformation instances.5hen you write the procedure code% you must ma-e sure it does not violate!asic mapping rules."he Multigroup External Procedure transformation sends and receives high

    precision decimals as high precision decimals.$se multi7threaded code in Multigroup External Procedure transformationprocedures.

    Custom Transformation Components

    5hen you configure a Multigroup External Procedure transformation% you definethe following components

    Transformation tab!ou can rename the transformation and add a descriptionon the "ransformation ta!.

    Ports tab!ou can add and edit ports and groups to a Multigroup ExternalProcedure transformation. ou can also define the input ports an output portdepends on. #or more information% see 5or-ing with 2roups and Ports.Port Attribute %efinitions tab!ou can create user7defined port attri!utes forMultigroup External Procedure transformation ports. #or more information a!outcreating and editing port attri!utes% see 5or-ing with Port Attri!utes.Properties tab!ou can define transformation properties such as module andfunction identifiers% transaction properties% and the runtime location. #or moreinformation a!out defining transformation properties% see Custom"ransformation Properties.nitiali/ation Properties tab!ou can define properties that the procedure uses

    at runtime% such as during initiali;ation. #or more information% see 5or-ing withProcedure Properties.0etadata 1)tensions tab!ou can create metadata extensions to defineproperties that the procedure uses at runtime% such as during initiali;ation. #ormore information% see5or-ing with Procedure Properties.

    Working with .roups and Ports

    A Multigroup External Procedure transformation has !oth input and outputgroups. 't also can have input ports% output ports% and input/output ports. oucreate and edit groups and ports on the Ports ta! of the Multigroup External

    Procedure transformation. ou can also define the relationship !etween inputand output ports on the Ports ta!.

  • 8/12/2019 24222825 Custom Transformation Overview

    5/77

    Creating .roups and Ports

    ou can create multiple input groups and multiple output groups in a MultigroupExternal Procedure transformation. ou must create at least one input group andone output group. "o create an input group% clic- the Create 'nput 2roup icon. "ocreate an output group% clic- the Create +utput 2roup icon. ou can change theexisting group names !y typing in the group header. 5hen you create a passiveCustom transformation% you can only create one input group and one outputgroup.

    5hen you create a port% the Designer adds it !elow the currently selected row orgroup. A port can !elong to the input group and the output group that appearsimmediately a!ove it. An input/output port that appears !elow the input group it isalso part of the output group. An input/output port that appears !elow the outputgroup it is also part of the input group.

    2roups that share ports are called a coupled group. Adjacent groups of oppositetype can share ports. +ne group can !e part of more than one coupled group.#or example% in #igure @7% 'nput2roup and +utput2roup is a coupled groupthat shares +,DE,3'D.

    'f the transformation has a Port Attri!ute Definitions ta!% you can edit theattri!utes for each port.

  • 8/12/2019 24222825 Custom Transformation Overview

    6/77

    1diting .roups and Ports

    $se the following rules and guidelines when you edit ports and groups in aMultigroup External Procedure transformation

    ou can change group names !y typing in the group header.ou can only enter A(C'' characters for port and group names.+nce you create a group% you cannot change the group type. 'f you need to

    change the group type% delete the group and add a new group.5hen you delete a group% the Designer deletes all ports of the same type in thatgroup. owever% all input/output ports remain in the transformation% !elong tothe group a!ove them% and change to input ports or output ports% depending onthe type of group you delete. #or example% an output group contains outputports and input/output ports. ou delete the output group. "he Designer deletesthe output ports. 't changes the input/output ports to input ports. "hose inputports !elong to the input group with the header directly a!ove them."o move a group up or down% select the group header and clic- the Move Port$p or Move Port Down !utton. "he ports a!ove and !elow the group headerremain the same% !ut the groups to which they !elong might change.

    "o create an input/output port% the transformation must have an input group andan output group.

    %efining Port -elationships

    6y default% an output port in a Multigroup External Procedure transformationdepends on all input ports. owever% you can define the relationship !etweeninput and output ports in a Multigroup External Procedure transformation. 5henyou do this% you can view lin- paths in a mapping containing a MultigroupExternal Procedure transformation and you can see which input ports an outputport depends on. ou can also view source column dependencies for target ports

    in a mapping containing a Multigroup External Procedure transformation.

    "o define the relationship !etween ports in a Multigroup External Proceduretransformation% create a port dependency. A port dependency is the relationship!etween an output or input/output port and one or more input or input/outputports. 5hen you create a port dependency% !ase it on the procedure logic in thecode.

    "o create a port dependency% clic- Custom "ransformation on the Ports ta! andchoose Port Dependencies.

  • 8/12/2019 24222825 Custom Transformation Overview

    7/77

    #or example% create a procedure that parses )M* data. ou create a MultigroupExternal Procedure transformation with one input group containing one input portand multiple output groups containing multiple output ports. According to theprocedure logic% all output ports depend on the input port. ou can define thisrelationship in the Multigroup External Procedure transformation !y creating aport dependency for each output port. Define each port dependency so that theoutput port depends on the one input port.

    "o create a port dependency

    2!+n the Ports ta!% clic- Custom "ransformation and choose Port Dependencies.

    3!'n the +utput Port Dependencies dialog !ox% select an output or input/outputport in the +utput Port field.

    4!'n the 'nput Ports pane% select an input or input/output port on which the outputport or input/output port depends.

    ,!Clic- Add.

    5!,epeat steps @to ?to include more input or input/output ports in the portdependency.

    +!"o create another port dependency% repeat steps 8to B.6!Clic- +.

  • 8/12/2019 24222825 Custom Transformation Overview

    8/77

    5hen you create a port attri!ute% define the following properties

    $ame!"he name of the port attri!ute.%atatype!"he datatype of the port attri!ute value. ou can choose 6oolean%4umeric% or (tring.7alue!"he default value of the port attri!ute. "his property is optional. 5henyou enter a value here% the value applies to all ports in the Multigroup ExternalProcedure transformation. ou can override the port attri!ute value for each porton the Ports ta!.

    ou define port attri!utes for each Multigroup External Procedure transformation.ou cannot copy a port attri!ute from one Multigroup External Proceduretransformation to another.

    1diting Port Attribute 7alues

    After you create port attri!utes% you can edit the port attri!ute values for eachport in the transformation. "o edit the port attri!ute values% clic- Custom"ransformation on the Ports ta! and choose Edit Port Attri!ute.

    #igure @7?shows where you edit port attri!ute values

  • 8/12/2019 24222825 Custom Transformation Overview

    9/77

    ou can change the port attri!ute value for a particular port !y clic-ing the +pen!utton. "his opens the Edit Port Attri!ute Default alue dialog !ox. +r% you canenter a new value !y typing directly in the alue column.

    ou can filter the ports listed in the Edit Port *evel Attri!utes dialog !ox !ychoosing a group from the (elect 2roup field

    Custom Transformation Properties

    Properties for the Multigroup External Procedure transformation apply to !oth theprocedure and the transformation. Configure the Multigroup External Proceduretransformation properties on the Properties ta! of the Custom transformation.

    "a!le @7descri!es the Multigroup External Procedure transformation properties

    "a!le @7. Custom "ransformation Properties

    +ption Description*anguage *anguage used for the procedure code. ou define the

    language when you create the Multigroup External Proceduretransformation. 'f you need to change the language% create anew Multigroup External Procedure transformation.

    Module 'dentifier Module name. Applies to Multigroup External Proceduretransformation procedures developed using C or C.

  • 8/12/2019 24222825 Custom Transformation Overview

    10/77

    Enter only A(C'' characters in this field. ou cannot entermulti!yte characters."his property is the !ase name of the D** or the shared li!rarythat contains the procedure. "he Designer uses this name tocreate the C file when you generate the procedure code.

    #unction 'dentifier 4ame of the procedure in the module. Applies to MultigroupExternal Procedure transformation procedures developedusing C.

    Enter only A(C'' characters in this field. ou cannot entermulti!yte characters."he Designer uses this name to create the C file where youenter the procedure code.

    Class 4ame Class name of the Multigroup External Proceduretransformation procedure. Applies to Multigroup ExternalProcedure transformation procedures developed using C or0ava.Enter only A(C'' characters in this field. ou cannot entermulti!yte characters.

    ,untime *ocation *ocation that contains the D** or shared li!rary. Default isFPMExtProcDir. Enter a path relative to the 'ntegration (ervicemachine that runs the session using the Multigroup ExternalProcedure transformation.'f you ma-e this property !lan-% the 'ntegration (ervice usesthe environment varia!le defined on the 'ntegration (ervicemachine to locate the D** or shared li!rary.ou must copy all D**s or shared li!raries to the runtimelocation or to the environment varia!le defined on the'ntegration (ervice machine. "he 'ntegration (ervice fails toload the procedure when it cannot locate the D**% sharedli!rary% or a referenced file.

    "racing *evel Amount of detail displayed in the session log for thistransformation. Default is 4ormal.

    's Partitiona!le 'ndicates if you can create multiple partitions in a pipeline thatuses this transformation

    7

    4o. "he transformation cannot !e partitioned. "hetransformation and other transformations in the same pipelineare limited to one partition.

    7

    *ocally. "he transformation can !e partitioned% !ut the'ntegration (ervice must run all partitions in the pipeline on thesame node. Choose *ocal when different partitions of the

    Custom transformation must share o!jects in memory.

    7

    Across 2rid. "he transformation can !e partitioned% and the'ntegration (ervice can distri!ute each partition to differentnodes.

    Default is 4o.

    'nputs Must 6loc- 'ndicates if the procedure associated with the transformationmust !e a!le to !loc- incoming data. Default is ena!led.

    's Active 'ndicates if this transformation is an active or passive

  • 8/12/2019 24222825 Custom Transformation Overview

    11/77

    transformation.ou cannot change this property after you create theMultigroup External Procedure transformation. 'f you need tochange this property% create a new Multigroup ExternalProcedure transformation and select the correct property value.

    $pdate (trategy"ransformation

    'ndicates if this transformation defines the update strategy foroutput rows. Default is disa!led. ou can ena!le this for activeMultigroup External Procedure transformations.

    "ransformation(cope

    'ndicates how the 'ntegration (ervice applies thetransformation logic to incoming data7,ow7"ransaction7All 'nput5hen the transformation is passive% this property is always,ow. 5hen the transformation is active% this property is All'nput !y default.

    2enerate"ransaction

    'ndicates if this transformation can generate transactions.5hen a Multigroup External Procedure transformationgenerates transactions% it generates transactions for all outputgroups.Default is disa!led. ou can only ena!le this for activeMultigroup External Procedure transformations.

    +utput is,epeata!le

    'ndicates if the order of the output data is consistent !etweensession runs.74ever. "he order of the output data is inconsistent !etweensession runs. "his is the default for active transformations.

    7

    6ased +n 'nput +rder. "he output order is consistent !etweensession runs when the input data order is consistent !etweensession runs. "his is the default for passive transformations.

    7

    Always. The order of the output data is consistent between sessionruns even if the order of the input data is inconsistent between

    session runs.

    ,e&uires (ingle"hread PerPartition

    'ndicates if the 'ntegration (ervice processes each partition atthe procedure with one thread. 5hen you ena!le this option%the procedure code can use thread7specific operations. Defaultis ena!led.

    +utput is

    Deterministic

    'ndicates whether the transformation generates consistent

    output data !etween session runs. Ena!le this property toperform recovery on sessions that use this transformation.

    Warning: 'f you configure a transformation as repeata!le and deterministic% it isyour responsi!ility to ensure that the data is repeata!le and deterministic. 'f youtry to recover a session with transformations that do not produce the same data!etween the session and the recovery% the recovery process can result incorrupted data.

  • 8/12/2019 24222825 Custom Transformation Overview

    12/77

    Setting the "pdate Strategy

    $se an active Multigroup External Procedure transformation to set the updatestrategy for a mapping at the following levels

    Within the pro#edure!ou can write the procedure code to set the updatestrategy for output rows. "he procedure can flag rows for insert% update% delete%or reject.

    Within the mapping!$se the Multigroup External Procedure transformation ina mapping to flag rows for insert% update% delete% or reject. (elect the $pdate(trategy "ransformation property for the Multigroup External Proceduretransformation.Within the session!Configure the session to treat the source rows as datadriven.

    'f you do not configure the Multigroup External Procedure transformation todefine the update strategy% or you do not configure the session as data driven%the 'ntegration (ervice does not use the procedure code to flag the output rows.'nstead% when the Multigroup External Procedure transformation is active% the

    'ntegration (ervice flags the output rows as insert. 5hen the Multigroup ExternalProcedure transformation is passive% the 'ntegration (ervice retains the row type.#or example% when a row flagged for update enters a passive MultigroupExternal Procedure transformation% the 'ntegration (ervice maintains the rowtype and outputs the row as update.

    Working with Thread8Spe#ifi# Pro#edure Code

    Multigroup External Procedure transformation procedures can include thread7specific operations. A thread7specific operation is code that performs an action!ased on the thread that is processing the procedure.

    ou can configure the Multigroup External Procedure transformation so the'ntegration (ervice uses one thread to process the Multigroup ExternalProcedure transformation for each partition using the ,e&uires (ingle "hread PerPartition property.

    5hen you configure a Custom transformation to process each partition with onethread% the 'ntegration (ervice calls the following functions with the same threadfor each partition

    p3

  • 8/12/2019 24222825 Custom Transformation Overview

    13/77

    partition. #or example% you might attach and detach threads to a 0ava irtualMachine.

    $ote: 5hen you configure a Multigroup External Procedure transformation toprocess each partition with one thread% the 5or-flow Manager adds partitionpoints depending on the mapping configuration.

    Working with Transa#tion Control

    ou can define transaction control for Multigroup External Proceduretransformations using the following transformation properties

    Transformation S#ope!Determines how the 'ntegration (ervice applies thetransformation logic to incoming data..enerate Transa#tion!'ndicates that the procedure generates transaction rowsand outputs them to the output groups.

    Transformation S#ope

    ou can configure how the 'ntegration (ervice applies the transformation logic toincoming data. ou can choose one of the following values

    -ow!Applies the transformation logic to one row of data at a time. Choose ,owwhen the results of the procedure depend on a single row of data. #or example%you might choose ,ow when a procedure parses a row containing an )M* file.Transa#tion!Applies the transformation logic to all rows in a transaction.Choose "ransaction when the results of the procedure depend on all rows in thesame transaction% !ut not on rows in other transactions. 5hen you choose"ransaction% you must connect all input groups to the same transaction controlpoint. #or example% you might choose "ransaction when the procedure performs

    aggregate calculations on the data in a single transaction.All nput!Applies the transformation logic to all incoming data. 5hen youchoose All 'nput% the 'ntegration (ervice drops transaction !oundaries. Choose

    All 'nput when the results of the procedure depend on all rows of data in thesource. #or example% you might choose All 'nput when the procedure performsaggregate calculations on all incoming data% or when it sorts all incoming data.

    .enerate Transa#tion

    ou can write the procedure code to output transactions% such as commit androll!ac- rows. 5hen the procedure outputs commit and roll!ac- rows% configure

    the Multigroup External Procedure transformation to generate transactions.(elect the 2enerate "ransaction transformation property. ou can ena!le thisproperty for active Custom transformations.

    5hen the procedure outputs a commit or roll!ac- row% it outputs or rolls !ac- therow for all output groups.

  • 8/12/2019 24222825 Custom Transformation Overview

    14/77

    5hen you configure the transformation to generate transactions% the 'ntegration(ervice treats the Multigroup External Procedure transformation li-e a"ransaction Control transformation. Most rules that apply to a "ransactionControl transformation in a mapping also apply to the Multigroup ExternalProcedure transformation. #or example% when you configure a MultigroupExternal Procedure transformation to generate transactions% you cannotconcatenate pipelines or pipeline !ranches containing the transformation.

    5hen you edit or create a session using a Multigroup External Proceduretransformation configured to generate transactions% configure it for user7definedcommit.

    Working with Transa#tion Boundaries

    "he 'ntegration (ervice handles transaction !oundaries entering and leavingMultigroup External Procedure transformations !ased on the mappingconfiguration and the Multigroup External Procedure transformation properties.

    "a!le @78descri!es how the 'ntegration (ervice handles transaction !oundaries

    at Multigroup External Procedure transformations

    "a!le @78. "ransaction 6oundary andling with Custom "ransformations

    "ransformation(cope

    2enerate "ransactionsEna!led

    2enerate "ransactions Disa!led

    ,ow 'ntegration (ervice dropsincoming transaction!oundaries and does not callthe data !oundary notificationfunction.

    't outputs transaction rowsaccording to the procedurelogic across all output groups.

    5hen the incoming data for allinput groups comes from thesame transaction control point% the'ntegration (ervice preservesincoming transaction !oundaries

    and outputs them across all outputgroups. owever% it does not callthe data !oundary notificationfunction.

    5hen the incoming data for theinput groups comes from differenttransaction control points% the'ntegration (ervice dropsincoming transaction !oundaries.'t does not call the data !oundary

    notification function. "he'ntegration (ervice outputs allrows in one open transaction.

    "ransaction 'ntegration (ervice preservesincoming transaction!oundaries and calls the data!oundary notification function.owever% it outputs

    'ntegration (ervice preservesincoming transaction !oundariesand calls the data !oundarynotification function.'t outputs the transaction rows

  • 8/12/2019 24222825 Custom Transformation Overview

    15/77

    transaction rows according tothe procedure logic across alloutput groups.

    across all output groups.

    All 'nput 'ntegration (ervice dropsincoming transaction!oundaries and does not callthe data !oundary notificationfunction. "he 'ntegration

    (ervice outputs transactionrows according to theprocedure logic across alloutput groups.

    'ntegration (ervice dropsincoming transaction !oundariesand does not call the data!oundary notification function. 'toutputs all rows in one open

    transaction

    Blo#king nput %ata

    6y default% the 'ntegration (ervice concurrently reads sources in a target loadorder group. owever% you can write the procedure code to !loc- input data onsome input groups. 6loc-ing is the suspension of the data flow into an inputgroup of a multiple input group transformation.

    "o use a Multigroup External Procedure transformation to !loc- input data% youmust write the procedure code to !loc- and un!loc- data. ou must also ena!le!loc-ing on the Properties ta! for the Multigroup External Proceduretransformation.

    Writing the Pro#edure Code to Blo#k %ata

    ou can write the procedure to !loc- and un!loc- incoming data. "o !loc-incoming data% use the '4#A3C"6loc-'nput#low9: function. "o un!loc- incomingdata% use the '4#A3C"$n!loc-'nput#low9: function.

    ou might want to !loc- input data if the procedure needs to alternate readingfrom input groups. 5ithout the !loc-ing functionality% you would need to write theprocedure code to !uffer incoming data. ou can !loc- input data instead of!uffering it which usually increases session performance.

    #or example% you need to create an procedure with two input groups. "heprocedure reads a row from the first input group and then reads a row from thesecond input group. 'f you use !loc-ing% you can write the procedure code to!loc- the flow of data from one input group while it processes the data from theother input group. 5hen you write the procedure code to !loc- data% you

    increase performance !ecause the procedure does not need to copy the sourcedata to a !uffer. owever% you could write the procedure to allocate a !uffer andcopy the data from one input group to the !uffer until it is ready to process thedata. Copying source data to a !uffer decreases performance.

    ,elated "opics6loc-ing #unctions.

  • 8/12/2019 24222825 Custom Transformation Overview

    16/77

    Configuring Custom Transformations as Blo#king Transformations

    5hen you create a Multigroup External Procedure transformation% the Designerena!les the 'nputs Must 6loc- transformation property !y default. "his propertyaffects data flow validation when you save or validate a mapping. 5hen youena!le this property% the Multigroup External Procedure transformation is a!loc-ing transformation. 5hen you clear this property% the Multigroup ExternalProcedure transformation is not a !loc-ing transformation.

    Configure the Multigroup External Procedure transformation as a !loc-ingtransformation when the procedure code must !e a!le to !loc- input data.

    ou can configure the Multigroup External Procedure transformation as a non7!loc-ing transformation when one of the following conditions is true

    "he procedure code does not include the !loc-ing functions."he procedure code includes two algorithms% one that uses !loc-ing and theother that copies the source data to a !uffer allocated !y the procedure insteadof !loc-ing data. "he code chec-s whether or not the 'ntegration (ervice allows

    the Multigroup External Procedure transformation to !loc- data. "he procedureuses the algorithm with the !loc-ing functions when it can !loc-% and uses theother algorithm when it cannot !loc-. ou might want to do this to create aMultigroup External Procedure transformation that you use in multiple mappingconfigurations.

    $ote: 5hen the procedure !loc-s data and you configure the MultigroupExternal Procedure transformation as a non7!loc-ing transformation% the'ntegration (ervice fails the session.

    7alidating 0appings with Custom Transformations

    5hen you include a Multigroup External Procedure transformation in a mapping%!oth the Designer and 'ntegration (ervice validate the mapping. "he Designervalidates the mapping you save or validate and the 'ntegration (ervice validatesthe mapping when you run the session.

    7alidating at %esign Time

    5hen you save or validate a mapping% the Designer performs data flowvalidation. 5hen the Designer does this% it verifies that the data can flow from allsources in a target load order group to the targets without !loc-ing

    transformations !loc-ing all sources. (ome mappings with !loc-ingtransformations are invalid.

    7alidating at -untime

    5hen you run a session% the 'ntegration (ervice validates the mapping againstthe procedure code at runtime. 5hen the 'ntegration (ervice does this% it trac-s

  • 8/12/2019 24222825 Custom Transformation Overview

    17/77

    whether or not it allows the Multigroup External Procedure transformations to!loc- data

    Configure the Custom transformation as a blo#king transformation!"he'ntegration (ervice always allows the Custom transformation to !loc- data.Configure the Custom transformation as a non8blo#king transformation!"he 'ntegration (ervice allows the Custom transformation to !loc- datadepending on the mapping configuration. 'f the 'ntegration (ervice can !loc-

    data at the Custom transformation without !loc-ing all sources in the target loadorder group simultaneously% it allows the Custom transformation to !loc- data.

    ou can write the procedure code to chec- whether or not the 'ntegration (erviceallows a Multigroup External Procedure transformation to !loc- data. $se the'4#A3C"3get'nternalProperty9: function to access the'4#A3C"3",A4(3MA36*+C3DA"A property 'D. "he 'ntegration (ervicereturns ",$E when the Multigroup External Procedure transformation can !loc-data% and it returns #A*(E when the Multigroup External Proceduretransformation cannot !loc- data.

    Working with Pro#edure Properties

    ou can define property name and value pairs in the Multigroup ExternalProcedure transformation that the procedure can use when the 'ntegration(ervice runs the procedure% such as during initiali;ation time. ou can createuser7defined properties on the following ta!s of the Multigroup ExternalProcedure transformation

    0etadata 1)tensions!ou can specify the property name% datatype% precision%and value. $se metadata extensions for passing information to the procedure.nitiali/ation Properties!ou can specify the property name and value.

    5hile you can define properties on !oth ta!s in the Multigroup ExternalProcedure transformation% the Metadata Extensions ta! lets you provide moredetail for the property. $se metadata extensions to pass properties to theprocedure.

    #or example% you create a Multigroup External Procedure transformationprocedure that sorts data after transforming it. ou could create a !ooleanmetadata extension named (ort3Ascending. 5hen you use the MultigroupExternal Procedure transformation in a mapping% you can choose "rue or #alsefor the metadata extension% depending on how you want the procedure to sort

    the data.

    5hen you define a property in the Multigroup External Procedure transformation%use the get all property names functions% such as'4#A3C"2etAllProperty4amesM9:% to access the names of all properties definedon the 'nitiali;ation Properties and Metadata Extensions ta!. $se the get externalproperty functions% such as '4#A3C"3getExternalPropertyM9:% to access theproperty name and value of a property 'D you specify.

  • 8/12/2019 24222825 Custom Transformation Overview

    18/77

    $ote: 5hen you define a metadata extension and an initiali;ation property withthe same name% the property functions only return information for the metadataextension.

    Creating Custom Transformation Pro#edures

    ou can create Custom transformation procedures that run on @87!it or >?7!it'ntegration (ervice machines. $se the following steps as a guideline when you

    create a Multigroup External Procedure transformation procedure

    .

    'n the "ransformation Developer% create a reusa!le Multigroup ExternalProcedure transformation. +r% in the Mapplet Designer or Mapping Designer%create a non7reusa!le Multigroup External Procedure transformation.

    8. 2enerate the template code for the procedure.5hen you generate the procedure code% the Designer uses the information fromthe Multigroup External Procedure transformation to create C source code filesand ma-efiles.@. Modify the C files to add the procedure logic.

    ?.

    $se a C/C compiler to compile and lin- the source code files into a D** or

    shared li!rary and copy it to the 'ntegration (ervice machine.B. Create a mapping with the Multigroup External Procedure transformation.>. ,un the session in a wor-flow.

    "his section includes an example to demonstrate this process. "he steps in thissection create a Multigroup External Procedure transformation that contains twoinput groups and one output group. "he Multigroup External Proceduretransformation procedure verifies that the Multigroup External Proceduretransformation uses two input groups and one output group. 't also verifies thatthe num!er of ports in all groups are e&ual and that the port datatypes are thesame for all groups. "he procedure ta-es rows of data from each input group and

    outputs all rows to the output group.

    Step 2! Create the Custom Transformation

    "o create a Multigroup External Procedure transformation

    2!'n the "ransformation Developer% clic- "ransformation = Create.

    3!'n the Create "ransformation dialog !ox% choose Multigroup ExternalProcedure transformation% enter a transformation name% and clic- Create.

    'n the $nion example% enter C"3'nf3$nion as the transformation name.

    4!

    'n the Active or Passive dialog !ox% create the transformation as a passive or

    active transformation% and clic- +.'n the $nion example% choose Active.,!Clic- Done to close the Create "ransformation dialog !ox.5!+pen the transformation and clic- the Ports ta!. Create groups and ports.ou can edit the groups and ports later% if necessary.'n the $nion example% create the groups and ports shown in #igure @7B

  • 8/12/2019 24222825 Custom Transformation Overview

    19/77

    6!Clic- the Metadata Extensions ta! to enter metadata extensions% such asproperties the procedure might need for initiali;ation.

    'n the $nion example% do not create metadata extensions.9!Clic- the Port Attri!ute Definitions ta! to create port attri!utes% if necessary.'n the $nion example% do not create port attri!utes.

    After you create the Multigroup External Procedure transformation that calls theprocedure% the next step is to generate the C files.

    Step 3! .enerate the C iles

    After you create a Multigroup External Procedure transformation% you generatethe source code files. "he Designer generates file names in lower case.

    "o generate the code for a Multigroup External Procedure transformationprocedure

    2!'n the "ransformation Developer% select the transformation and clic-"ransformation = 2enerate Code.

    3!(elect the procedure you just created. "he Designer lists the procedures as

  • 8/12/2019 24222825 Custom Transformation Overview

    20/77

    "he Designer creates a su!directory% ? 9>?7!it:% ma-efile.hp 9@87!it:% ma-efile.hp>?

    9>?7!it:% ma-efile.hpparisc>?% ma-efile.linux 9@87!it:% and ma-efile.sol 9@87!it:.

    Step 4! ill Out the Code with the Transformation ;ogi#

    ou must code the procedure C file. +ptionally% you can also code the module Cfile. 'n the $nion example% you fill out the procedure C file only. ou do not needto fill out the module C file.

    "o code the procedure C file

    2!+pen p3

  • 8/12/2019 24222825 Custom Transformation Overview

    21/77

    G server executa!le.

    G

    G for more information on these files%

    G see F9'4#A3+ME:/ExtProc/include/,eadme.txt

    GGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGG/

    /G

    G '4#+,MA"'CA I$4'+4 DEM+I developed using the AP' for custom

    G transformations.

    G #ile 4ame p3$nion.c

    G

    G An example of a custom transformation 9I$nionI: using PowerCenterJ.H

    G

    G "he purpose of the I$nionI transformation is to com!ine pipelines with the

    G same row definition into one pipeline 9i.e. union of multiple pipelines:.

    G K 4ote that it does not correspond to the mathematical definition of union

    G since it does not eliminate duplicate rows.L

    G

    G "his example union transformation allows 4 input pipelines 9 each

    G corresponding to an input group: to !e com!ined into one pipeline.

    G

    G "o use this transformation in a mapping% the following attri!utes must !e

    G true

    G a. "he transformation must have = 8 input groups and only one output group.

  • 8/12/2019 24222825 Custom Transformation Overview

    22/77

    G !. 'n the Properties ta! set the following properties

    G i. Module 'dentifier $nionDemo

    G ii. #unction 'dentifier $nion

    G iii. 'nputs May 6loc- $nchec-ed

    G iv. 's Active Chec-ed

    G v. $pdate (trategy "ransformation $nchec-ed G

    G vi. "ransformation (cope All

    G vii. 2enerate "ransaction $nchec-ed G

    G

    G G "his version of the union transformation does not provide code for

    G changing the update strategy or for generating transactions.

    G c. "he input groups and the output group must have the same num!er of ports

    G and the same datatypes. "his is verified in the initiali;ation of the

    G module and the session is failed if this is not true.

    G d. "he transformation can !e used in multiple num!er of times in a "arget

    G *oad +rder 2roup and can also !e contained within multiple partitions.

    G

    G/

    /GGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGG

    'ncludes

    GGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGG/

    include

  • 8/12/2019 24222825 Custom Transformation Overview

    23/77

    /GGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGG

    #orward Declarations

    GGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGG/

    '4#A3("A"$( validateProperties9const '4#A3C"3PA,"'"'+43A4D*EGpartition:

    /GGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGG

    #unctions

    GGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGG/

    /GGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGG

    #unction p3union3proc'nit

    Description 'nitiali;ation for the procedure. ,eturns '4#A3($CCE(( if

    procedure initiali;ation succeeds% else return '4#A3#A'*$,E.

    'nput procedure 7 the handle for the procedure

    +utput 4one

    ,emar-s "his function will get called once for the session at

    initiali;ation time. 't will !e called after the module'nit function.

    GGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGG/

    '4#A3("A"$( p3union3proc'nit9 '4#A3C"3P,+CED$,E3A4D*E procedure:

    Q

  • 8/12/2019 24222825 Custom Transformation Overview

    24/77

    const '4#A3C"3",A4(#+,MA"'+43A4D*EG transformation 4$**

    const '4#A3C"3PA,"'"'+43A4D*EG partition 4$**

    si;e3t n"ransformations H% nPartitions H% i H

    /G *og a message indicating !eginning of the procedure initiali;ation G/

    '4#A3C"*ogMessageM9 eE(*3*+2%

    Ounion3demo Procedure initiali;ation started ...O :

    '4#A3C"Change(tringMode9 procedure% eA(M3M6C( :

    /G 2et the transformation handles G/

    transformation '4#A3C"2etChildrenandles9 procedure%

    Rn"ransformations%

    ",A4(#+,MA"'+4"PE:

    /G #or each transformation verify that the Hth partition has the correct

    G properties. "his does not need to !e done for all partitions since rest

    G of the partitions have the same information G/

    for 9i H i < n"ransformations i:

    Q

    /G 2et the partition handle G/

    partition '4#A3C"2etChildrenandles9transformationKiL%

    RnPartitions% PA,"'"'+4"PE :

    if 9validateProperties9partition: S '4#A3($CCE((:

  • 8/12/2019 24222825 Custom Transformation Overview

    25/77

    Q

    '4#A3C"*ogMessageM9 eE(*3E,,+,%

    Ounion3demo #ailed to validate attri!utes of O

    Othe transformationO:

    return '4#A3#A'*$,E

    T

    T

    '4#A3C"*ogMessageM9 eE(*3*+2%

    Ounion3demo Procedure initiali;ation completed.O :

    return '4#A3($CCE((

    T

    /GGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGG

    #unction p3union3procDeinit

    Description Deinitiali;ation for the procedure. ,eturns '4#A3($CCE(( if

    procedure deinitiali;ation succeeds% else return '4#A3#A'*$,E.

    'nput procedure 7 the handle for the procedure

    +utput 4one

    ,emar-s "his function will get called once for the session at

    deinitiali;ation time. 't will !e called !efore the moduleDeinit

    function.

  • 8/12/2019 24222825 Custom Transformation Overview

    26/77

    GGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGG/

    '4#A3("A"$( p3union3procDeinit9 '4#A3C"3P,+CED$,E3A4D*Eprocedure%

    '4#A3("A"$( session(tatus :

    Q

    /G Do nothing ... G/

    return '4#A3($CCE((

    T

    /GGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGG

    #unction p3union3partition'nit

    Description 'nitiali;ation for the partition. ,eturns '4#A3($CCE(( if

    partition deinitiali;ation succeeds% else return '4#A3#A'*$,E.

    'nput partition 7 the handle for the partition

    +utput 4one

    ,emar-s "his function will get called once for each partition for each

    transformation in the session.

    GGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGG/

    '4#A3("A"$( p3union3partition'nit9 '4#A3C"3PA,"'"'+43A4D*E partition :

    Q

    /G Do nothing ... G/

  • 8/12/2019 24222825 Custom Transformation Overview

    27/77

    return '4#A3($CCE((

    T

    /GGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGG

    #unction p3union3partitionDeinit

    Description Deinitiali;ation for the partition. ,eturns '4#A3($CCE(( if

    partition deinitiali;ation succeeds% else return '4#A3#A'*$,E.

    'nput partition 7 the handle for the partition

    +utput 4one

    ,emar-s "his function will get called once for each partition for each

    transformation in the session.

    GGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGG/

    '4#A3("A"$( p3union3partitionDeinit9 '4#A3C"3PA,"'"'+43A4D*Epartition :

    Q

    /G Do nothing ... G/

    return '4#A3($CCE((

    T

    /GGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGG

    #unction p3union3input,ow4otification

  • 8/12/2019 24222825 Custom Transformation Overview

    28/77

    Description 4otification that a row needs to !e processed for an input

    group in a transformation for the given partition. ,eturns '4#A3,+5($CCE((

    if the input row was processed successfully% '4#A3,+5#A'*$,E if the input

    row was not processed successfully and '4#A3#A"A*E,,+, if the input row

    causes the session to fail.

    'nput partition 7 the handle for the partition for the given row

    group 7 the handle for the input group for the given row

    +utput 4one

    ,emar-s "his function is pro!a!ly where the meat of your code will go%

    as it is called for every row that gets sent into your transformation.

    GGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGG/

    '4#A3,+5("A"$(p3union3input,ow4otification9 '4#A3C"3PA,"'"'+43A4D*E partition%

    '4#A3C"3'4P$"2,+$P3A4D*E input2roup :

    Q

    const '4#A3C"3+$"P$"2,+$P3A4D*EG output2roups 4$**

    const '4#A3C"3'4P$"P+,"3A4D*EG input2roupPorts 4$**

    const '4#A3C"3+$"P$"P+,"3A4D*EG output2roupPorts 4$**

    si;e3t n4um'nputPorts H% n4um+utput2roups H%

    n4umPorts'n+utput2roup H% i H

    /G 2et the output group port handles G/

  • 8/12/2019 24222825 Custom Transformation Overview

    29/77

    output2roups '4#A3C"2etChildrenandles9partition%

    Rn4um+utput2roups%

    +$"P$"2,+$P"PE:

    output2roupPorts '4#A3C"2etChildrenandles9output2roupsKHL%

    Rn4umPorts'n+utput2roup%

    +$"P$"P+,""PE:

    /G 2et the input groups port handles G/

    input2roupPorts '4#A3C"2etChildrenandles9input2roup%

    Rn4um'nputPorts%

    '4P$"P+,""PE:

    /G #or the union transformation% on receiving a row of input% we need to

    G output that row on the output group. G/

    for 9i H i < n4um'nputPorts i:

    Q

    '4#A3C"(etData9output2roupPortsKiL%

    '4#A3C"2etDataoid9input2roupPortsKiL::

    '4#A3C"(et'ndicator9output2roupPortsKiL%

    '4#A3C"2et'ndicator9input2roupPortsKiL: :

    '4#A3C"(et*ength9output2roupPortsKiL%

    '4#A3C"2et*ength9input2roupPortsKiL: :

  • 8/12/2019 24222825 Custom Transformation Overview

    30/77

    T

    /G 5e -now there is only one output group for each partition G/

    return '4#A3C"+utput4otification9output2roupsKHL:

    T

    /GGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGG

    #unction p3union3eof4otification

    Description 4otification that the last row for an input group has already

    !een seen. ,eturn '4#A3#A'*$,E if the session should fail as a result of

    seeing this notification% '4#A3($CCE(( otherwise.

    'nput partition 7 the handle for the partition for the notification

    group 7 the handle for the input group for the notification

    +utput 4one

    GGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGG/

    '4#A3("A"$( p3union3eof4otification9 '4#A3C"3PA,"'"'+43A4D*Epartition%

    '4#A3C"3'4P$"2,+$P3A4D*E group:

    Q

    '4#A3C"*ogMessageM9 eE(*3*+2%

    Ounion3demo An input group received an E+# notificationO:

  • 8/12/2019 24222825 Custom Transformation Overview

    31/77

    return '4#A3($CCE((

    T

    /GGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGG

    #unction p3union3data6dry4otification

    Description 4otification that a transaction has ended. "he data

    !oundary type can either !e commit or roll!ac-.

    ,eturn '4#A3#A'*$,E if the session should fail as a result of

    seeing this notification% '4#A3($CCE(( otherwise.

    'nput partition 7 the handle for the partition for the notification

    transaction"ype 7 commit or roll!ac-

    +utput 4one

    GGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGG/

    '4#A3("A"$( p3union3data6dry4otification 9 '4#A3C"3PA,"'"'+43A4D*Epartition%

    '4#A3C"3DA"A6D,3"PE transaction"ype:

    Q

    /G Do nothing G/

    return '4#A3($CCE((

    T

    /G elper functions G/

  • 8/12/2019 24222825 Custom Transformation Overview

    32/77

    /GGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGG

    #unction validateProperties

    Description alidate that the transformation has all properties expected

    !y a union transformation% such as at least one input group% and only

    one output group. ,eturn '4#A3#A'*$,E if the session should fail since the

    transformation was invalid% '4#A3($CCE(( otherwise.

    'nput partition 7 the handle for the partition

    +utput 4one

    GGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGG/

    '4#A3("A"$( validateProperties9const '4#A3C"3PA,"'"'+43A4D*EGpartition:

    Q

    const '4#A3C"3'4P$"2,+$P3A4D*EG input2roups 4$**

    const '4#A3C"3+$"P$"2,+$P3A4D*EG output2roups 4$**

    si;e3t n4um'nput2roups H% n4um+utput2roups H

    const '4#A3C"3'4P$"P+,"3A4D*EGG all'nput2roupsPorts 4$**

    const '4#A3C"3+$"P$"P+,"3A4D*EG output2roupPorts 4$**

    si;e3t n4umPorts'n+utput2roup H

    si;e3t i H% n"emp4um'nputPorts H

    /G 2et the input and output group handles G/

  • 8/12/2019 24222825 Custom Transformation Overview

    33/77

    input2roups '4#A3C"2etChildrenandles9partitionKHL%

    Rn4um'nput2roups%

    '4P$"2,+$P"PE:

    output2roups '4#A3C"2etChildrenandles9partitionKHL%

    Rn4um+utput2roups%

    +$"P$"2,+$P"PE:

    /G . 4um!er of input groups must !e = 8 and num!er of output groups must

    G !e e&ual to one. G/

    if 9n4um'nput2roups < UU n4um+utput2roups S :

    Q

    '4#A3C"*ogMessageM9 eE(*3E,,+,%

    O$nionDemo "here must !e at least two input groups O

    Oand only one output groupO:

    return '4#A3#A'*$,E

    T

    /G 8. erify that the same num!er of ports are in each group 9including

    G output group:. G/

    output2roupPorts '4#A3C"2etChildrenandles9output2roupsKHL%

    Rn4umPorts'n+utput2roup%

    +$"P$"P+,""PE:

    /G Allocate an array for all input groups ports G/

  • 8/12/2019 24222825 Custom Transformation Overview

    34/77

    all'nput2roupsPorts malloc9si;eof9'4#A3C"3'4P$"P+,"3A4D*EG: G

    n4um'nput2roups:

    for 9i H i < n4um'nput2roups i:

    Q

    all'nput2roupsPortsKiL '4#A3C"2etChildrenandles9input2roupsKiL%

    Rn"emp4um'nputPorts%

    '4P$"P+,""PE:

    if 9 n4umPorts'n+utput2roup S n"emp4um'nputPorts:

    Q

    '4#A3C"*ogMessageM9 eE(*3E,,+,%

    O$nionDemo "he num!er of ports in all input and O

    Othe output group must !e the same.O:

    return '4#A3#A'*$,E

    T

    T

    free9all'nput2roupsPorts:

    /G @. Datatypes of ports in input group must match data types of all other

    G groups.

    "+D+G/

    return '4#A3($CCE((

  • 8/12/2019 24222825 Custom Transformation Overview

    35/77

    T

    Step ,! Build the 0odule

    ou can !uild the module on a 5indows or $4') platform.

    "a!le @7@lists the li!rary file names for each platform when you !uild the module

    "a!le @7@. Module #ile 4ames

    Platform Module #ile 4ame

    5indows

    'n the $nion example% add the following filesm3$nionDemo.cp3$nion.c

    2=!Clic- Project = (ettings.22!Clic- the C/C ta!% and select Preprocessor from the Category field.

    23!'n the Additional 'nclude Directories field% enter the following path and clic-+

  • 8/12/2019 24222825 Custom Transformation Overview

    36/77

    .. ?7!it:

    ma-e 7f ma-efile.aix>?

    P7$)9@87!it:

    ma-e 7f ma-efile.hp

    P7$)9>?7!it:

    ma-e 7f ma-efile.hp>?

    P7$)PA7,'(C

    ma-e 7f ma-efile.hpparisc>?

    *inux ma-e 7f ma-efile.linux

    (olaris ma-e 7f ma-efile.sol

  • 8/12/2019 24222825 Custom Transformation Overview

    37/77

    'n this mapping% two sources with the same ports and datatypes connect to thetwo input groups in the Multigroup External Procedure transformation. "heMultigroup External Procedure transformation ta-es the rows from !oth sourcesand outputs them all through its one output group. "he output group has thesame ports and datatypes as the input groups.

    Step +! -un the Session in a Workflow

    5hen you run the session% the 'ntegration (ervice loo-s for the shared li!rary orD** in the runtime location you specify in the Multigroup External Proceduretransformation.

    "o run a session in a wor-flow

    2!'n the 5or-flow Manager% create a wor-flow.3!Create a session for this mapping in the wor-flow.4!Copy the shared li!rary or D** to the runtime location directory.,!,un the wor-flow containing the session.5hen the 'ntegration (ervice loads a Multigroup External Proceduretransformation !ound to a procedure% it loads the D** or shared li!rary and callsthe procedure you define.

    Custom Transformation un#tions Overview

  • 8/12/2019 24222825 Custom Transformation Overview

    38/77

    Custom transformations operate in conjunction with procedures you createoutside of the Designer to extend PowerCenter functionality. "he Customtransformation functions allow you to develop the transformation logic in aprocedure you associate with a Custom transformation. PowerCenter providestwo sets of functions called generated and AP' functions. "he 'ntegration (erviceuses generated functions to interface with the procedure. 5hen you create aCustom transformation and generate the source code files% the Designer includesthe generated functions in the files. $se the AP' functions in the procedure code

    to develop the transformation logic.

    5hen you write the procedure code% you can configure it to receive a !loc- ofrows from the 'ntegration (ervice or a single row at a time. ou can increase theprocedure performance when it receives and processes a !loc- of rows.

    Working with ?andles

    Most functions are associated with a handle% such as'4#A3C"3PA,"'"'+43A4D*E. "he first parameter for these functions is thehandle the function affects. Multigroup External Procedure transformation

    handles have a hierarchical relationship to each other. A parent handle has a nrelationship to its child handle.

    #igure ?7shows the Multigroup External Procedure transformation handles

    "a!le ?7descri!es the Multigroup External Procedure transformation handles

  • 8/12/2019 24222825 Custom Transformation Overview

    39/77

    "a!le ?7. Custom "ransformation andles

    andle 4ame Description

    '4#A3C"3M+D$*E3A4D*E ,epresents the shared li!rary or D**. "heprocedure can only access the modulehandle in its own shared li!rary or D**. 'tcannot access the module handle in anyother shared li!rary or D**.

    '4#A3C"3P,+C3A4D*E ,epresents a specific procedure within theshared li!rary or D**.ou might use this handle when you needto write a function to affect a procedurereferenced !y multiple Multigroup ExternalProcedure transformations.

    '4#A3C"3",A4(3A4D*E ,epresents a specific Multigroup ExternalProcedure transformation instance in thesession.

    '4#A3C"3PA,"'"'+43A4D*E ,epresents a specific partition in a specificMultigroup External Proceduretransformation instance.

    '4#A3C"3'4P$"2,+$P3A4D*E ,epresents an input group in a partition.

    '4#A3C"3'4P$"P+,"3A4D*E ,epresents an input port in an input groupin a partition.

    '4#A3C"3+$"P$"2,+$P3A4D*E ,epresents an output group in a partition.

    '4#A3C"3+$"P$"P+,"3A4D*E ,epresents an output port in an outputgroup in a partition.

    un#tion -eferen#e

    "he Custom transformation functions include generated and AP' functions.

    "a!le ?78lists the Custom transformation generated functions

    "a!le ?78. Custom "ransformation 2enerated #unctions

    #unction Description

    m3

  • 8/12/2019 24222825 Custom Transformation Overview

    40/77

    "a!le ?7@. Custom "ransformation AP' #unctions

    #unction Description

    '4#A3C"(etDataAccessMode9: (et data access mode function.

    '4#A3C"2etAncestorandle9: 2et ancestor handle function.

    '4#A3C"2etChildrenandles9: 2et children handles function.

    '4#A3C"2et'nputPortandle9: 2et input port handle function.

    '4#A3C"2et+utputPortandle9: 2et output port handle function.'4#A3C"2et'nternalProperty

  • 8/12/2019 24222825 Custom Transformation Overview

    41/77

    '4#A3C"2et,ow(trategy9: 2et row strategy function.

    '4#A3C"(et,ow(trategy9: (et the row strategy function.

    '4#A3C"ChangeDefault,ow(trategy9: Change the default row strategy of atransformation.

    "a!le ?7?lists the Custom transformation array7!ased functions

    "a!le ?7?. Custom "ransformation Array76ased AP' #unctions#unction Description

    '4#A3C"A2et'nput,owMax9: 2et maximum num!er of input rows function.

    '4#A3C"A2et+utput,owMax9: 2et maximum num!er of output rows function.

    '4#A3C"A(et+utput,owMax9: (et maximum num!er of output rows function.

    '4#A3C"A2et4um,ows9: 2et num!er of rows function.

    '4#A3C"A(et4um,ows9: (et num!er of rows function.

    '4#A3C"A's,owalid9: 's row valid function.

    '4#A3C"A2etData

  • 8/12/2019 24222825 Custom Transformation Overview

    42/77

    All array7!ased functions use the prefix '4#A3C"A. All other functions use theprefix '4#A3C".

    $se the following steps to write the procedure code to access a !loc- of rows

    .Call '4#A3C"(etDataAccessMode9: during the procedure initiali;ation% tochange the data access mode to array7!ased.

    8.

    5hen you create a passive Multigroup External Procedure transformation% you

    can also call '4#A3C"(etPass"hruPort9: during procedure initiali;ation to passthrough the data for input/output ports.

    5hen a !loc- of data reaches the Multigroup External Procedure transformationprocedure% the 'ntegration (ervice calls p3.

    6efore calling '4#A3C"+utput4otification9:% call '4#A3C"A(et4um,ows9: to

    notify the 'ntegration (ervice of the num!er of rows the procedure is outputtingin the !loc-.

    W. Call '4#A3C"+utput4otification9:.

    -ules and .uidelines

    $se the following rules and guidelines when you write the procedure code to useeither row7!ased or array7!ased data access mode

    'n row7!ased mode% you can return '4#A3,+5E,,+, in the input rownotification function to indicate the function encountered an error for the row of

    data on input. "he 'ntegration (ervice increments the internal error count.'n array7!ased mode% do not return '4#A3,+5E,,+, in the input rownotification function. "he 'ntegration (ervice treats that as a fatal error. 'f youneed to indicate a row in a !loc- has an error% call the'4#A3C"A(et'nputError,owM9: or '4#A3C"A(et'nputError,ow$9: function.'n row7!ased mode% the 'ntegration (ervice only passes valid rows to theprocedure.'n array7!ased mode% an input !loc- may contain invalid rows% such as dropped%filtered% or error rows. Call '4#A3C"A's,owalid9: to determine if a row in a!loc- is valid.'n array7!ased mode% do not call '4#A3C"A(et4um,ows9: for a passive

    Multigroup External Procedure transformation. ou can call this function foractive Multigroup External Procedure transformations.'n array7!ased mode% call '4#A3C"+utput4otification9: once.'n array7!ased mode% you can call '4#A3C"(etPass"hruPort9: only for passiveMultigroup External Procedure transformations.'n array7!ased mode for passive Multigroup External Proceduretransformations% you must output all rows in an output !loc-% including any errorrow.

  • 8/12/2019 24222825 Custom Transformation Overview

    43/77

    .enerated un#tions

    5hen you use the Designer to generate the procedure code% the Designerincludes a set of functions called generated functions in them3

  • 8/12/2019 24222825 Custom Transformation Overview

    44/77

    "he return value datatype is '4#A3("A"$(. $se '4#A3($CCE(( and'4#A3#A'*$,E for the return value. 5hen the function returns '4#A3#A'*$,E%the 'ntegration (ervice fails the session.

    Pro#edure nitiali/ation un#tion

    "he 'ntegration (ervice calls p3

  • 8/12/2019 24222825 Custom Transformation Overview

    45/77

    "he return value datatype is '4#A3("A"$(. $se '4#A3($CCE(( and'4#A3#A'*$,E for the return value. 5hen the function returns '4#A3#A'*$,E%the 'ntegration (ervice fails the session.

    $ote: 5hen the Multigroup External Procedure transformation re&uires onethread for each partition% you can include thread7specific operations in thepartition initiali;ation function.

    $otifi#ation un#tions

    "he 'ntegration (ervice calls the notification functions when it passes a row ofdata to the Custom transformation.

    "he Designer generates the following notification functions

    p3

  • 8/12/2019 24222825 Custom Transformation Overview

    46/77

    this value when the data access mode is row.'f the input row notification function returns '4#A3,+5E,,+, in array7!asedmode% the 'ntegration (ervice treats it as a fatal error. 'f you need to indicate arow in a !loc- has an error% call the '4#A3C"A(et'nputError,owM9: or'4#A3C"A(et'nputError,ow$9: function.$A&ATA;1--O-! 'ndicates the function encountered a fatal error for therow of data or the !loc- of data. "he 'ntegration (ervice fails the session.

    %ata Boundary $otifi#ation un#tion

    "he 'ntegration (ervice calls the p3

  • 8/12/2019 24222825 Custom Transformation Overview

    47/77

    Argument Datatype 'nput/+utput

    Description

    transformation '4#A3C"3PA,"'"'+43A4D*E 'nput Partition handle.

    group '4#A3C"3'4P$"2,+$P3A4D*E'nput 'nput group handle.

    "he return value datatype is '4#A3("A"$(. $se '4#A3($CCE(( and'4#A3#A'*$,E for the return value. 5hen the function returns '4#A3#A'*$,E%

    the 'ntegration (ervice fails the session.

    %einitiali/ation un#tions

    "he 'ntegration (ervice calls the deinitiali;ation functions after it processes datafor the Custom transformation. $se the deinitiali;ation functions to writeprocesses you want the 'ntegration (ervice to run after it passes all rows of datato the Custom transformation.

    "he Designer generates the following deinitiali;ation functions

    p3

  • 8/12/2019 24222825 Custom Transformation Overview

    48/77

    $ote: 5hen the Multigroup External Procedure transformation re&uires onethread for each partition% you can include thread7specific operations in thepartition deinitiali;ation function.

    Pro#edure %einitiali/ation un#tion

    "he 'ntegration (ervice calls the p3

  • 8/12/2019 24222825 Custom Transformation Overview

    49/77

    module '4#A3C"3M+D$*E3A4D*E'nput Module handle.

    session(tatus '4#A3("A"$( 'nput 'ntegration (ervice uses oneof the following values forthe session(tatusparameter7'4#A3($CCE((. 'ndicatesthe session succeeded.

    7

    I!A_!AIL"R#. Indicates

    the session failed.

    "he return value datatype is '4#A3("A"$(. $se '4#A3($CCE(( and'4#A3#A'*$,E for the return value. 5hen the function returns '4#A3#A'*$,E%the 'ntegration (ervice fails the session.

    $avigation un#tions

    $se the navigation functions when you want the procedure to navigate throughthe handle hierarchy.

    PowerCenter provides the following navigation functions

    '4#A3C"2etAncestorandle9:'4#A3C"2etChildrenandles9:'4#A3C"2et'nputPortandle9:'4#A3C"2et+utputPortandle9:

    .et An#estor ?andle un#tion

    $se the '4#A3C"2etAncestorandle9: function when you want the procedure toaccess a parent handle of a given handle.

    $se the following syntax

    '4#A3C"3A4D*E '4#A3C"2etAncestorandle9'4#A3C"3A4D*E handle%'4#A3C"andle"ype returnandle"ype:

    Argument Datatype 'nput/+utput

    Description

    andle '4#A3C"3A4D*E 'nput andle name.

    returnandle"ype'4#A3C"andle"yp

    e

    'nput ,eturn handle type.

    $se the following values forthe returnandle"ypeparameter7P,+CED$,E"PE7",A4(#+,MA"'+4"PE

    7PA,"'"'+4"PE

  • 8/12/2019 24222825 Custom Transformation Overview

    50/77

    7'4P$"2,+$P"PE7+$"P$"2,+$P"PE7'4P$"P+,""PE7

    O"T$"T$ORTT%$#

    "he handle parameter specifies the handle whose parent you want the procedureto access. "he 'ntegration (ervice returns '4#A3C"3A4D*E if you specify avalid handle in the function. +therwise% it returns a null value.

    "o avoid compilation errors% you must code the procedure to set a handle nameto the return value.

    #or example% you can enter the following code

    '4#A3C"3M+D$*E3A4D*E module '4#A3C"2etAncestorandle9procedureandle% '4#A3C"3andle"ype:

    .et Children ?andles un#tion

    $se the '4#A3C"2etChildrenandles9: function when you want the procedure toaccess the children handles of a given handle.

    $se the following syntax

    '4#A3C"3A4D*EG '4#A3C"2etChildrenandles9'4#A3C"3A4D*E handle%

    si;e3tG pnChildrenandles% '4#A3C"andle"ype returnandle"ype:

    Argument Datatype 'nput/+utput

    Description

    handle '4#A3C"3A4D*E 'nput andle name.

    pnChildrenandles

    si;e3tG +utput 'ntegration (ervice returnsan array of childrenhandles. "hepnChildrenandlesparameter indicates the

    num!er of children handlesin the array.

    returnandle"ype '4#A3C"andle"ype

    'nput $se the following valuesfor the returnandle"ypeparameter7P,+CED$,E"PE7",A4(#+,MA"'+4"P

  • 8/12/2019 24222825 Custom Transformation Overview

    51/77

    E7PA,"'"'+4"PE7'4P$"2,+$P"PE7+$"P$"2,+$P"PE7

    '4P$"P+,""PE7O"T$"T$ORTT%$#

    "he handle parameter specifies the handle whose children you want theprocedure to access. "he 'ntegration (ervice returns '4#A3C"3A4D*EG whenyou specify a valid handle in the function. +therwise% it returns a null value.

    "o avoid compilation errors% you must code the procedure to set a handle nameto the returned value.

    #or example% you can enter the following code

    '4#A3C"3PA,"'"'+43A4D*E partition '4#A3C"2etChildrenandles9procedureandle% pnChildrenandles%'4#A3C"3PA,"'"'+43A4D*E3"PE:

    .et Port ?andle un#tions

    "he 'ntegration (ervice associates the '4#A3C"3'4P$"P+,"3A4D*E withinput and input/output ports% and the '4#A3C"3+$"P$"P+,"3A4D*E withoutput and input/output ports.

    PowerCenter provides the following get port handle functions

    $A&CT.etnputPort?andle@! $se this function when the procedure -nowsthe output port handle for an input/output port and needs the input port handle.

    $se the following syntax

    '4#A3C"'4#A3C"3'4P$"P+,"3A4D*E'4#A3C"2et'nputPortandle9'4#A3C"3+$"P$"P+,"3A4D*EoutputPortandle:

    Argument Datatype 'nput/+utput

    Description

    outputPortandle '4#A3C"3+$"P$"P+,"3A4D*Einput +utput porthandle.

    $A&CT.etOutputPort?andle@! $se this function when the procedure -nowsthe input port handle for an input/output port and needs the output port handle.

    $se the following syntax

  • 8/12/2019 24222825 Custom Transformation Overview

    52/77

    '4#A3C"3+$"P$"P+,"3A4D*E'4#A3C"2et+utputPortandle9'4#A3C"3'4P$"P+,"3A4D*EinputPortandle:

    Argument Datatype 'nput/+utput

    Description

    inputPortandle '4#A3C"3'4P$"P+,"3A4D*Einput 'nput port

    handle.

    "he 'ntegration (ervice returns 4$** when you use the get port handle functionswith input or output ports.

    Property un#tions

    $se the property functions when you want the procedure to access the Customtransformation properties. "he property functions access properties on thefollowing ta!s of the Custom transformation

    PortsProperties'nitiali;ation PropertiesMetadata ExtensionsPort Attri!ute Definitions

    $se the following property functions in initiali;ation functions

    '4#A3C"2et'nternalProperty

  • 8/12/2019 24222825 Custom Transformation Overview

    53/77

    M6C( for a given property 'D.$se the following syntax

    '4#A3("A"$( '4#A3C"2et'nternalProperty(tringM9 '4#A3C"3A4D*Ehandle% si;e3t prop'd% const charGG psPropalue :

    $A&CT.etnternalPropertyString"@!Accesses a value of type string in$nicode for a given property 'D.

    $se the following syntax

    '4#A3("A"$( '4#A3C"2et'nternalProperty(tring$9 '4#A3C"3A4D*Ehandle% si;e3t prop'd% const '4#A3$4'CA,GG psPropalue :

    $A&CT.etnternalPropertynt43@!Accesses a value of type integer for agiven property 'D.

    $se the following syntax

    '4#A3("A"$( '4#A3C"2et'nternalProperty'nt@89 '4#A3C"3A4D*E handle%si;e3t prop'd% '4#A3'4"@8G pnPropalue :

    $A&CT.etnternalPropertyBool@!Accesses a value of type 6oolean for agiven property 'D.

    $se the following syntax

    '4#A3("A"$( '4#A3C"2et'nternalProperty6ool9 '4#A3C"3A4D*E handle%si;e3t prop'd% '4#A36++*E4G p!Propalue :

    $A&CT.etnternalProperty$A&PT-@!Accesses a pointer to a value for agiven property 'D.

    $se the following syntax

    '4#A3("A"$( '4#A3C"2et'nternalProperty'4#A3P",9 '4#A3C"3A4D*Ehandle% si;e3t prop'd% '4#A3P",G pvPropalue :

    "he return value datatype is '4#A3("A"$(. $se '4#A3($CCE(( and'4#A3#A'*$,E for the return value.

    Port and Property Attribute Property %s

    "he following ta!les list the property 'Ds for the port and property attri!utes in theCustom transformation. Each ta!le lists a Custom transformation handle and the

    property 'Ds you can access with the handle in a property function.

    "a!le ?7Blists '4#A3C"3M+D$*E 3A4D*E property 'Ds

    "a!le ?7B. '4#A3C"3M+D$*E Property 'Ds

    andle Property 'D Datatype

    Description

  • 8/12/2019 24222825 Custom Transformation Overview

    54/77

    '4#A3C"3M+D$*E34AME (tring (pecifies the module name.

    '4#A3C"3(E(('+43'4#A3E,('+4

    (tring (pecifies the 'nformaticaversion.

    '4#A3C"3(E(('+43C+DE3PA2E

    'nteger (pecifies the 'ntegration (ervicecode page.

    '4#A3C"3(E(('+43DA"AM+EME4"3M+DE

    'nteger (pecifies the data movementmode. "he 'ntegration (ervice

    returns one of the followingvalues7eA(M3M6C(7eA&'_"ICO(#

    '4#A3C"3(E(('+43A*'DA"E3C+DEPA2E

    6oolean

    (pecifies whether the 'ntegration(ervice enforces code pagevalidation.

    '4#A3C"3(E(('+43P,+D3'4("A**3D',

    (tring (pecifies the 'ntegration (erviceinstallation directory.

    '4#A3C"3(E(('+43'23P,EC'('+43M+DE

    6oolean

    (pecifies whether session isconfigured for high precision.

    '4#A3C"3M+D$*E3,$4"'ME3D',

    (tring (pecifies the runtime directoryfor the D** or shared li!rary.

    '4#A3C"3(E(('+43'(3$PD3(",3A**+5ED

    6oolean

    (pecifies whether the $pdate(trategy "ransformationproperty is selected in thetransformation.

    '4#A3C"3",A4(3+$"P$"3'(3,EPEA"A6*E

    'nteger (pecifies whether the MultigroupExternal Proceduretransformation produces data in

    the same order in every sessionrun. "he 'ntegration (ervicereturns one of the followingvalues7e+$",EPEA"34EE, 7e+$",EPEA"3A*5A( 87eO"TR#$#AT_BA(_O_I

    $"T_OR(#R ) *

    '4#A3C"3",A4(3#A"A*3E,,+,

    6oolean

    (pecifies if the Custom"ransformation caused a fatalerror. "he 'ntegration (ervicereturns one of the followingvalues7'4#A3",$E7I!A_!AL

  • 8/12/2019 24222825 Custom Transformation Overview

    55/77

    "a!le ?7>lists '4#A3C"3P,+C3A4D*E property 'Ds

    "a!le ?7>. '4#A3C"3P,+C3A4D*E Property 'Ds

    andle Property 'D Datatype Description

    '4#A3C"3P,+CED$,E34AME (tring (pecifies the Custom

    transformation procedurename.

    "a!le ?7Wlists '4#A3C"3",A4(3A4D*E property 'Ds

    "a!le ?7W. '4#A3C"3",A4(3A4D*E Property 'Ds

    andle Property 'D Datatype

    Description

    '4#A3C"3",A4(3'4("A4CE34AME

    (tring (pecifies the Customtransformation instance name.

    '4#A3C"3",A4(3",ACE3*EE*

    'nteger (pecifies the tracing level. "he'ntegration (ervice returns one ofthe following values7e",ACE3"E,(E7e",ACE34+,MA*7e",ACE3E,6+(E3'4'"7eTRAC#_+#RBO_(ATA

    '4#A3C"3",A4(3MA36*+C3DA"A

    6oolean

    (pecifies if the 'ntegration (erviceallows the procedure to !loc- inputdata in the current session.

    '4#A3C"3",A4(3M$("36*+C3DA"A

    6oolean

    (pecifies if the 'nputs Must 6loc-Custom transformation property isselected.

    '4#A3C"3",A4(3'(AC"'E 6oolean

    (pecifies whether the Customtransformation is an active orpassive transformation.

    '4#A3C"3",A4(3'(PA,"'"'

    +4A6*E

    6oolea

    n

    (pecifies if you can partition

    sessions that use this Customtransformation.

    '4#A3C"3",A4(3'(3$PDA"E3(",A"E2

    6oolean

    (pecifies if the Customtransformation !ehaves li-e an$pdate (trategy transformation.

    '4#A3C"3",A4(3DE#A$*"3$PDA"E3(",A"E2

    'nteger (pecifies the default updatestrategy.7eD$(3'4(E,"

  • 8/12/2019 24222825 Custom Transformation Overview

    56/77

    7eD$(3$PDA"E7eD$(3DE*E"E7eD$(3,E0EC"7

    e("&_$A&&T,RO"-,'4#A3C"3",A4(34$M3PA,"'"'+4(

    'nteger (pecifies the num!er of partitionsin the sessions that use thisCustom transformation.

    '4#A3C"3",A4(3DA"AC+DEPA2E

    'nteger (pecifies the code page in whichthe 'ntegration (ervice passesdata to the Custom transformation.$se the set data code pagefunction if you want the Customtransformation to access data in adifferent code page.

    '4#A3C"3",A4(3",A4(#+,M3(C+PE

    'nteger (pecifies the transformation scopein the Custom transformation. "he'ntegration (ervice returns one ofthe following values7e"(3,+57e"(3",A4(AC"'+47eT&_ALLI$"T

    '4#A3C"3",A4(32E4E,A"E3",A4(AC"

    6oolean (pecifies if the 2enerate"ransaction property is ena!led."he 'ntegration (ervice returnsone of the following values7'4#A3",$E7I!A_!AL

    '4#A3C"3",A4(3+$"P$"3'(3,EPEA"A6*E

    'nteger (pecifies whether the MultigroupExternal Procedure transformationproduces data in the same order in

    every session run. "he 'ntegration(ervice returns one of the followingvalues7e+$",EPEA"34EE, 7e+$",EPEA"3A*5A( 87eO"TR#$#AT_BA(_O_I$

  • 8/12/2019 24222825 Custom Transformation Overview

    57/77

    "T_OR(#R ) *

    '4#A3C"3",A4(3#A"A*3E,,+,

    6oolean

    (pecifies if the Custom"ransformation caused a fatalerror. "he 'ntegration (ervicereturns one of the following values7'4#A3",$E7

    I!A_!AL

    "a!le ?7Jlists '4#A3C"3'4P$"32,+$P3A4D*E and'4#A3C"3+$"P$"32,+$P3A4D*E property 'Ds

    "a!le ?7J. '4#A3C"3'4P$"32,+$P% '4#A3C"3+$"P$"32,+$PProperty 'Ds

    andle Property 'D Datatype Description

    '4#A3C"32,+$P34AME (tring (pecifies the group name.

    '4#A3C"32,+$P34$M3P+,"(

    'nteger (pecifies the num!er of ports inthe group.

    '4#A3C"32,+$P3'(C+44EC"ED

    6oolean (pecifies if all ports in a groupare connected to anothertransformation.

    '4#A3C"3P+,"34AME (tring (pecifies the port name.

    '4#A3C"3P+,"3CDA"A"PE 'nteger (pecifies the port datatype. "he'ntegration (ervice returns oneof the following values7e'4#A3C"PE3(+,"

    7e'4#A3C"PE3'4"@87e'4#A3C"PE3CA,7e'4#A3C"PE3,A57e'4#A3C"PE3$4'CA,7e'4#A3C"PE3"'ME7

    e'4#A3C"PE3#*+A"7e'4#A3C"PE3D+$6*E7e'4#A3C"PE3DEC'MA*J

    3#')ED7e'4#A3C"PE3DEC'MA*8J3#')ED

    7eI!A_CT%$#_I!A_CT(A

  • 8/12/2019 24222825 Custom Transformation Overview

    58/77

    T#TI'#

    '4#A3C"3P+,"3P,EC'('+4 'nteger (pecifies the port precision.

    '4#A3C"3P+,"3(CA*E 'nteger (pecifies the port scale 9ifapplica!le:.

    '4#A3C"3P+,"3'(3MAPPED 6oolean (pecifies whether the port islin-ed to other transformations inthe mapping.

    '4#A3C"3P+,"3("+,A2E('XE 'nteger (pecifies the internal storagesi;e of the data for a port. "hestorage si;e depends on thedatatype of the port.

    '4#A3C"3P+,"36+$4DDA"A"PE

    'nteger (pecifies the port datatype. $seinstead of'4#A3C"3P+,"3CDA"A"PEif you re!ind the port and specifya datatype other than thedefault.

    "a!le ?7Ylists '4#A3C"3'4P$"P+,"3A4D*E and'4#A3C"3+$"P$"3A4D*E property 'Ds

    "a!le ?7Y. '4#A3C"3'4P$"P+,"% '4#A3C"3+$"P$"P+,"3A4D*EProperty 'Ds

    andle Property 'D Datatype Description

    '4#A3C"3P+,"34AME (tring (pecifies the port name.

    '4#A3C"3P+,"3CDA"A"PE 'nteger (pecifies the port datatype. "he'ntegration (ervice returns oneof the following values

    7e'4#A3C"PE3(+,"7e'4#A3C"PE3'4"@87e'4#A3C"PE3CA,7e'4#A3C"PE3,A57e'4#A3C"PE3$4'CA,7

    e'4#A3C"PE3"'ME7e'4#A3C"PE3#*+A"7e'4#A3C"PE3D+$6*E7e'4#A3C"PE3DEC'MA*J

    3#')ED7e'4#A3C"PE3DEC'MA*8J3#

  • 8/12/2019 24222825 Custom Transformation Overview

    59/77

    ')ED7eI!A_CT%$#_I!A_CT(A

    T#TI'#

    '4#A3C"3P+,"3P,EC'('+4 'nteger (pecifies the port precision.

    '4#A3C"3P+,"3(CA*E 'nteger (pecifies the port scale% ifapplica!le.

    '4#A3C"3P+,"3'(3MAPPED 6oolean (pecifies whether the port is

    lin-ed to other transformations inthe mapping.

    '4#A3C"3P+,"3("+,A2E('XE

    'nteger (pecifies the internal storagesi;e of the data for a port. "hestorage si;e depends on thedatatype of the port.

    '4#A3C"3P+,"36+$4DDA"A"PE

    'nteger (pecifies the port datatype. $seinstead of'4#A3C"3P+,"3CDA"A"PEif you re!ind the port and specifya datatype other than the

    default.

    .et All 1)ternal Property $ames @0BCS or "ni#ode

    PowerCenter provides two functions to access the property names defined onthe Metadata Extensions ta!% 'nitiali;ation Properties ta!% and Port Attri!uteDefinitions ta! of the Custom transformation.

    $se the following functions when you want the procedure to access the propertynames

    $A&CT.etAllProperty$ames0@!Accesses the property names in M6C(.$se the following syntax

    '4#A3("A"$( '4#A3C"2etAllProperty4amesM9'4#A3C"3A4D*E handle%const charGconstGG paProperty4ames% si;e3tG pnProperties:

    Argument Datatype 'nput/+utput

    Description

    handle '4#A3C"3A4D*E 'nput (pecify the handle name.

    paProperty4ames const charGconstGG +utput (pecifies the property name."he 'ntegration (ervicereturns an array of propertynames in M6C(.

    pnProperties si;e3tG +utput 'ndicates the num!er ofproperties in the array.

    $A&CT.etAllProperty$ames"@!Accesses the property names in $nicode.$se the following syntax

  • 8/12/2019 24222825 Custom Transformation Overview

    60/77

    '4#A3("A"$( '4#A3C"2etAllProperty4ames$9'4#A3C"3A4D*E handle%const '4#A3$4'CA,GconstGG pasProperty4ames% si;e3tG pnProperties:

    Argument Datatype 'nput/+utput

    Description

    handle '4#A3C"3A4D*E 'nput (pecify the handlename.

    paProperty4ames const'4#A3$4'CA,GconstGG +utput (pecifies the propertyname. "he 'ntegration(ervice returns anarray of propertynames in $nicode.

    pnProperties si;e3tG +utput 'ndicates the num!erof properties in thearray.

    "he return value datatype is '4#A3("A"$(. $se '4#A3($CCE(( and'4#A3#A'*$,E for the return value.

    .et 1)ternal Properties @0BCS or "ni#ode

    PowerCenter provides functions to access the values of the properties defined onthe Metadata Extensions ta!% 'nitiali;ation Properties ta!% or Port Attri!uteDefinitions ta! of the Custom transformation.

    ou must specify the property names in the functions if you want the procedureto access the values. $se the '4#A3C"2etAllProperty4amesM9: or'4#A3C"2etAllProperty4ames$9: functions to access property names.#or thehandle parameter% specify a handle name from the handle hierarchy. "he

    'ntegration (ervice fails the session if the handle name is invalid.

    $ote: 'f you define an initiali;ation property with the same name as a metadataextension% the 'ntegration (ervice returns the metadata extension value.

    $se the following functions when you want the procedure to access the values ofthe properties

    $A&CT.et1)ternalProperty'datatype(0@!Accesses the value of theproperty in M6C(. $se the syntax as shown in "a!le ?7H

    "a!le ?7H. Property #unctions 9M6C(:

    (yntax PropertyDatatype

    '4#A3("A"$('4#A3C"2etExternalProperty(tringM9'4#A3C"3A4D*Ehandle% const charG sProp4ame% const charGG psPropalue:

    (tring

    '4#A3("A"$('4#A3C"2etExternalProperty'4"@8M9'4#A3C"3A4D*E

    'nteger

  • 8/12/2019 24222825 Custom Transformation Overview

    61/77

    handle% const charG sProp4ame% '4#A3'4"@8G pnPropalue:

    '4#A3("A"$('4#A3C"2etExternalProperty6oolM9'4#A3C"3A4D*Ehandle% const charG sProp4ame% '4#A36++*E4Gp!Propalue:

    6oolean

    $A&CT.et1)ternalProperty'datatype("@!Accesses the value of theproperty in $nicode. $se the syntax as shown in "a!le ?7

    "a!le ?7. Property un#tions @"ni#ode(yntax Property

    Datatype

    '4#A3("A"$('4#A3C"2etExternalProperty(tring$9'4#A3C"3A4D*Ehandle% '4#A3$4'CA,G sProp4ame% '4#A3$4'CA,GGpsPropalue:

    (tring

    '4#A3("A"$('4#A3C"2etExternalProperty(tring$9'4#A3C"3A4D*Ehandle% '4#A3$4'CA,G sProp4ame% '4#A3'4"@8GpnPropalue:

    'nteger

    '4#A3("A"$('4#A3C"2etExternalProperty(tring$9'4#A3C"3A4D*Ehandle% '4#A3$4'CA,G sProp4ame% '4#A36++*E4Gp!Propalue:

    6oolean

    "he return value datatype is '4#A3("A"$(. $se '4#A3($CCE(( and'4#A3#A'*$,E for the return value.

    -ebind %atatype un#tions

    ou can re!ind a port with a datatype other than the default datatype withPowerCenter. $se the re!ind datatype functions if you want the procedure toaccess data in a datatype other than the default datatype. ou must re!ind theport with a compati!le datatype.

    ou can only use these functions in the initiali;ation functions.

    Consider the following rules when you re!ind the datatype for an output orinput/output port

    ou must use the data handling functions to set the data and the indicator for

    that port. $se the '4#A3C"(etData9: and '4#A3C"(et'ndicator9: functions inrow7!ased mode% and use the '4#A3C"A(etData9: function in array7!asedmode.Do not call the '4#A3C"(etPass"hruPort9: function for the output port.

    "a!le ?78lists compati!le datatypes

    "a!le ?78. Compati!le Datatypes

  • 8/12/2019 24222825 Custom Transformation Overview

    62/77

    Default Datatype Compati!le 5ith

    Char $nichar

    $nichar Char

    Date '4#A3DA"E"'ME$se the following syntaxstruct '4#A3DA"E"'MEQ

    int nearint nMonthint nDayint nourint nMinuteint n(econdint n4ano(econdT

    DecJ Char% $nichar

    Dec8J Char% $nichar

    PowerCenter provides the following re!ind datatype functions

    $A&CT-ebindnput%ataType@! ,e!inds the input port. $se the followingsyntax

    '4#A3("A"$('4#A3C",e!ind'nputData"ype9'4#A3C"3'4P$"P+,"3A4D*E portandle%'4#A3CDA"A"PE datatype:

    $A&CT-ebindOutput%ataType@!,e!inds the output port. $se the followingsyntax

    '4#A3("A"$('4#A3C",e!ind+utputData"ype9'4#A3C"3+$"P$"P+,"3A4D*Eportandle% '4#A3CDA"A"PE datatype:

    Argument

    Datatype 'nput/+utput

    Description

    portandle

    '4#A3C"3+$"P$"P+,"3A4D*E

    'nput +utput port handle.

    datatype '4#A3CDA"A"PE 'nput "he datatype with which youre!ind the port. $se thefollowing values for thedatatype parameter7e'4#A3C"PE3(+,"7e'4#A3C"PE3'4"@8

  • 8/12/2019 24222825 Custom Transformation Overview

    63/77

    7e'4#A3C"PE3CA,7e'4#A3C"PE3,A57e'4#A3C"PE3$4'CA,7e'4#A3C"PE3"'ME

    7e'4#A3C"PE3#*+A"7e'4#A3C"PE3D+$6*E7e'4#A3C"PE3DEC'MA*J3#')ED7e'4#A3C"PE3DEC'MA*8J

    3#')ED7eI!A_CT%$#_I!A_CT(AT#TI'#

    "he return value datatype is '4#A3("A"$(. $se '4#A3($CCE(( and'4#A3#A'*$,E for the return value.

    %ata ?andling un#tions @-ow8Based 0ode

    5hen the 'ntegration (ervice calls the input row notification function% it notifiesthe procedure that the procedure can access a row or !loc- of data. owever% toget data from the input port% modify it% and set data in the output port% you mustuse the data handling functions in the input row notification function. 5hen thedata access mode is row7!ased% use the row7!ased data handling functions.

    'nclude the '4#A3C"2etData

  • 8/12/2019 24222825 Custom Transformation Overview

    64/77

    ou must modify the function name depending on the datatype of the port youwant the procedure to access.

    "a!le ?7@lists the '4#A3C"2etData

  • 8/12/2019 24222825 Custom Transformation Overview

    65/77

    '4#A3("A"$( '4#A3C"(etData9'4#A3C"3+$"P$"P+,"3A4D*Edataandle% voidG data:

    "he return value datatype is '4#A3("A"$(. $se '4#A3($CCE(( and'4#A3#A'*$,E for the return value.

    $ote: 'f you use the '4#A3C"(etPass"hruPort9: function on an input/output port%do not use set the data or indicator for that port.

    ndi#ator un#tions @-ow8Based 0ode

    $se the indicator functions when you want the procedure to get the indicator foran input port or to set the indicator for an output port. "he indicator for a portindicates whether the data is valid% null% or truncated.

    PowerCenter provides the following indicator functions

    $A&CT.etndi#ator@! 2ets the indicator for an input port. $se the followingsyntax

    '4#A3'4D'CA"+, '4#A3C"2et'ndicator9'4#A3C"3'4P$"P+,"3A4D*Edataandle:"he return value datatype is '4#A3'4D'CA"+,. $se the following values for'4#A3'4D'CA"+,7$A&%ATA&7A;%!'ndicates the data is valid.7$A&$";;&%ATA!'ndicates a null value.7$A&%ATA&T-"$CAT1%!'ndicates the data has !een truncated.$A&CTSetndi#ator@! (ets the indicator for an output port. $se thefollowing syntax

    '4#A3("A"$( '4#A3C"(et'ndicator9'4#A3C"3+$"P$"P+,"3A4D*Edataandle% '4#A3'4D'CA"+, indicator:

    Argument

    Datatype 'nput/+utput

    Description

    dataandle

    '4#A3C"3+$"P$"P+,"3A4D*E

    'nput +utput port handle.

    indicator '4#A3'4D'CA"+, 'nput "he indicator value forthe output port. $se oneof the following values

    7

    '4#A3DA"A3A*'D.'ndicates the data isvalid.

    7'4#A34$**3DA"A.'ndicates a null value.

    7

    I!A_(ATA_TR"C

    AT#(. Indicates the

    data has been truncated.

    "he return value datatype is '4#