WebSphere DataStage and QualityStage


Version 8

Parallel Job Developer Guide

SC18-9891-00
 WebSphere DataStage and QualityStage
®


Version 8

Parallel Job Developer Guide

SC18-9891-00
 Note
Before using this information and the product that it supports, be sure to read the general information under “Notices and
trademarks” on page 615.

© Ascential Software Corporation 2000, 2005.

© Copyright International Business Machines Corporation 2006. All rights reserved.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Contents
Chapter 1. Introduction . . . . . . . . 1 Reading from a data set . . . . . . . . . 68
WebSphere DataStage parallel jobs . . . . . . . 1 Stage page . . . . . . . . . . . . . . . 68
Advanced tab . . . . . . . . . . . . 68
Chapter 2. Designing parallel jobs . . . 3 Input page. . . . . . . . . . . . . . . 68
Input link properties tab . . . . . . . . . 69
Parallel processing . . . . . . . . . . . . 3
Partitioning tab . . . . . . . . . . . . 69
Pipeline parallelism . . . . . . . . . . . 3
Output page . . . . . . . . . . . . . . 71
Partition parallelism . . . . . . . . . . . 4
Output link properties tab . . . . . . . . 71
Combining pipeline and partition parallelism . . 5
Repartitioning data . . . . . . . . . . . 5
Parallel processing environments . . . . . . . 6 Chapter 5. Sequential file stage . . . . 73
The configuration file . . . . . . . . . . . 7 Example of writing a sequential file . . . . . . 74
Partitioning, repartitioning, and collecting data . . . 8 Example of reading a sequential file . . . . . . 75
Partitioning . . . . . . . . . . . . . . 8 Must do’s . . . . . . . . . . . . . . . 77
Collecting . . . . . . . . . . . . . . 17 Writing to a file . . . . . . . . . . . . 77
Repartitioning data . . . . . . . . . . . 21 Reading from a file . . . . . . . . . . . 77
The mechanics of partitioning and collecting . . 22 Stage page . . . . . . . . . . . . . . . 77
Sorting data . . . . . . . . . . . . . . 24 Advanced tab . . . . . . . . . . . . 77
Data sets . . . . . . . . . . . . . . . 24 NLS Map tab . . . . . . . . . . . . . 78
Metadata . . . . . . . . . . . . . . . 25 Input page. . . . . . . . . . . . . . . 78
Runtime column propagation . . . . . . . 25 Input link properties tab . . . . . . . . . 78
Table definitions . . . . . . . . . . . . 25 Partitioning tab . . . . . . . . . . . . 80
Schema files and partial schemas . . . . . . 26 Input link format tab . . . . . . . . . . 81
Data types . . . . . . . . . . . . . . 26 Output page . . . . . . . . . . . . . . 88
Strings and ustrings . . . . . . . . . . 29 Output link properties tab . . . . . . . . 88
Complex data types . . . . . . . . . . 29
Date and time formats . . . . . . . . . . 30 Chapter 6. File set stage . . . . . . . 99
Incorporating server job functionality . . . . . . 36 Must do’s . . . . . . . . . . . . . . 100
Writing to a file . . . . . . . . . . . 100
Chapter 3. Stage editors . . . . . . . 37 Reading from a file . . . . . . . . . . 100
Showing stage validation errors . . . . . . . 41 Stage page . . . . . . . . . . . . . . 100
The stage page . . . . . . . . . . . . . 41 Advanced tab . . . . . . . . . . . . 100
General tab . . . . . . . . . . . . . 41 NLS Map tab . . . . . . . . . . . . 101
Properties tab. . . . . . . . . . . . . 42 Input page . . . . . . . . . . . . . . 101
Advanced tab . . . . . . . . . . . . 43 Input link properties tab. . . . . . . . . 101
Link ordering tab . . . . . . . . . . . 44 Partitioning tab . . . . . . . . . . . . 103
NLS Map tab . . . . . . . . . . . . . 46 Input link format tab . . . . . . . . . . 105
NLS Locale tab . . . . . . . . . . . . 46 Output page . . . . . . . . . . . . . . 111
Inputs page . . . . . . . . . . . . . . 47 Output link properties tab . . . . . . . . 112
General tab . . . . . . . . . . . . . 47 Reject link properties . . . . . . . . . . 113
Properties tab. . . . . . . . . . . . . 47 Output link Format tab . . . . . . . . . 113
Partitioning tab . . . . . . . . . . . . 47 Using RCP With file set stages . . . . . . . 119
Format tab. . . . . . . . . . . . . . 49
Columns Tab . . . . . . . . . . . . . 50 Chapter 7. Lookup file set stage . . . 121
Advanced tab . . . . . . . . . . . . 61 Must do’s . . . . . . . . . . . . . . 123
Output page . . . . . . . . . . . . . . 62 Creating a lookup file set . . . . . . . . 123
General tab . . . . . . . . . . . . . 62 Looking up a lookup file set . . . . . . . 123
Properties tab. . . . . . . . . . . . . 62 Stage page . . . . . . . . . . . . . . 123
Format tab. . . . . . . . . . . . . . 62 Advanced tab . . . . . . . . . . . . 123
Columns tab . . . . . . . . . . . . . 63 NLS Map tab . . . . . . . . . . . . 124
Mapping tab . . . . . . . . . . . . . 64 Input page . . . . . . . . . . . . . . 124
Advanced tab . . . . . . . . . . . . 65 Input link properties tab. . . . . . . . . 124
Partitioning tab . . . . . . . . . . . . 127
Chapter 4. Data set stage . . . . . . . 67 Output page . . . . . . . . . . . . . . 128
Must do’s . . . . . . . . . . . . . . . 67 Output link properties tab . . . . . . . . 128
Writing to a data set . . . . . . . . . . 68

© Copyright IBM Corp. 2006 iii

Chapter 8. External source stage . . . 131 Exiting the expression editor . . . . . . . 180
Must do’s . . . . . . . . . . . . . . 132 Configuring the expression editor . . . . . 180
Stage page . . . . . . . . . . . . . . 132 System variables . . . . . . . . . . . 180
Advanced tab . . . . . . . . . . . . 132 Guide to using transformer expressions and
NLS Map tab . . . . . . . . . . . . 133 stage variables . . . . . . . . . . . . 181
Output page . . . . . . . . . . . . . . 133 Transformer stage properties . . . . . . . . 182
Output link properties tab . . . . . . . . 133 Stage page . . . . . . . . . . . . . 182
Output link Format tab . . . . . . . . . 134 Input page . . . . . . . . . . . . . 185
Using RCP With External Source Stages . . . 141 Output page . . . . . . . . . . . . . 186

Chapter 9. External Target stage . . . 143 Chapter 12. BASIC Transformer

Must do’s . . . . . . . . . . . . . . 144 stages . . . . . . . . . . . . . . 187
Stage page . . . . . . . . . . . . . . 144 Must do’s . . . . . . . . . . . . . . 187
Advanced tab . . . . . . . . . . . . 144 BASIC Transformer editor components . . . . . 187
NLS Map tab . . . . . . . . . . . . 145 Toolbar . . . . . . . . . . . . . . 187
Input page . . . . . . . . . . . . . . 145 Link area . . . . . . . . . . . . . . 188
Input link properties tab. . . . . . . . . 145 Metadata area . . . . . . . . . . . . 188
Partitioning tab . . . . . . . . . . . . 146 Shortcut menus . . . . . . . . . . . . 188
Format tab . . . . . . . . . . . . . 147 BASIC Transformer stage basic concepts . . . . 189
Using RCP with External Target stages . . . . . 155 Input link . . . . . . . . . . . . . 189
Output links . . . . . . . . . . . . . 189
Chapter 10. Complex Flat File stage 157 Before-stage and after-stage routines. . . . . 190
Editing a Complex Flat File stage as a source . . . 157 Editing BASIC transformer stages . . . . . . 190
Creating record definitions . . . . . . . . 158 Using drag and drop . . . . . . . . . . 190
Column definitions . . . . . . . . . . 158 Find and replace facilities . . . . . . . . 191
Defining record ID constraints . . . . . . . 160 Select facilities . . . . . . . . . . . . 191
Selecting output columns . . . . . . . . 161 Creating and deleting columns . . . . . . 192
Defining output link constraints . . . . . . 164 Moving columns within a link . . . . . . . 192
Editing a Complex Flat File stage as a target . . . 164 Editing column meta data . . . . . . . . 192
Reject links . . . . . . . . . . . . . . 165 Defining output column derivations . . . . . 193
Editing multiple derivations . . . . . . . 194
Specifying before-stage and after-stage
Chapter 11. Transformer stage . . . . 167
subroutines . . . . . . . . . . . . . 195
Must do’s . . . . . . . . . . . . . . 167
Defining constraints and handling reject links 196
Transformer editor components . . . . . . . 168
Specifying link order . . . . . . . . . . 197
Toolbar . . . . . . . . . . . . . . 168
Defining local stage variables . . . . . . . 197
Link area . . . . . . . . . . . . . . 168
The WebSphere DataStage expression editor . . . 198
Metadata area . . . . . . . . . . . . 169
Expression format . . . . . . . . . . . 198
Shortcut menus . . . . . . . . . . . . 169
Entering expressions . . . . . . . . . . 199
Transformer stage basic concepts . . . . . . . 170
Completing variable names . . . . . . . . 200
Input link . . . . . . . . . . . . . 170
Validating the expression . . . . . . . . 200
Output links . . . . . . . . . . . . . 170
Exiting the expression editor . . . . . . . 200
Editing Transformer stages . . . . . . . . . 171
Configuring the expression editor . . . . . 200
Using drag and drop . . . . . . . . . . 171
BASIC Transformer stage properties . . . . . . 200
Find and replace facilities . . . . . . . . 171
Stage page . . . . . . . . . . . . . 200
Select facilities . . . . . . . . . . . . 172
Input page . . . . . . . . . . . . . 201
Creating and deleting columns . . . . . . 172
Output page . . . . . . . . . . . . . 203
Moving columns within a link . . . . . . . 173
Editing column meta data . . . . . . . . 173
Defining output column derivations . . . . . 173 Chapter 13. Aggregator stage . . . . 205
Editing multiple derivations . . . . . . . 174 Example . . . . . . . . . . . . . . . 206
Handling null values in input columns . . . . 176 Must do’s . . . . . . . . . . . . . . 208
Defining constraints and handling otherwise Stage page . . . . . . . . . . . . . . 209
links . . . . . . . . . . . . . . . 176 Properties tab . . . . . . . . . . . . 209
Specifying link order . . . . . . . . . . 177 Advanced tab . . . . . . . . . . . . 214
Defining local stage variables . . . . . . . 177 NLS Locale tab . . . . . . . . . . . . 215
The WebSphere DataStage expression editor . . . 178 Input page . . . . . . . . . . . . . . 215
Expression format . . . . . . . . . . . 178 Partitioning tab . . . . . . . . . . . . 215
Entering expressions . . . . . . . . . . 179 Output page . . . . . . . . . . . . . . 216
Completing variable names . . . . . . . . 179 Mapping tab . . . . . . . . . . . . 217
Validating the expression . . . . . . . . 180

iv Parallel Job Developer Guide

Chapter 14. Join stage . . . . . . . 219 Expression Format. . . . . . . . . . . 250
Join versus lookup . . . . . . . . . . . 220 Entering Expressions . . . . . . . . . . 251
Example joins . . . . . . . . . . . . . 220 Completing Variable Names . . . . . . . 251
Inner join . . . . . . . . . . . . . . 221 Validating the Expression . . . . . . . . 252
Left outer join . . . . . . . . . . . . 221 Exiting the Expression Editor . . . . . . . 252
Right outer join . . . . . . . . . . . 221 Configuring the Expression Editor . . . . . 252
Full outer join . . . . . . . . . . . . 222
Must do’s . . . . . . . . . . . . . . 222 Chapter 17. Sort stage . . . . . . . 253
Stage page . . . . . . . . . . . . . . 223 Examples . . . . . . . . . . . . . . . 255
Properties tab . . . . . . . . . . . . 223 Sequential Sort . . . . . . . . . . . . 255
Advanced tab . . . . . . . . . . . . 224 Parallel sort . . . . . . . . . . . . . 257
Link ordering tab . . . . . . . . . . . 224 Total sort . . . . . . . . . . . . . . 258
NLS Locale tab . . . . . . . . . . . . 224 Must do’s . . . . . . . . . . . . . . 259
Input page . . . . . . . . . . . . . . 224 Stage page . . . . . . . . . . . . . . 259
Partitioning on input links . . . . . . . . 225 Properties tab . . . . . . . . . . . . 259
Output page . . . . . . . . . . . . . . 226 Advanced tab . . . . . . . . . . . . 262
Mapping tab . . . . . . . . . . . . 226 NLS Locale tab . . . . . . . . . . . . 262
Input page . . . . . . . . . . . . . . 263
Chapter 15. Merge Stage . . . . . . 227 Partitioning tab . . . . . . . . . . . . 263
Example merge . . . . . . . . . . . . . 228 Output page . . . . . . . . . . . . . . 264
Must do’s . . . . . . . . . . . . . . 229 Mapping tab . . . . . . . . . . . . 265
Stage page . . . . . . . . . . . . . . 229
Properties tab . . . . . . . . . . . . 229 Chapter 18. Funnel Stage . . . . . . 267
Advanced Tab . . . . . . . . . . . . 231 Examples . . . . . . . . . . . . . . . 268
Link Ordering tab . . . . . . . . . . . 231 Continuous funnel example . . . . . . . 268
NLS Locale tab . . . . . . . . . . . . 231 Sort Funnel Example . . . . . . . . . . 269
Input page . . . . . . . . . . . . . . 231 Sequence funnel example . . . . . . . . 270
Partitioning tab . . . . . . . . . . . . 232 Must do’s . . . . . . . . . . . . . . 271
Output page . . . . . . . . . . . . . . 233 Stage page . . . . . . . . . . . . . . 271
Reject links . . . . . . . . . . . . . 233 Properties tab . . . . . . . . . . . . 271
Mapping tab . . . . . . . . . . . . 234 Advanced tab . . . . . . . . . . . . 272
Link Ordering tab . . . . . . . . . . . 273
Chapter 16. Lookup Stage . . . . . . 235 NLS Locale tab . . . . . . . . . . . . 273
Lookup Versus Join . . . . . . . . . . . 236 Input page . . . . . . . . . . . . . . 273
Example Look Up . . . . . . . . . . . . 236 Partitioning on input links . . . . . . . . 273
Must Do’s . . . . . . . . . . . . . . 237 Output page . . . . . . . . . . . . . . 275
Using In-Memory Lookup tables . . . . . . 238 Mapping tab . . . . . . . . . . . . 275
Using Oracle or DB2 Databases Directly . . . 239
Using Lookup File Set . . . . . . . . . 240 Chapter 19. Remove Duplicates Stage 277
Lookup Editor Components . . . . . . . . 240 Example . . . . . . . . . . . . . . . 277
Toolbar . . . . . . . . . . . . . . 240 Must do’s . . . . . . . . . . . . . . 278
Link Area . . . . . . . . . . . . . 241 Stage page . . . . . . . . . . . . . . 278
Meta Data Area . . . . . . . . . . . 241 Properties tab . . . . . . . . . . . . 279
Shortcut Menus . . . . . . . . . . . 241 Advanced tab . . . . . . . . . . . . 279
Editing Lookup Stages . . . . . . . . . . 242 NLS Locale tab . . . . . . . . . . . . 280
Using Drag and Drop . . . . . . . . . 242 Input page . . . . . . . . . . . . . . 280
Find and Replace Facilities . . . . . . . . 243 Partitioning on input links . . . . . . . . 280
Select Facilities . . . . . . . . . . . . 243 Output page . . . . . . . . . . . . . . 282
Creating and Deleting Columns . . . . . . 244 Mapping tab . . . . . . . . . . . . 282
Moving Columns Within a Link . . . . . . 244
Editing Column Meta Data . . . . . . . . 244 Chapter 20. Compress stage . . . . . 283
Defining Output Column Derivations . . . . 244 Must do’s . . . . . . . . . . . . . . 284
Defining Input Column Key Expressions . . . 245 Stage page . . . . . . . . . . . . . . 284
Lookup Stage Properties . . . . . . . . . . 245 Properties tab . . . . . . . . . . . . 284
Stage Page . . . . . . . . . . . . . 246 Advanced tab . . . . . . . . . . . . 284
Input Page . . . . . . . . . . . . . 247 Input page . . . . . . . . . . . . . . 285
Output Page . . . . . . . . . . . . . 249 Partitioning on input links . . . . . . . . 285
Lookup Stage Conditions . . . . . . . . . 249 Output page . . . . . . . . . . . . . . 286
Range lookups . . . . . . . . . . . . . 250
The WebSphere DataStage Expression Editor . . . 250
Chapter 21. Expand Stage . . . . . . 287
Contents v
Must do’s . . . . . . . . . . . . . . 287 Must do’s . . . . . . . . . . . . . . 333
Stage page . . . . . . . . . . . . . . 287 Stage page . . . . . . . . . . . . . . 333
Properties tab . . . . . . . . . . . . 287 Properties tab . . . . . . . . . . . . 333
Advanced tab . . . . . . . . . . . . 288 Advanced tab . . . . . . . . . . . . 336
Input page . . . . . . . . . . . . . . 288 Link Ordering tab . . . . . . . . . . . 336
Partitioning on input Llinks . . . . . . . 288 NLS Locale tab . . . . . . . . . . . . 336
Output page . . . . . . . . . . . . . . 289 Input page . . . . . . . . . . . . . . 337
Partitioning tab . . . . . . . . . . . . 337
Chapter 22. Copy stage . . . . . . . 291 Output page . . . . . . . . . . . . . . 338
Example . . . . . . . . . . . . . . . 291 Mapping tab . . . . . . . . . . . . 338
Must do’s . . . . . . . . . . . . . . 296
Stage page . . . . . . . . . . . . . . 297 Chapter 27. Change Apply stage . . . 341
Properties tab . . . . . . . . . . . . 297 Example Data . . . . . . . . . . . . . 342
Advanced tab . . . . . . . . . . . . 297 Must do’s . . . . . . . . . . . . . . 343
Input page . . . . . . . . . . . . . . 297 Stage page . . . . . . . . . . . . . . 344
Partitioning on input links . . . . . . . . 298 Properties tab . . . . . . . . . . . . 344
Output page . . . . . . . . . . . . . . 299 Advanced tab . . . . . . . . . . . . 346
Mapping tab . . . . . . . . . . . . 299 Link Ordering tab . . . . . . . . . . . 346
NLS Locale tab . . . . . . . . . . . . 346
Chapter 23. Modify stage . . . . . . 301 Input page . . . . . . . . . . . . . . 347
Examples . . . . . . . . . . . . . . . 301 Partitioning tab . . . . . . . . . . . . 347
Dropping and keeping columns . . . . . . 301 Output page . . . . . . . . . . . . . . 348
Changing data type . . . . . . . . . . 302 Mapping tab . . . . . . . . . . . . 348
Null handling . . . . . . . . . . . . 302
Must do’s . . . . . . . . . . . . . . 303 Chapter 28. Difference stage . . . . . 351
Stage page . . . . . . . . . . . . . . 303 Example data . . . . . . . . . . . . . 351
Properties tab . . . . . . . . . . . . 303 Must do’s . . . . . . . . . . . . . . 353
Advanced tab . . . . . . . . . . . . 315 Stage page . . . . . . . . . . . . . . 353
Input page . . . . . . . . . . . . . . 316 Properties tab . . . . . . . . . . . . 353
Partitioning on input links . . . . . . . . 316 Advanced tab . . . . . . . . . . . . 355
Output page . . . . . . . . . . . . . . 317 Link Ordering tab . . . . . . . . . . . 356
NLS Locale tab . . . . . . . . . . . . 356
Chapter 24. Filter Stage . . . . . . . 319 Input page . . . . . . . . . . . . . . 356
Specifying the filter . . . . . . . . . . . 319 Partitioning tab . . . . . . . . . . . . 356
Input data columns . . . . . . . . . . 320 Output page . . . . . . . . . . . . . . 358
Supported Boolean expressions and operators 320 Mapping tab . . . . . . . . . . . . 358
String comparison . . . . . . . . . . . 320
Examples . . . . . . . . . . . . . . 321 Chapter 29. Compare stage . . . . . 359
Must do’s . . . . . . . . . . . . . . 321 Example Data . . . . . . . . . . . . . 359
Stage page . . . . . . . . . . . . . . 322 Must do’s . . . . . . . . . . . . . . 361
Properties tab . . . . . . . . . . . . 322 Stage page . . . . . . . . . . . . . . 361
Advanced tab . . . . . . . . . . . . 323 Properties tab . . . . . . . . . . . . 361
Link Ordering tab . . . . . . . . . . . 323 Advanced tab . . . . . . . . . . . . 362
NLS Locale tab . . . . . . . . . . . . 323 Link Ordering tab . . . . . . . . . . . 363
Input page . . . . . . . . . . . . . . 324 NLS Locale tab . . . . . . . . . . . . 363
Partitioning on input links . . . . . . . . 324 Input page . . . . . . . . . . . . . . 363
Output page . . . . . . . . . . . . . . 325 Partitioning tab . . . . . . . . . . . . 363
Mapping tab . . . . . . . . . . . . 325 Output page . . . . . . . . . . . . . . 365

Chapter 25. External Filter stage . . . 327 Chapter 30. Encode Stage . . . . . . 367
Must do’s . . . . . . . . . . . . . . 327 Must do’s . . . . . . . . . . . . . . 367
Stage page . . . . . . . . . . . . . . 327 Stage page . . . . . . . . . . . . . . 367
Properties tab . . . . . . . . . . . . 327 Properties tab . . . . . . . . . . . . 368
Advanced tab . . . . . . . . . . . . 328 Advanced tab . . . . . . . . . . . . 368
Input page . . . . . . . . . . . . . . 328 Input page . . . . . . . . . . . . . . 368
Partitioning on input links . . . . . . . . 329 Partitioning tab . . . . . . . . . . . . 369
Output page . . . . . . . . . . . . . . 330 Output page . . . . . . . . . . . . . . 370

Chapter 26. Change Capture stage 331 Chapter 31. Decode stage . . . . . . 371
Example Data . . . . . . . . . . . . . 332 Must do’s . . . . . . . . . . . . . . 371

vi Parallel Job Developer Guide

Stage page . . . . . . . . . . . . . . 371 Purpose codes in a Slowly Changing Dimension
Properties tab . . . . . . . . . . . . 371 stage . . . . . . . . . . . . . . . . 408
Advanced tab . . . . . . . . . . . . 372 Surrogate keys in a Slowly Changing Dimension
Input page . . . . . . . . . . . . . . 372 stage . . . . . . . . . . . . . . . . 408
Partitioning tab . . . . . . . . . . . . 372 Editing a Slowly Changing Dimension stage . . . 409
Output page . . . . . . . . . . . . . . 373 Defining the match condition . . . . . . . 410
Selecting purpose codes . . . . . . . . . 410
Chapter 32. Switch stage . . . . . . 375 Specifying information about a key source . . . 411
Example . . . . . . . . . . . . . . . 375 Creating derivations for dimension columns . . 411
Must do’s . . . . . . . . . . . . . . 376 Mapping data to the output link . . . . . . 412
Stage page . . . . . . . . . . . . . . 377 Dimension update action . . . . . . . . . 412
Properties tab . . . . . . . . . . . . 377
Advanced tab . . . . . . . . . . . . 379 Chapter 37. Column Import stage . . . 415
Link Ordering tab . . . . . . . . . . . 379 Examples . . . . . . . . . . . . . . . 415
NLS Locale tab . . . . . . . . . . . . 379 Must do’s . . . . . . . . . . . . . . 418
Input page . . . . . . . . . . . . . . 379 Stage page . . . . . . . . . . . . . . 418
Partitioning tab . . . . . . . . . . . . 380 Properties tab . . . . . . . . . . . . 418
Output page . . . . . . . . . . . . . . 381 Advanced tab . . . . . . . . . . . . 420
Mapping tab . . . . . . . . . . . . 381 Input page . . . . . . . . . . . . . . 420
Reject link . . . . . . . . . . . . . 382 Partitioning tab . . . . . . . . . . . . 420
Output page . . . . . . . . . . . . . . 422
Chapter 33. FTP Enterprise Stage . . . 383 Mapping tab . . . . . . . . . . . . 422
Restartability . . . . . . . . . . . . . 383 Mapping tab . . . . . . . . . . . . 422
Must Do’s . . . . . . . . . . . . . . 384 Reject link . . . . . . . . . . . . . 422
Transferring Data to a Remote Host Using the Using RCP With Column Import Stages . . . . 423
FTP Enterprise Stage . . . . . . . . . . 384
Accessing Data from a Remote Host Using the Chapter 38. Column Export stage . . . 425
FTP Enterprise Stage . . . . . . . . . . 384 Examples . . . . . . . . . . . . . . . 425
Stage Page . . . . . . . . . . . . . . 384 Must do’s . . . . . . . . . . . . . . 428
Advanced tab . . . . . . . . . . . . 385 Stage page . . . . . . . . . . . . . . 428
NLS Map Tab . . . . . . . . . . . . 385 Properties tab . . . . . . . . . . . . 429
Input Page . . . . . . . . . . . . . . 385 Advanced tab . . . . . . . . . . . . 430
Properties Tab . . . . . . . . . . . . 385 Input page . . . . . . . . . . . . . . 430
Partitioning Tab . . . . . . . . . . . 388 Partitioning tab . . . . . . . . . . . . 430
Output Page . . . . . . . . . . . . . . 390 Format tab . . . . . . . . . . . . . 432
Properties Tab . . . . . . . . . . . . 390 Mapping tab . . . . . . . . . . . . 439
Reject link . . . . . . . . . . . . . 439
Chapter 34. Generic stage . . . . . . 395 Using RCP with Column Export stages . . . . . 439
Must do’s . . . . . . . . . . . . . . 395
Stage page . . . . . . . . . . . . . . 396 Chapter 39. Make Subrecord stage 441
Properties tab . . . . . . . . . . . . 396 Examples . . . . . . . . . . . . . . . 442
Advanced tab . . . . . . . . . . . . 396 Must do’s . . . . . . . . . . . . . . 445
Link Ordering tab . . . . . . . . . . . 397 Stage page . . . . . . . . . . . . . . 445
Input page . . . . . . . . . . . . . . 397 Properties tab . . . . . . . . . . . . 445
Partitioning tab . . . . . . . . . . . . 397 Advanced tab . . . . . . . . . . . . 446
Output page . . . . . . . . . . . . . . 398 Input page . . . . . . . . . . . . . . 446
Partitioning tab . . . . . . . . . . . . 447
Chapter 35. Surrogate Key Generator Output page . . . . . . . . . . . . . . 448
stage . . . . . . . . . . . . . . . 401
Creating the key source . . . . . . . . . . 401 Chapter 40. Split Subrecord Stage 449
Deleting the key source . . . . . . . . . . 402 Examples . . . . . . . . . . . . . . . 450
Updating the state file . . . . . . . . . . 402 Must do’s . . . . . . . . . . . . . . 451
Generating surrogate keys . . . . . . . . . 402 Stage page . . . . . . . . . . . . . . 452
Properties tab . . . . . . . . . . . . 452
Chapter 36. Slowly Changing Advanced tab . . . . . . . . . . . . 452
Input page . . . . . . . . . . . . . . 452
Dimension stage . . . . . . . . . . 405 Partitioning tab . . . . . . . . . . . . 453
Job design using a Slowly Changing Dimension Output page . . . . . . . . . . . . . . 454
stage . . . . . . . . . . . . . . . . 405
Chapter 41. Combine Records stage 455
Contents vii
Examples . . . . . . . . . . . . . . . 456 Mapping tab . . . . . . . . . . . . 495
Example 1 . . . . . . . . . . . . . 456
Example 2 . . . . . . . . . . . . . 458 Chapter 46. Tail stage . . . . . . . . 497
Must do’s . . . . . . . . . . . . . . 460 Examples . . . . . . . . . . . . . . . 497
Stage page . . . . . . . . . . . . . . 460 Must do’s . . . . . . . . . . . . . . 498
Properties tab . . . . . . . . . . . . 460 Stage page . . . . . . . . . . . . . . 499
Advanced tab . . . . . . . . . . . . 461 Properties tab . . . . . . . . . . . . 499
NLS Locale tab . . . . . . . . . . . . 461 Advanced tab . . . . . . . . . . . . 499
Input page . . . . . . . . . . . . . . 462 Input page . . . . . . . . . . . . . . 500
Partitioning tab . . . . . . . . . . . . 462 Partitioning tab . . . . . . . . . . . . 500
Output page . . . . . . . . . . . . . . 463 Output page . . . . . . . . . . . . . . 501
Mapping tab . . . . . . . . . . . . 502
Chapter 42. Promote Subrecord
sStage . . . . . . . . . . . . . . 465 Chapter 47. Sample stage . . . . . . 503
Examples . . . . . . . . . . . . . . . 466 Examples . . . . . . . . . . . . . . . 504
Example 1 . . . . . . . . . . . . . 466 Sampling in percent mode . . . . . . . . 504
Example 2 . . . . . . . . . . . . . 467 Sampling in Period Mode . . . . . . . . 506
Must do’s . . . . . . . . . . . . . . 469 Must do’s . . . . . . . . . . . . . . 508
Stage page . . . . . . . . . . . . . . 469 Stage page . . . . . . . . . . . . . . 508
Properties tab . . . . . . . . . . . . 469 Properties tab . . . . . . . . . . . . 508
Advanced tab . . . . . . . . . . . . 469 Advanced tab . . . . . . . . . . . . 509
Input page . . . . . . . . . . . . . . 470 Link Ordering tab . . . . . . . . . . . 510
Partitioning tab . . . . . . . . . . . . 470 Input page . . . . . . . . . . . . . . 510
Output page . . . . . . . . . . . . . . 471 Partitioning on input links . . . . . . . . 510
Output page . . . . . . . . . . . . . . 511
Chapter 43. Make Vector stage . . . . 473 Mapping tab . . . . . . . . . . . . 512
Examples . . . . . . . . . . . . . . . 474
Example 1 . . . . . . . . . . . . . 474 Chapter 48. Peek stage . . . . . . . 513
Example 2 . . . . . . . . . . . . . 475 Must do’s . . . . . . . . . . . . . . 513
Must do’s . . . . . . . . . . . . . . 476 Stage page . . . . . . . . . . . . . . 513
Stage page . . . . . . . . . . . . . . 476 Properties tab . . . . . . . . . . . . 514
Properties tab . . . . . . . . . . . . 477 Advanced tab . . . . . . . . . . . . 515
Advanced tab . . . . . . . . . . . . 477 Link Ordering tab . . . . . . . . . . . 516
Input page . . . . . . . . . . . . . . 477 Input page . . . . . . . . . . . . . . 516
Partitioning tab . . . . . . . . . . . . 478 Partitioning tab . . . . . . . . . . . . 516
Output page . . . . . . . . . . . . . . 479 Output page . . . . . . . . . . . . . . 518
Mapping tab . . . . . . . . . . . . 518
Chapter 44. Split Vector Stage . . . . 481
Examples . . . . . . . . . . . . . . . 481 Chapter 49. Row Generator stage . . . 519
Example 1 . . . . . . . . . . . . . 482 Examples . . . . . . . . . . . . . . . 519
Example 2 . . . . . . . . . . . . . 483 Using a Row Generator Stage in Default Mode 519
Must do’s . . . . . . . . . . . . . . 484 Example of specifying data to be generated . . 520
Stage page . . . . . . . . . . . . . . 484 Example of generating data in parallel . . . . 521
Properties tab . . . . . . . . . . . . 484 Must do’s . . . . . . . . . . . . . . 523
Advanced tab . . . . . . . . . . . . 484 Stage page . . . . . . . . . . . . . . 523
Input page . . . . . . . . . . . . . . 485 Advanced tab . . . . . . . . . . . . 523
Partitioning tab . . . . . . . . . . . . 485 Output page . . . . . . . . . . . . . . 523
Output page . . . . . . . . . . . . . . 487 Properties tab . . . . . . . . . . . . 524

Chapter 45. Head stage . . . . . . . 489 Chapter 50. Column Generator stage 525
Examples . . . . . . . . . . . . . . . 489 Example . . . . . . . . . . . . . . . 525
Head stage default behavior . . . . . . . 489 Must do’s . . . . . . . . . . . . . . 527
Skipping Data . . . . . . . . . . . . 490 Stage page . . . . . . . . . . . . . . 528
Must do’s . . . . . . . . . . . . . . 491 Properties tab . . . . . . . . . . . . 528
Stage page . . . . . . . . . . . . . . 492 Advanced tab . . . . . . . . . . . . 529
Properties tab . . . . . . . . . . . . 492 Input page . . . . . . . . . . . . . . 529
Advanced tab . . . . . . . . . . . . 493 Partitioning on input links . . . . . . . . 529
Input page . . . . . . . . . . . . . . 493 Output page . . . . . . . . . . . . . . 531
Partitioning tab . . . . . . . . . . . . 493 Mapping tab . . . . . . . . . . . . 531
Output page . . . . . . . . . . . . . . 495

viii Parallel Job Developer Guide

Chapter 51. Write Range Map stage 533 The resource DB2 option . . . . . . . . . 570
Example . . . . . . . . . . . . . . . 533 The resource INFORMIX option . . . . . . . 571
Must do’s . . . . . . . . . . . . . . 534 The resource ORACLE option . . . . . . . . 572
Stage page . . . . . . . . . . . . . . 534 The SAS resources . . . . . . . . . . . . 573
Advanced tab . . . . . . . . . . . . 535 Adding SAS information to your configuration
NLS Locale tab . . . . . . . . . . . . 535 file . . . . . . . . . . . . . . . . 573
Input page . . . . . . . . . . . . . . 535 Example . . . . . . . . . . . . . . 573
Input Link Properties tab . . . . . . . . 535 Sort configuration . . . . . . . . . . . . 573
Partitioning tab . . . . . . . . . . . . 536 Allocation of resources . . . . . . . . . . 574
Selective configuration with startup scripts . . . 574
Chapter 52. Parallel jobs on USS . . . 539 Hints and tips . . . . . . . . . . . . . 575
Set up . . . . . . . . . . . . . . . . 539
Deployment options . . . . . . . . . . . 539 Chapter 55. Remote deployment . . . 579
Deploy under control of WebSphere DataStage 539 Enabling a project for job deployment . . . . . 580
Deploy standalone . . . . . . . . . . 541 Deployment package . . . . . . . . . . . 581
Implementation details . . . . . . . . . . 542 Command shell script - pxrun.sh . . . . . . 581
Directory structure . . . . . . . . . . 542 Environment variable setting source script -
Generated files . . . . . . . . . . . . 543 evdepfile . . . . . . . . . . . . . . 581
Configuration files. . . . . . . . . . . 544 Main parallel (OSH) program script -
Running jobs on the USS machine . . . . . . 544 OshScript.osh . . . . . . . . . . . . 581
Deploying and running from WebSphere Script parameter file - jpdepfile . . . . . . 581
DataStage . . . . . . . . . . . . . 544 XML report file - <jobname>.xml . . . . . . 582
Deploying from WebSphere DataStage, running Compiled transformer binary files -
manually . . . . . . . . . . . . . . 545 <jobnamestagename>.trx.so . . . . . . . 582
Deploying and running manually . . . . . 545 Self-contained transformer compilation . . . . 582
Deploying a job . . . . . . . . . . . . 582
Chapter 53. Managing data sets . . . 547 Server side plug-ins . . . . . . . . . . . 583
Structure of data sets . . . . . . . . . . . 547
Starting the data set manager . . . . . . . . 548 Appendix A. Schemas . . . . . . . . 585
Data set viewer . . . . . . . . . . . . . 548 Schema format . . . . . . . . . . . . . 585
Viewing the schema . . . . . . . . . . 548 Date columns . . . . . . . . . . . . 586
Viewing the data . . . . . . . . . . . 548 Decimal columns . . . . . . . . . . . 586
Copying data sets . . . . . . . . . . . 549 Floating-point columns . . . . . . . . . 587
Deleting data sets . . . . . . . . . . . 549 Integer columns . . . . . . . . . . . 587
Raw columns . . . . . . . . . . . . 587
Chapter 54. The Parallel engine String columns . . . . . . . . . . . . 587
Time columns . . . . . . . . . . . . 588
configuration file . . . . . . . . . . 551 Timestamp columns . . . . . . . . . . 588
Configurations editor . . . . . . . . . . . 551 Vectors . . . . . . . . . . . . . . 588
Configuration considerations . . . . . . . . 551 Subrecords . . . . . . . . . . . . . 588
Logical processing nodes . . . . . . . . 552 Tagged columns . . . . . . . . . . . 589
Optimizing parallelism . . . . . . . . . 552 Partial schemas . . . . . . . . . . . . . 590
Configuration options for an SMP . . . . . 553
Example Configuration File for an SMP . . . 555
Configuration options for an MPP system . . . 556
Appendix B. Functions . . . . . . . 593
An Example of a four-node MPP system Date and time functions . . . . . . . . . . 593
configuration . . . . . . . . . . . . 557 Logical Functions . . . . . . . . . . . . 595
Configuration options for an SMP cluster . . . 558 Mathematical Functions . . . . . . . . . . 595
An example of an SMP cluster configuration 559 Null handling functions . . . . . . . . . . 597
Options for a cluster with the conductor Number functions . . . . . . . . . . . . 598
unconnected to the high-speed switch . . . . 560 Raw functions . . . . . . . . . . . . . 598
Diagram of a cluster environment . . . . . 562 String functions . . . . . . . . . . . . 598
Configuration files. . . . . . . . . . . . 563 Vector function . . . . . . . . . . . . . 600
The default path name and the Type Conversion Functions . . . . . . . . . 601
APT_CONFIG_FILE . . . . . . . . . . 564 Type `casting’ functions . . . . . . . . . . 602
Syntax . . . . . . . . . . . . . . . 564 Utility functions . . . . . . . . . . . . 603
Node names . . . . . . . . . . . . . 565
Options . . . . . . . . . . . . . . 565 Appendix C. Fillers . . . . . . . . . 605
Node pools and the default node pool . . . . 568 Creating fillers . . . . . . . . . . . . . 605
Disk and scratch disk pools and their defaults 569 Filler creation rules . . . . . . . . . . 605
Buffer scratch disk pools . . . . . . . . 570 Filler creation examples . . . . . . . . . 606

Contents ix
Expanding fillers . . . . . . . . . . . . 611 Notices and trademarks . . . . . . . 615
Notices . . . . . . . . . . . . . . . 615
Accessing information about IBM . . 613 Trademarks . . . . . . . . . . . . . . 617
Contacting IBM . . . . . . . . . . . . 613
Accessible documentation . . . . . . . . . 613 Index . . . . . . . . . . . . . . . 619
Providing comments on the documentation . . . 614

x Parallel Job Developer Guide

Chapter 1. Introduction
This chapter gives an overview of parallel jobs. Parallel jobs are developed using the WebSphere®
DataStage® Designer and compiled and run on the WebSphere DataStage server. Such jobs commonly
connect to a data source, extract, and transform data and write it to a data warehouse.

WebSphere DataStage allows you to concentrate on designing your job sequentially, without worrying too
much about how parallel processing will be implemented. You specify the logic of the job, WebSphere
DataStage specifies the best implementation on the available hardware. If required, however, you can
exert more exact control on job implementation.

Once designed, parallel jobs can run on SMP, MPP, or cluster systems. Jobs are scaleable. The more
processors you have, the faster the job will run.

Parallel jobs can also be run on a USS system, special instructions for this are given in Chapter 52,
“Parallel jobs on USS,” on page 539.

Note: You must choose to either run parallel jobs on standard UNIX® systems or on USS systems in the
WebSphere DataStage Administrator. You cannot run both types of job at the same time. See
WebSphere DataStage Administrator Client Guide.

WebSphere DataStage also supports server jobs and mainframe jobs. Server jobs are compiled and run on
the server. These are for use on non-parallel systems and SMP systems with up to 64 processors. Server
jobs are described in WebSphere DataStage Server Job Developer Guide. Mainframe jobs are available if have
Enterprise MVS™ Edition installed. These are loaded onto a mainframe and compiled and run there.
Mainframe jobs are described in WebSphere DataStage Mainframe Job Developer Guide.

WebSphere DataStage parallel jobs

WebSphere DataStage jobs consist of individual stages. Each stage describes a particular process, this may
be accessing a database or transforming data in some way. For example, one stage may extract data from
a data source, while another transforms it. Stages are added to a job and linked together using the
Designer.

The following diagram represents one of the simplest jobs you could have: a data source, a Transformer
(conversion) stage, and the final database. The links between the stages represent the flow of data into or
out of a stage. In a parallel job each stage would correspond to a process. You can have multiple
instances of each process to run on the available processors in your system.

data transformer data

source target

© Copyright IBM Corp. 2006 1

You must specify the data you want at each stage, and how it is handled. For example, do you want all
the columns in the source data, or only a select few? Are you going to rename any of the columns? How
are they going to be transformed?

You lay down these stages and links on the canvas of the WebSphere DataStage Designer. You specify the
design as if it was sequential, WebSphere DataStage determines how the stages will become processes
and how many instances of these will actually be run.

WebSphere DataStage also allows you to store reuseable components in the Repository which can be
incorporated into different job designs. You can import these components, or entire jobs, from other
WebSphere DataStage Projects using the Designer. You can also import meta data directly from data
sources and data targets.

Guidance on how to construct your job and define the required meta data using the Designer is in the
WebSphere DataStage Designer Client Guide. Chapter 4 onwards of this manual describe the individual
stage editors that you may use when developing parallel jobs.

2 Parallel Job Developer Guide

Chapter 2. Designing parallel jobs
Parallel jobs brings the power of parallel processing to your data extraction and transformation
applications. This chapter gives a basic introduction to parallel processing, and describes some of the key
concepts in designing parallel jobs for WebSphere DataStage. If you are new to WebSphere DataStage,
you should read the introductory chapters of the WebSphere DataStage Designer Client Guide first so that
you are familiar with the WebSphere DataStage Designer client interface and the way jobs are built from
stages and links.

Parallel processing
There are two basic types of parallel processing; pipeline and partitioning. WebSphere DataStage allows
you to use both of these methods. The following sections illustrate these methods using a simple parallel
job which extracts data from a data source, transforms it in some way, then writes it to another data
source. In all cases this job would appear the same on your Designer canvas, but you can configure it to
behave in different ways (which are shown diagrammatically).

Pipeline parallelism
If you ran the example job on a system with at least three processors, the stage reading would start on
one processor and start filling a pipeline with the data it had read. The transformer stage would start
running on another processor as soon as there was data in the pipeline, process it and start filling another
pipeline. The stage writing the transformed data to the target database would similarly start writing as
soon as there was data available. Thus all three stages are operating simultaneously. If you were running
sequentially, there would only be one instance of each stage. If you were running in parallel, there would
be as many instances as you had partitions (see next section).

© Copyright IBM Corp. 2006 3

 time taken

conceptual representation of job running with no parallelism

time taken

conceptual representation of same job using pipeline parallelism

Partition parallelism
Imagine you have the same simple job as described above, but that it is handling very large quantities of
data. In this scenario you could use the power of parallel processing to your best advantage by
partitioning the data into a number of separate sets, with each partition being handled by a separate
instance of the job stages.

Using partition parallelism the same job would effectively be run simultaneously by several processors,
each handling a separate subset of the total data.

At the end of the job the data partitions can be collected back together again and written to a single data
source.

4 Parallel Job Developer Guide

 Conceptual representation of job using partition parallelism

Combining pipeline and partition parallelism

In practice you will be combining pipeline and partition parallel processing to achieve even greater
performance gains. In this scenario you would have stages processing partitioned data and filling
pipelines so the next one could start on that partition before the previous one had finished.

Conceptual representation of job using pipeline and partition parallelism

Repartitioning data
In some circumstances you may want to actually repartition your data between stages. This might
happen, for example, where you want to group data differently. Say you have initially processed data
based on customer last name, but now want to process on data grouped by zip code. You will need to
repartition to ensure that all customers sharing the same zip code are in the same group. WebSphere

Chapter 2. Designing parallel jobs 5

DataStage allows you to repartition between stages as and when needed (although note there are
performance implications if you do this and you may affect the balance of your partitions – see Parallel
Job Advanced Developer Guide).

Conceptual representation of data repartitioning

Further details about how WebSphere DataStage actually partitions data, and collects it together again, is
given in ″Partitioning, Repartitioning, and Collecting Data″.

Parallel processing environments

The environment in which you run your parallel jobs is defined by your system’s architecture and
hardware resources. All parallel processing environments are categorized as one of:
v SMP (symmetric multiprocessing), in which some hardware resources may be shared among
processors. The processors communicate via shared memory and have a single operating system.
v Cluster or MPP (massively parallel processing), also known as shared-nothing, in which each processor
has exclusive access to hardware resources. MPP systems are physically housed in the same box,
whereas cluster systems can be physically dispersed. The processors each have their own operating
system, and communicate via a high-speed network.

SMP systems allow you to scale up the number of processors, which may improve performance of your
jobs. The improvement gained depends on how your job is limited:
v CPU-limited jobs. In these jobs the memory, memory bus, and disk I/O spend a disproportionate
amount of time waiting for the processor to finish its work. Running a CPU-limited application on
more processors can shorten this waiting time so speed up overall performance.

6 Parallel Job Developer Guide

v Memory-limited jobs. In these jobs CPU and disk I/O wait for the memory or the memory bus. SMP
systems share memory resources, so it may be harder to improve performance on SMP systems
without hardware upgrade.
v Disk I/O limited jobs. In these jobs CPU, memory and memory bus wait for disk I/O operations to
complete. Some SMP systems allow scalability of disk I/O, so that throughput improves as the number
of processors increases. A number of factors contribute to the I/O scalability of an SMP, including the
number of disk spindles, the presence or absence of RAID, and the number of I/O controllers.

In a cluster or MPP environment, you can use the multiple processors and their associated memory and
disk resources in concert to tackle a single job. In this environment, each processor has its own dedicated
memory, memory bus, disk, and disk access. In a shared-nothing environment, parallelization of your job
is likely to improve the performance of CPU-limited, memory-limited, or disk I/O-limited applications.

The configuration file

One of the great strengths of the WebSphere DataStage Enterprise Edition is that, when designing jobs,
you don’t have to worry too much about the underlying structure of your system, beyond appreciating
its parallel processing capabilities. If your system changes, is upgraded or improved, or if you develop a
job on one platform and implement it on another, you don’t necessarily have to change your job design.

WebSphere DataStage learns about the shape and size of the system from the configuration file. It
organizes the resources needed for a job according to what is defined in the configuration file. When
your system changes, you change the file not the jobs.

The configuration file describes available processing power in terms of processing nodes. These may, or
may not, correspond to the actual number of processors in your system. You may, for example, want to
always leave a couple of processors free to deal with other activities on your system. The number of
nodes you define in the configuration file determines how many instances of a process will be produced
when you compile a parallel job.

Every MPP, cluster, or SMP environment has characteristics that define the system overall as well as the
individual processors. These characteristics include node names, disk storage locations, and other
distinguishing attributes. For example, certain processors might have a direct connection to a mainframe
for performing high-speed data transfers, while others have access to a tape drive, and still others are
dedicated to running an RDBMS application. You can use the configuration file to set up node pools and
resource pools. A pool defines a group of related nodes or resources, and when you design a parallel job
you can specify that execution be confined to a particular pool.

The configuration file describes every processing node that WebSphere DataStage will use to run your
application. When you run a parallel job, WebSphere DataStage first reads the configuration file to
determine the available system resources.

When you modify your system by adding or removing processing nodes or by reconfiguring nodes, you
do not need to alter or even recompile your parallel job. Just edit the configuration file.

The configuration file also gives you control over parallelization of your job during the development
cycle. For example, by editing the configuration file, you can first run your job on a single processing
node, then on two nodes, then four, then eight, and so on. The configuration file lets you measure system
performance and scalability without actually modifying your job.

You can define and edit the configuration file using the Designer client.

Chapter 2. Designing parallel jobs 7

Partitioning, repartitioning, and collecting data
We have already described how you can use partitioning of data to implement parallel processing in your
job . This section takes a closer look at how you can partition data in your jobs, and collect it together
again.

Partitioning
In the simplest scenario you probably won’t be bothered how your data is partitioned. It is enough that it
is partitioned and that the job runs faster. In these circumstances you can safely delegate responsibility
for partitioning to WebSphere DataStage. Once you have identified where you want to partition data,
WebSphere DataStage will work out the best method for doing it and implement it.

The aim of most partitioning operations is to end up with a set of partitions that are as near equal size as
possible, ensuring an even load across your processors.

When performing some operations however, you will need to take control of partitioning to ensure that
you get consistent results. A good example of this would be where you are using an aggregator stage to
summarize your data. To get the answers you want (and need) you must ensure that related data is
grouped together in the same partition before the summary operation is performed on that partition.
WebSphere DataStage lets you do this.

There are a number of different partitioning methods available, note that all these descriptions assume
you are starting with sequential data. If you are repartitioning already partitioned data then there are
some specific considerations:

Round robin partitioner

The first record goes to the first processing node, the second to the second processing node, and so on.
When WebSphere DataStage reaches the last processing node in the system, it starts over. This method is
useful for resizing partitions of an input data set that are not equal in size. The round robin method
always creates approximately equal-sized partitions. This method is the one normally used when
WebSphere DataStage initially partitions data.

8 Parallel Job Developer Guide

 Round Robin 1
Partioner 5
9

13

Node 1
1

2
3

4 2
5
6
6 10
7 14
8
9 Node 2
10
11

12 3
13
7
14 11
15
15
16
Node 3
Input data

4
8
12

16

Node 4

Random partitioner
Records are randomly distributed across all processing nodes. Like round robin, random partitioning can
rebalance the partitions of an input data set to guarantee that each processing node receives an
approximately equal-sized partition. The random partitioning has a slightly higher overhead than round
robin because of the extra processing required to calculate a random value for each record.

Chapter 2. Designing parallel jobs 9

 Random 2
Partioner 5
15

14

Node 1
1

2
3

4 9
5
6
6 10
7 13
8
9 Node 2
10
11

12 1
13
7
14 11
15
3
16
Node 3
Input data

8
4
4

16

Node 4

Same partitioner
The stage using the data set as input performs no repartitioning and takes as input the partitions output
by the preceding stage. With this partitioning method, records stay on the same processing node; that is,
they are not redistributed. Same is the fastest partitioning method. This is normally the method
WebSphere DataStage uses when passing data between stages in your job.

10 Parallel Job Developer Guide

 1 1

5 5
9 9

13 13

Node 1 Node 1

2 2
6 6
10 10
14 14

Node 2 Node 2

3 3

7 7
11 11

15 15

Node 3 Node 3

4 4
8 8
12 12

16 16

Node 4 Same Node 4

Partioner

Entire partitioner
Every instance of a stage on every processing node receives the complete data set as input. It is useful
when you want the benefits of parallel execution, but every instance of the operator needs access to the
entire input data set. You are most likely to use this partitioning method with stages that create lookup
tables from their input.

Chapter 2. Designing parallel jobs 11

 1
Entire
2
Partioner
3

4
5
Node 1

2
3

4
1
5
2
Node 2
3

4
5 1

2
3

4
5
Node 3
Input data

2
3

4
5
Node 4

Hash partitioner
Partitioning is based on a function of one or more columns (the hash partitioning keys) in each record.
The hash partitioner examines one or more fields of each input record (the hash key fields). Records with
the same values for all hash key fields are assigned to the same processing node.

This method is useful for ensuring that related records are in the same partition, which may be a
prerequisite for a processing operation. For example, for a remove duplicates operation, you can hash
partition records so that records with the same partitioning key values are on the same node. You can
then sort the records on each node using the hash key fields as sorting key fields, then remove

12 Parallel Job Developer Guide

duplicates, again using the same keys. Although the data is distributed across partitions, the hash
partitioner ensures that records with identical keys are in the same partition, allowing duplicates to be
found.

Hash partitioning does not necessarily result in an even distribution of data between partitions. For
example, if you hash partition a data set based on a zip code field, where a large percentage of your
records are from one or two zip codes, you can end up with a few partitions containing most of your
records. This behavior can lead to bottlenecks because some nodes are required to process more records
than other nodes.

For example, the diagram shows the possible results of hash partitioning a data set using the field age as
the partitioning key. Each record with a given age is assigned to the same partition, so for example
records with age 36, 40, or 22 are assigned to partition 0. The height of each bar represents the number of
records in the partition.

Age values

10 54 17

12 18 27

Partition size
(in records)
35 5 60

36 40 22

15 44 39

…
0 1 2 3 N

Partition number

As you can see, the key values are randomly distributed among the different partitions. The partition
sizes resulting from a hash partitioner are dependent on the distribution of records in the data set so even
though there are three keys per partition, the number of records per partition varies widely, because the
distribution of ages in the population is non-uniform.

When hash partitioning, you should select hashing keys that create a large number of partitions. For
example, hashing by the first two digits of a zip code produces a maximum of 100 partitions. This is not
a large number for a parallel processing system. Instead, you could hash by five digits of the zip code to
create up to 10,000 partitions. You also could combine a zip code hash with an age hash (assuming a
maximum age of 190), to yield 1,500,000 possible partitions.

Chapter 2. Designing parallel jobs 13

Fields that can only assume two values, such as yes/no, true/false, male/female, are particularly poor
choices as hash keys.

You must define a single primary partitioning key for the hash partitioner, and you may define as many
secondary keys as are required by your job. Note, however, that each column can be used only once as a
key. Therefore, the total number of primary and secondary keys must be less than or equal to the total
number of columns in the row.

You specify which columns are to act as hash keys on the Partitioning tab of the stage editor The data
type of a partitioning key may be any data type except raw, subrecord, tagged aggregate, or vector. By
default, the hash partitioner does case-sensitive comparison. This means that uppercase strings appear
before lowercase strings in a partitioned data set. You can override this default if you want to perform
case insensitive partitioning on string fields.

Modulus partitioner
Partitioning is based on a key column modulo the number of partitions. This method is similar to hash
by field, but involves simpler computation.

In data mining, data is often arranged in buckets, that is, each record has a tag containing its bucket
number. You can use the modulus partitioner to partition the records according to this number. The
modulus partitioner assigns each record of an input data set to a partition of its output data set as
determined by a specified key field in the input data set. This field can be the tag field.

The partition number of each record is calculated as follows:

partition_number = fieldname mod number_of_partitions

where:
v fieldname is a numeric field of the input data set.
v number_of_partitions is the number of processing nodes on which the partitioner executes. If a
partitioner is executed on three processing nodes it has three partitions.

In this example, the modulus partitioner partitions a data set containing ten records. Four processing
nodes run the partitioner, and the modulus partitioner divides the data among four partitions. The input
data is as follows:

Column name SQL type

bucket Integer
date Date

The bucket is specified as the key field, on which the modulus operation is calculated.

Here is the input data set. Each line represents a row:

bucket date
64123 1960-03-30
61821 1960-06-27
44919 1961-06-18
22677 1960-09-24
90746 1961-09-15
21870 1960-01-01
87702 1960-12-22

14 Parallel Job Developer Guide

bucket date
4705 1961-12-13
47330 1961-03-21
88193 1962-03-12

The following table shows the output data set divided among four partitions by the modulus partitioner.

Partition 0 Partition 1 Partition 2 Partition 3

61821 1960-06-27 21870 1960-01-01 64123 1960-03-30
22677 1960-09-24 87702 1960-12-22 44919 1961-06-18
47051961-12-13 47330 1961-03-21
88193 1962-03-12 90746 1961-09-15

Here are three sample modulus operations corresponding to the values of three of the key fields:
v 22677 mod 4 = 1; the data is written to Partition 1.
v 47330 mod 4 = 2; the data is written to Partition 2.
v 64123 mod 4 = 3; the data is written to Partition 3.

None of the key fields can be divided evenly by 4, so no data is written to Partition 0.

Range partitioner
Divides a data set into approximately equal-sized partitions, each of which contains records with key
columns within a specified range. This method is also useful for ensuring that related records are in the
same partition.

A range partitioner divides a data set into approximately equal size partitions based on one or more
partitioning keys. Range partitioning is often a preprocessing step to performing a total sort on a data set.

In order to use a range partitioner, you have to make a range map. You can do this using the Write
Range Map stage, which is described in Chapter 55.

The range partitioner guarantees that all records with the same partitioning key values are assigned to
the same partition and that the partitions are approximately equal in size so all nodes perform an equal
amount of work when processing the data set.

An example of the results of a range partition is shown below. The partitioning is based on the age key,
and the age range for each partition is indicated by the numbers in each bar. The height of the bar shows
the size of the partition.

Chapter 2. Designing parallel jobs 15

 Age values

Partition size 26-44

0-2 3-17 18-25 66-71
(in records)

Partition

All partitions are of approximately the same size. In an ideal distribution, every partition would be
exactly the same size.

However, you typically observe small differences in partition size. In order to size the partitions, the
range partitioner uses a range map to calculate partition boundaries. As shown above, the distribution of
partitioning keys is often not even; that is, some partitions contain many partitioning keys, and others
contain relatively few. However, based on the calculated partition boundaries, the number of records in
each partition is approximately the same.

Range partitioning is not the only partitioning method that guarantees equivalent-sized partitions. The
random and round robin partitioning methods also guarantee that the partitions of a data set are
equivalent in size. However, these partitioning methods are keyless; that is, they do not allow you to
control how records of a data set are grouped together within a partition.

In order to perform range partitioning your job requires a write range map stage to calculate the range
partition boundaries in addition to the stage that actually uses the range partitioner. The write range map
stage uses a probabilistic splitting technique to range partition a data set. This technique is described in
Parallel Sorting on a Shared- Nothing Architecture Using Probabilistic Splitting by DeWitt, Naughton, and
Schneider in Query Processing in Parallel Relational Database Systems by Lu, Ooi, and Tan, IEEE Computer
Society Press, 1994. In order for the stage to determine the partition boundaries, you pass it a sorted
sample of the data set to be range partitioned. From this sample, the stage can determine the appropriate
partition boundaries for the entire data set.

When you come to actually partition your data, you specify the range map to be used by clicking on the
property icon, next to the Partition type field, the Partitioning/Collection properties dialog box appears
and allows you to specify a range map.

DB2 partitioner
Partitions an input data set in the same way that DB2® would partition it. For example, if you use this
method to partition an input data set containing update information for an existing DB2 table, records are
assigned to the processing node containing the corresponding DB2 record. Then, during the execution of
the parallel operator, both the input record and the DB2 table record are local to the processing node.
Any reads and writes of the DB2 table would entail no network activity.

See theDB2 Parallel Edition for AIX®, Administration Guide and Reference for more information on DB2
partitioning.

16 Parallel Job Developer Guide

To use DB2 partitioning on a stage, select a Partition type of DB2 on the Partitioning tab, then click the
Properties button to the right. In the Partitioning/Collection properties dialog box, specify the details of
the DB2 table whose partitioning you want to replicate ).

Auto partitioner
The most common method you will see on the WebSphere DataStage stages is Auto. This just means that
you are leaving it to WebSphere DataStage to determine the best partitioning method to use depending
on the type of stage, and what the previous stage in the job has done. Typically WebSphere DataStage
would use round robin when initially partitioning data, and same for the intermediate stages of a job.

Collecting
Collecting is the process of joining the multiple partitions of a single data set back together again into a
single partition. There are various situations where you may want to do this. There may be a stage in
your job that you want to run sequentially rather than in parallel, in which case you will need to collect
all your partitioned data at this stage to make sure it is operating on the whole data set.

Similarly, at the end of a job, you might want to write all your data to a single database, in which case
you need to collect it before you write it.

There might be other cases where you do not want to collect the data at all. For example, you may want
to write each partition to a separate flat file.

Just as for partitioning, in many situations you can leave DataStage to work out the best collecting
method to use. There are situations, however, where you will want to explicitly specify the collection
method.

Note that collecting methods are mostly non-deterministic. That is, if you run the same job twice with the
same data, you are unlikely to get data collected in the same order each time. If order matters, you need
to use the sorted merge collection method.

Round robin collector

Reads a record from the first input partition, then from the second partition, and so on. After reaching
the last partition, starts over. After reaching the final record in any partition, skips that partition in the
remaining rounds.

Chapter 2. Designing parallel jobs 17

 1 Round Robin
2
Collector
3

Node 1
1

5
9
5 13
6 2

7 6
8 10
14
Node 2 3

7
11
9 15
10 4

11 8
12
12
16
Node 3
Input data

13
14
15
16

Node 4

Ordered collector
Reads all records from the first partition, then all records from the second partition, and so on. This
collection method preserves the order of totally sorted input data sets. In a totally sorted data set, both
the records in each partition and the partitions themselves are ordered. This may be useful as a
preprocessing action before exporting a sorted data set to a single data file.

18 Parallel Job Developer Guide

 1 Ordered
2
Collector
3

Node 1
1

2
3

5 4

6 5

7 6
8 7
8
Node 2 9
10
11

9 12

10 13
11 14

12 15
16
Node 3
Input data

13
14
15
16

Node 4

Sorted merge collector

Read records in an order based on one or more columns of the record. The columns used to define record
order are called collecting keys. Typically, you use the sorted merge collector with a partition-sorted data
set (as created by a sort stage). In this case, you specify as the collecting key fields those fields you
specified as sorting key fields to the sort stage. For example, the figure below shows the current record in
each of three partitions of an input data set to the collector:

Chapter 2. Designing parallel jobs 19

 Partition 0 Partition 1 Partition 2

“Jane” “Smith” 42 “Paul” “Smith” 34 “Mary” “Davis” 42

Current record

In this example, the records consist of three fields. The first-name and last-name fields are strings, and
the age field is an integer. The following figure shows the order of the three records read by the sort
merge collector, based on different combinations of collecting keys.

order read:

1 “Jane” “Smith” 42

2 “Mary” “Davis” 42

3 “Paul” “Smith” 34

primary collecting key

order read:

1 “Paul” “Smith” 34

2 “Mary” “Davis” 42

3 “Jane” “Smith” 42

secondary collecting key

primary collecting key

order read:

1 “Jane” “Smith” 42

2 “Paul” “Smith” 34

3 “Mary” “Davis” 42

secondary collecting key

20 Parallel Job Developer Guide

You must define a single primary collecting key for the sort merge collector, and you may define as many
secondary keys as are required by your job. Note, however, that each column can be used only once as a
collecting key. Therefore, the total number of primary and secondary collecting keys must be less than or
equal to the total number of columns in the row. You define the keys on the Partitioning tab, and the key
you define first is the primary key.

The data type of a collecting key can be any type except raw, subrec, tagged, or vector.

By default, the sort merge collector uses ascending sort order and case-sensitive comparisons. Ascending
order means that records with smaller values for a collecting field are processed before records with
larger values. You also can specify descending sorting order, so records with larger values are processed
first.

With a case-sensitive algorithm, records with uppercase strings are processed before records with
lowercase strings. You can override this default to perform case-insensitive comparisons of string fields.

Auto collector
The most common method you will see on the parallel stages is Auto. This normally means that
WebSphere DataStage will eagerly read any row from any input partition as it becomes available, but if it
detects that, for example, the data needs sorting as it is collected, it will do that. This is the fastest
collecting method.

Repartitioning data
If you decide you need to repartition data within your parallel job there are some particular
considerations as repartitioning can affect the balance of data partitions.

For example, if you start with four perfectly balanced partitions and then subsequently repartition into
three partitions, you will lose the perfect balance and be left with, at best, near perfect balance. This is
true even for the round robin method; this only produces perfectly balanced partitions from a sequential
data source. The reason for this is illustrated below. Each node partitions as if it were a single processor
with a single data set, and will always start writing to the first target partition. In the case of four
partitions repartitioning to three, more rows are written to the first target partition. With a very small
data set the effect is pronounced; with a large data set the partitions tend to be more balanced.

Chapter 2. Designing parallel jobs 21

 Data repartitioned from four
partitions to three partitions

The mechanics of partitioning and collecting

This section gives a quick guide to how partitioning and collecting is represented in a parallel job.

Partitioning icons
Each parallel stage in a job can partition or repartition incoming data before it operates on it. Equally it
can just accept the partitions that the data comes in. There is an icon on the input link to a stage which
shows how the stage handles partitioning.

22 Parallel Job Developer Guide

In most cases, if you just lay down a series of parallel stages in a DataStage job and join them together,
the auto method will determine partitioning. This is shown on the canvas by the auto partitioning icon:

In some cases, stages have a specific partitioning method associated with them that cannot be overridden.
It always uses this method to organize incoming data before it processes it. In this case an icon on the
input link tells you that the stage is repartitioning data:

If you have a data link from a stage running sequentially to one running in parallel the following icon is
shown to indicate that the data is being partitioned:

You can specify that you want to accept the existing data partitions by choosing a partitioning method of
same. This is shown by the following icon on the input link:

Partitioning methods are set on the Partitioning tab of the Inputs pages on a stage editor.

Preserve partitioning flag

A stage can also request that the next stage in the job preserves whatever partitioning it has
implemented. It does this by setting the preserve partitioning flag for its output link. Note, however, that
the next stage may ignore this request.

In most cases you are best leaving the preserve partitioning flag in its default state. The exception to this
is where preserving existing partitioning is important. The flag will not prevent repartitioning, but it will
warn you that it has happened when you run the job. If the Preserve Partitioning flag is cleared, this
means that the current stage doesn’t care what the next stage in the job does about partitioning. On some

Chapter 2. Designing parallel jobs 23

stages, the Preserve Partitioning flag can be set to Propagate. In this case the stage sets the flag on its
output link according to what the previous stage in the job has set. If the previous job is also set to
Propagate, the setting from the stage before is used and so on until a Set or Clear flag is encountered
earlier in the job. If the stage has multiple inputs and has a flag set to Propagate, its Preserve Partitioning
flag is set if it is set on any of the inputs, or cleared if all the inputs are clear.

Collector icon
A stage in the job which is set to run sequentially will need to collect partitioned data before it operates
on it. There is an icon on the input link to a stage which shows that it is collecting data:

Sorting data
You will probably have requirements in your parallel jobs to sort data. WebSphere DataStage has a sort
stage, which allows you to perform complex sorting operations. There are situations, however, where you
require a fairly simple sort as a precursor to a processing operation. For these purposes, WebSphere
DataStage allows you to insert a sort operation in most stage types for incoming data. You do this by
selecting the Sorting option on the Input page Partitioning tab . When you do this you can specify:
v Sorting keys. The field(s) on which data is sorted. You must specify a primary key, but you can also
specify any number of secondary keys. The first key you define is taken as the primary.
v Stable sort (this is the default and specifies that previously sorted data sets are preserved).
v Unique sort (discards records if multiple records have identical sorting key values).
v Case sensitivity.
v Sort direction. Sorted as EBCDIC (ASCII is the default).

If you have NLS enabled, you can also specify the collate convention used.

Some WebSphere DataStage operations require that the data they process is sorted (for example, the
Merge operation). If WebSphere DataStage detects that the input data set is not sorted in such a case, it
will automatically insert a sort operation in order to enable the processing to take place unless you have
explicitly specified otherwise.

Data sets
Inside a WebSphere DataStage parallel job, data is moved around in data sets. These carry meta data with
them, both column definitions and information about the configuration that was in effect when the data
set was created. If for example, you have a stage which limits execution to a subset of available nodes,
and the data set was created by a stage using all nodes, WebSphere DataStage can detect that the data
will need repartitioning.

If required, data sets can be landed as persistent data sets, represented by a Data Set stage (see Chapter 4,
“Data set stage,” on page 67, ″Data Set Stage.″) This is the most efficient way of moving data between
linked jobs. Persistent data sets are stored in a series of files linked by a control file (note that you should
not attempt to manipulate these files using UNIX tools such as RM or MV. Always use the tools provided
with WebSphere DataStage).

24 Parallel Job Developer Guide

Note: The example screenshots in the individual stage descriptions often show the stage connected to a
Data Set stage. This does not mean that these kinds of stage can only be connected to Data Set
stages.

Metadata
Metadata is information about data. It describes the data flowing through your job in terms of column
definitions, which describe each of the fields making up a data record.

WebSphere DataStage has two alternative ways of handling metadata, through table definitions, or
through Schema files. By default, parallel stages derive their meta data from the columns defined on the
Outputs or Input page Column tab of your stage editor. Additional formatting information is supplied,
where needed, by a Formats tab on the Outputs or Input page. In some cases you can specify that the
stage uses a schema file instead by explicitly setting a property on the stage editor and specify the name
and location of the schema file. Note that, if you use a schema file, you should ensure that runtime
column propagation is turned on. Otherwise the column definitions specified in the stage editor will
always override any schema file.

Where is additional formatting information needed? Typically this is where you are reading from, or
writing to, a file of some sort and WebSphere DataStage needs to know more about how data in the file
is formatted.

You can specify formatting information on a row basis, where the information is applied to every column
in every row in the dataset. This is done from the Formats tab (the Formats tab is described with the
stage editors that support it; for example, for Sequential files, see page Input Link Format Tab). You can
also specify formatting for particular columns (which overrides the row formatting) from the Edit
Column Metadata dialog box for each column (see page Field Level).

Runtime column propagation

WebSphere DataStage is also flexible about meta data. It can cope with the situation where meta data
isn’t fully defined. You can define part of your schema and specify that, if your job encounters extra
columns that are not defined in the meta data when it actually runs, it will adopt these extra columns
and propagate them through the rest of the job. This is known as runtime column propagation (RCP).
This can be enabled for a project via the WebSphere DataStage Administrator (see WebSphere DataStage
Administrator Client Guide), and set for individual links via the Output Page Columns tab (see ″Columns
Tab″ on page Columns Tab) for most stages, or in the Output page General tab for Transformer stages
(see ″Output Page″ ). You should always ensure that runtime column propagation is turned on if you
want to use schema files to define column meta data.

Table definitions
A table definition is a set of related columns definitions that are stored in the Repository. These can be
loaded into stages as and when required.

You can import a table definition from a data source via the Designer. You can also edit and define new
table definitions in the Designer (see WebSphere DataStage Designer Client Guide). If you want, you can edit
individual column definitions once you have loaded them into your stage.

You can also simply type in your own column definition from scratch on the Outputs or Input page
Column tab of your stage editor. When you have entered a set of column definitions you can save them
as a new table definition in the Repository for subsequent reuse in another job.

Chapter 2. Designing parallel jobs 25

Schema files and partial schemas
You can also specify the meta data for a stage in a plain text file known as a schema file. This is not
stored in the Repository but you could, for example, keep it in a document management or source code
control system, or publish it on an intranet site.

The format of schema files is described in Appendix A of this manual.

Note: If you are using a schema file on an NLS system, the schema file needs to be in UTF-8 format. It is,
however, easy to convert text files between two different maps with a WebSphere DataStage job.
Such a job would read data from a text file using a Sequential File stage and specifying the
appropriate character set on the NLS Map page. It would write the data to another file using a
Sequential File stage, specifying the UTF-8 map on the NLS Map page.

Some parallel job stages allow you to use a partial schema. This means that you only need define column
definitions for those columns that you are actually going to operate on. Partial schemas are also described
in Appendix A.

Remember that you should turn runtime column propagation on if you intend to use schema files to
define column meta data.

Data types
When you work with parallel job column definitions, you will see that they have an SQL type associated
with them. This maps onto an underlying data type which you use when specifying a schema via a file,
and which you can view in the Parallel tab of the Edit Column Meta Data dialog box. The underlying
data type is what a parallel job data set understands. The following table summarizes the underlying
data types that columns definitions can have:

SQL Type Underlying Data Type Size Description

Date date 4 bytes Date with month, day, and
year
Decimal Numeric decimal (Roundup(p)+1)/2 Packed decimal, compatible
with IBM® packed decimal
format
Float Real sfloat 4 bytes IEEE single-precision
(32-bit) floating point value
Double dfloat 8 bytes IEEE double-precision
(64-bit) floating point value
TinyInt int8 uint8 1 byte Signed or unsigned integer
of 8 bits (Extended
(unsigned) option for
unsigned)
SmallInt int16 uint16 2 bytes Signed or unsigned integer
of 16 bits (Extended
(unsigned) option for
unsigned)
Integer int32 uint32 4 bytes Signed or unsigned integer
of 32 bits (Extended
(unsigned) option for
unsigned)
BigInt1 int64 uint64 8 bytes Signed or unsigned integer
of 64 bits (Extended
(unsigned) option for
unsigned)

26 Parallel Job Developer Guide

SQL Type Underlying Data Type Size Description
Binary Bit LongVarBinary raw 1 byte per character Untypes collection,
VarBinary consisting of a fixed or
variable number of
contiguous bytes and an
optional alignment value
Unknown Char string 1 byte per character ASCII character string of
LongVarChar VarChar fixed or variable length
(without the
extended(Unicode) option
selected)
NChar NVarChar ustring multiple bytes per character ASCII character string of
LongNVarChar fixed or variable length
(without the
extended(Unicode) option
selected)
Char LongVarChar VarChar ustring multiple bytes per character ASCII character string of
fixed or variable length
(with the
extended(Unicode) option
selected)
Char subrec sum of lengths of subrecord Complex data type
fields comprising nested columns
Char tagged sum of lengths of subrecord Complex data type
fields comprising tagged
columns, of which one can
be referenced when the
column is used
Time time 5 bytes Time of day, with
resolution of seconds.
Time time(microseconds) 5 bytes Time of day, with
resolution of microseconds
(Extended (Microseconds)
option selected).
Timestamp timestamp 9 bytes Single field containing both
data and time value
Timestamp timestamp(microseconds) 9 bytes Single field containing both
data and time value, with
resolution of microseconds
(Extended (Microseconds)
option selected).

Chapter 2. Designing parallel jobs 27

1
BigInt values map to long long integers on all supported platforms except Tru64 where they map to longer
integers. For all platforms except Tru64, the c_format is:

’%[padding_character][integer]lld’

Because Tru64 supports real 64-bit integers, its c_format is:

%[padding_character][integer]ld’

The integer component specifies a minimum field width. The output column is printed at least this wide, and wider
if necessary. If the column has fewer digits than the field width, it is padded on the left with padding_character to
make up the field width. The default padding character is a space.

For this example c_format specification: ’%09lld’ the padding character is zero (0), and the integers 123456 and
12345678 are printed out as 000123456 and 123456789.

When you work with mainframe data using the CFF stage, the data types are as follows:

Underlying Data
COBOL Data Type Type
binary, native binary 2 bytes S9(1-4) int16
COMP/COMP-5
binary, native binary 4 bytes S9(5-9) int32
COMP/COMP-5
binary, native binary 8 bytes S9(10-18) int64
COMP/COMP-5
binary, native binary 2 bytes 9(1-4) uint16
COMP/COMP-5
binary, native binary 4 bytes 9(5-9) uint32
COMP/COMP-5
binary, native binary 8 bytes 9(10-18) uint64
COMP/COMP-5
character n bytes X(n) string[n]
character for filler n bytes X(n) raw(n)
varchar n bytes X(n) string[max=n]
decimal (x+y)/2+1 bytes 9(x)V9(y)COMP-3 decimal[x+y,y] packed
decimal (x+y)/2+1 bytes S9(x)V9(y)COMP-3 decimal[x+y,y] packed
display_numeric x+y bytes 9(x)V9(y) decimal[x+y,y] or zoned
string[x+y]
display_numeric x+y bytes S9(x)V9(y) decimal[x+y,y] or zoned, trailing
string[x+y]
display_numeric x+y bytes S9(x)V9(y) sign is decimal[x+y,y] zoned, trailing
trailing
display_numeric x+y bytes S9(x)V9(y) sign is decimal[x+y,y] zoned, leading
leading
display_numeric x+y+1 bytes S9(x)V9(y) sign is decimal[x+y,y] separate, trailing
trailing separate
display_numeric x+y+1 bytes S9(x)V9(y) sign is decimal[x+y,y] separate, leading
leading separate
float 4 bytes 8 bytes COMP-1 COMP-2 sfloat dfloat floating point

28 Parallel Job Developer Guide

 Underlying Data
COBOL Data Type Type
graphic_n, graphic_g n*2 bytes N(n) or G(n) ustring[n]
DISPLAY-1
vargraphic_g/n n*2 bytes N(n) or G(n) ustring[max=n]
DISPLAY-1
group subrec

Strings and ustrings

If you have NLS enabled, parallel jobs support two types of underlying character data types: strings and
ustrings. String data represents unmapped bytes, ustring data represents full Unicode (UTF-16) data.

The Char, VarChar, and LongVarChar SQL types relate to underlying string types where each character is
8-bits and does not require mapping because it represents an ASCII character. You can, however, specify
that these data types are extended, in which case they are taken as ustrings and do require mapping.
(They are specified as such by selecting the Extended check box for the column in the Edit Meta Data
dialog box.) An Extended field appears in the columns grid, and extended Char, VarChar, or
LongVarChar columns have `Unicode’ in this field. The NChar, NVarChar, and LongNVarChar types
relate to underlying ustring types so do not need to be explicitly extended.

Complex data types

Parallel jobs support three complex data types:
v Subrecords
v Tagged subrecords
v Vectors

When referring to complex data in WebSphere DataStage column definitions, you can specify fully
qualified column names, for example:
Parent.Child5.Grandchild2

Subrecords
A subrecord is a nested data structure. The column with type subrecord does not itself define any
storage, but the columns it contains do. These columns can have any data type, and you can nest
subrecords one within another. The LEVEL property is used to specify the structure of subrecords. The
following diagram gives an example of a subrecord structure.

Parent (subrecord)
Child1 (string)
Child2 (string)
Child3 (string) LEVEL01
Child4 (string)
Child5(subrecord)
Grandchild1 (string)
Grandchild2 (time) LEVEL02
Grandchild3 (sfloat)

Chapter 2. Designing parallel jobs 29

Tagged subrecord
This is a special type of subrecord structure, it comprises a number of columns of different types and the
actual column is ONE of these, as indicated by the value of a tag at run time. The columns can be of any
type except subrecord or tagged. The following diagram illustrates a tagged subrecord.

Parent (tagged)
Child1 (string)
Child2 (int8)
Child3 (raw)

Tag = Child1, so column has data type of string

Vector
A vector is a one dimensional array of any type except tagged. All the elements of a vector are of the
same type, and are numbered from 0. The vector can be of fixed or variable length. For fixed length
vectors the length is explicitly stated, for variable length ones a property defines a link field which gives
the length at run time. The following diagram illustrates a vector of fixed length and one of variable
length.

Fixed length

int32 int32 int32 int32 int32 int32 int32 int32 int32

0 1 2 3 4 5 6 7 8

Variable length

int32 int32 int32 int32 int32 int32 int32 int32

0 1 2 3 4 5 6 N

link field = N

Date and time formats

Parallel jobs provide flexible handling of date and time formats.

You use formatting strings at various places in parallel jobs to specify the format of dates, times, and
timestamps.

Date formats
Format strings are used to control the format of dates.

A date format string can contain one or a combination of the following elements:
Table 1. Date format tags
Variable width
Tag availability Description Value range Options
%d import Day of month, 1...31 s
variable width
%dd Day of month, fixed 01...31 s
width

30 Parallel Job Developer Guide

Table 1. Date format tags (continued)
Variable width
Tag availability Description Value range Options
%ddd with v option Day of year 1...366 s, v
%m import Month of year, 1...12 s
variable width
%mm Month of year, fixed 01...12 s
width
%mmm Month of year, short Jan, Feb ... t, u, w
name, locale specific
%mmmm import/export Month of year, full January, February ... t, u, w, -N, +N
name, locale specific
%yy Year of century 00...99 s
%yyyy Four digit year 0001 ...9999
%NNNNyy Cutoff year plus year yy = 00...99 s
of century
%e Day of week, Sunday 1...7
= day 1
%E Day of week, 1...7
Monday = day 1
%eee Weekday short name, Sun, Mon ... t, u, w
locale specific
%eeee import/export Weekday long name, Sunday, Monday ... t, u, w, -N, +N
locale specific
%W import Week of year (ISO 1...53 s
8601, Mon)
%WW Week of year (ISO 01...53 s
8601, Mon)

When you specify a date format string, prefix each component with the percent symbol (%). Separate the
string’s components with a literal character.

The default date format is %yyyy-%mm-%dd.

Where indicated the tags can represent variable-width date elements. Variable-width date elements can
omit leading zeroes without causing errors.

The following options can be used in the format string where indicated in the table:
s Specify this option to allow leading spaces in date formats. The s option is specified in the form:
%(tag,s)
Where tag is the format string. For example:
%(m,s)
indicates a numeric month of year field in which values can contain leading spaces or zeroes and
be one or two characters wide. If you specified the following date format property:
%(d,s)/%(m,s)/%yyyy
Then the following dates would all be valid:
8/ 8/1958

Chapter 2. Designing parallel jobs 31

 08/08/1958
8/8/1958
v Use this option in conjunction with the %ddd tag to represent day of year in variable-width
format. So the following date property:
%(ddd,v)
represents values in the range 1 to 366. (If you omit the v option then the range of values would
be 001 to 366.)
u Use this option to render text elements such as day or month name in uppercase text on output.
w Use this option to render text elements such as day or month name in lowercase text on output.
t Use this option to render text elements such as day or month name in titlecase (initial capitals) on
output.

The u, w, and t options are mutually exclusive. They affect how text is formatted for output. Input dates
will still be correctly interpreted regardless of case.
-N Specify this option to left justify long day or month names so that the other elements in the date
will be aligned.
+N Specify this option to right justify long day or month names so that the other elements in the
date will be aligned.

Names are left justified or right justified within a fixed width field of N characters (where N is between 1
and 99). Names will be truncated if necessary. The following are examples of justification in use:

%dd-%(mmmm,-5)-%yyyy
21-Augus-2006

%dd-%(mmmm,-10)-%yyyy
21-August -2005

%dd-%(mmmm,+10)-%yyyy
21- August-2005

The locale for determining the setting of the day and month names can be controlled through the locale
tag. This has the format:
%(L,’locale’)

Where locale specifies the locale to be set using the language_COUNTRY.variant naming convention
supported by ICU. See NLS Guide for a list of locales. The default locale for month names and weekday
names markers is English unless overridden by a %L tag or the APT_IMPEXP_LOCALE environment
variable (the tag takes precedence over the environment variable if both are set).

Use the locale tag in conjunction with your time format, for example the format string:

%(L,’es’)%eeee, %dd %mmmm %yyyy

Specifies the Spanish locale and would result in a date with the following format:

miércoles, 21 septembre 2005

The format string is subject to the restrictions laid out in the following table. A format string can contain
at most one tag from each row. In addition some rows are mutually incompatible, as indicated in the
’incompatible with’ column. When some tags are used the format string requires that other tags are

32 Parallel Job Developer Guide

present too, as indicated in the ’requires’ column.
Table 2. Format tag restrictions
Element Numeric format tags Text format tags Requires Incompatible with
year %yyyy, %yy, - - -
%[nnnn]yy
month %mm, %m %mmm, %mmmm year week of year
day of month %dd, %d - month day of week, week of
year
day of year %ddd year day of month, day of
week, week of year
day of week %e, %E %eee, %eeee month, week of year day of year
week of year %WW year month, day of month,
day of year

When a numeric variable-width input tag such as %d or %m is used, the field to the immediate right of
the tag (if any) in the format string cannot be either a numeric tag, or a literal substring that starts with a
digit. For example, all of the following format strings are invalid because of this restriction:

%d%m-%yyyy

%d%mm-%yyyy

%(d)%(mm)-%yyyy

%h00 hours

The year_cutoff is the year defining the beginning of the century in which all two-digit years fall. By
default, the year cutoff is 1900; therefore, a two-digit year of 97 represents 1997.

You can specify any four-digit year as the year cutoff. All two-digit years then specify the next possible
year ending in the specified two digits that is the same or greater than the cutoff. For example, if you set
the year cutoff to 1930, the two-digit year 30 corresponds to 1930, and the two-digit year 29 corresponds
to 2029.

This property is mutually exclusive with days_since, text, and julian.

You can include literal text in your date format, for example as separators. Any Unicode character other
than null, backslash, or the percent sign can be used (although it is better to avoid control codes and
other non-graphic characters). The following table lists special tags and escape sequences:

Tag Escape sequence

%% literal percent sign
\% literal percent sign
\n newline
\t horizontal tab
\\ single backslash

Time formats
Format strings are used to control the format of times.

Chapter 2. Designing parallel jobs 33

The possible components of the time format string are given in the following table:
Table 3. Time format tags
Variable width
Tag availability Description Value range Options
%h import Hour (24), variable 0...23 s
width
%hh Hour (24), fixed 0...23 s
width
%H import Hour (12), variable 1...12 s
width
%HH Hour (12), fixed 01...12 s
width
%n import Minutes, variable 0...59 s
width
%nn Minutes, fixed width 0...59 s
%s import Seconds, variable 0...59 s
width
%ss Seconds, fixed width 0...59 s
%s.N import Seconds + fraction (N – s, c, C
= 0...6)
%ss.N Seconds + fraction (N – s, c, C
= 0...6)
%SSS with v option Milliseconds 0...999 s, v
%SSSSSS with v option Microseconds 0...999999 s, v
%aa German am/pm marker, am, pm u, w
locale specific

When you specify a time string, prefix each component of the format string with the percent symbol.
Separate the string’s components with a literal character.

The default time format is %hh:%nn:%ss.

Where indicated the tags can represent variable-width date elements. Variable-width time elements can
omit leading zeroes without causing errors.

The following options can be used in the format string where indicated:
s Specify this option to allow leading spaces in time formats. The s option is specified in the form:
%(tag,s)
Where tag is the format string. For example:
%(n,s)
indicates a minute field in which values can contain leading spaces or zeroes and be one or two
characters wide. If you specified the following date format property:
%(h,s):$(n,s):$(s,s)
Then the following times would all be valid:
20: 6:58
20:06:58

34 Parallel Job Developer Guide

 20:6:58
v Use this option in conjunction with the %SSS or %SSSSSS tags to represent milliseconds or
microseconds in variable-width format. So the time property:
%(SSS,v)
represents values in the range 0 to 999. (If you omit the v option then the range of values would
be 000 to 999.)
u Use this option to render the am/pm text in uppercase on output.
w Use this option to render the am/pm text in lowercase on output.
c Specify this option to use a comma as the decimal separator in the %ss.N tag.
C Specify this option to use a period as the decimal separator in the %ss.N tag.

The c and C options override the default setting of the locale.

The locale for determining the setting of the am/pm string and the default decimal separator can be
controlled through the locale tag. This has the format:
%(L,’locale’)

Where locale specifies the locale to be set using the language_COUNTRY.variant naming convention
supported by ICU. See NLS Guide for a list of locales. The default locale for am/pm string and separators
markers is English unless overridden by a %L tag or the APT_IMPEXP_LOCALE environment variable
(the tag takes precedence over the environment variable if both are set).

Use the locale tag in conjunction with your time format, for example:

%L(’es’)%HH:%nn %aa

Specifies the Spanish locale.

The format string is subject to the restrictions laid out in the following table. A format string can contain
at most one tag from each row. In addition some rows are mutually incompatible, as indicated in the
’incompatible with’ column. When some tags are used the format string requires that other tags are
present too, as indicated in the ’requires’ column.
Table 4. Format tag restrictions
Element Numeric format tags Text format tags Requires Incompatible with
hour %hh, %h, %HH, %H - - -
am/pm - %aa hour (%HH) hour (%hh)
marker
minute %nn, %n - - -
second %ss, %s - - -
fraction of a %ss.N, %s.N, %SSS, - - -
second %SSSSSS

You can include literal text in your date format. Any Unicode character other than null, backslash, or the
percent sign can be used (although it is better to avoid control codes and other non-graphic characters).
The following table lists special tags and escape sequences:

Tag Escape sequence

%% literal percent sign

Chapter 2. Designing parallel jobs 35

Tag Escape sequence
\% literal percent sign
\n newline
\t horizontal tab
\\ single backslash

Timestamp formats
Format strings are used to control the format of timestamps.

The timestamp format is the date format and the time format combined. The two formats can be in any
order and their elements can be mixed. The formats are described in “Date formats” on page 30 and
“Time formats” on page 33.

You must prefix each component of the format string with the percent symbol (%).

Incorporating server job functionality

You can incorporate Server job functionality in your Parallel jobs by the use of Server Shared Container
stages. This allows you to, for example, use Server job plug-in stages to access data source that are not
directly supported by Parallel jobs. (Some plug-ins have parallel versions that you can use directly in a
parallel job.)

You create a new shared container in the Designer, add Server job stages as required, and then add the
Server Shared Container to your Parallel job and connect it to the Parallel stages. Server Shared Container
stages used in Parallel jobs have extra pages in their Properties dialog box, which enable you to specify
details about parallel processing and partitioning and collecting data.

You can only use Server Shared Containers in this way on SMP systems (not MPP or cluster systems).

The following limitations apply to the contents of such Server Shared Containers:
v There must be zero or one container inputs, zero or more container outputs, and at least one of either.
v There can be no disconnected flows - all stages must be linked to the input or an output of the
container directly or via an active stage. When the container has an input and one or more outputs,
each stage must connect to the input and at least one of the outputs.
v There can be no synchronization by having a passive stage with both input and output links.

For details on how to use Server Shared Containers, see in WebSphere DataStage Designer Client Guide. This
also tells you how to use Parallel Shared Containers, which enable you to package parallel job
functionality in a reuseable form.

36 Parallel Job Developer Guide

Chapter 3. Stage editors
The Parallel job stage editors all use a generic user interface (with the exception of the Transformer stage,
Shared Container, and Complex Flat File stages). This chapter describes the generic editor and gives a
guide to using it.

Parallel jobs have a large number of stages available. They are organized into groups in the tool palette
or you can drag all the stages you use frequently to the Favorites category.

The stage editors are divided into the following basic types:
v Database. These are stages that read or write data contained in a database. Examples of database
stages are the Oracle Enterprise and DB2/UDB Enterprise stages.
v Development/Debug. These are stages that help you when you are developing and troubleshooting
parallel jobs. Examples are the Peek and Row Generator stages.
v File. These are stages that read or write data contained in a file or set of files. Examples of file stages
are the Sequential File and Data Set stages.
v Processing. These are stages that perform some processing on the data that is passing through them.
Examples of processing stages are the Aggregator and Transformer stages.
v Real Time. These are the stages that allow Parallel jobs to be made available as web services. They are
part of the optional Web Services package.
v Restructure. These are stages that deal with and manipulate data containing columns of complex data
type. Examples are Make Subrecord and Make Vector stages.

Parallel jobs also support local containers and shared containers. Local containers allow you to tidy your
designs by putting portions of functionality in a container, the contents of which are viewed on a
separate canvas. Shared containers are similar, but are stored separately in the repository and can be
reused by other parallel jobs. Parallel jobs can use both Parallel Shared Containers and Server Shared
Containers. Using shared containers is described in WebSphere DataStage Designer Client Guide.

The following table lists the available stage types and gives a quick guide to their function:

Stage Type Function

Data Set File Allows you to read data from or
write data to a persistent data set.
Sequential File File Allows you to read data from or
write data to one or more flat files.
File Set File Allows you to read data from or
write data to a file set. File sets
enable you to spread data across a
set of files referenced by a single
control file.
Lookup File Set File Allows you to create a lookup file set
or reference one for a lookup.

External Source File Allows you to read data that is

output from one or more source
programs.
External Target File Allows you to write data to one or
more source programs.

© Copyright IBM Corp. 2006 37

Stage Type Function
Complex Flat File File Allows you to read or write complex
flat files on a mainframe machine.
This is intended for use on USS
systems (note that it uses a different
interface from other file stages).
SAS Data Set File Allows you to read data from or
write data to a parallel SAS data set
in conjunction with an SAS stage.
DB2/UDB Enterprise Database Allows you to read data from and
write data to a DB2 database.
Oracle Enterprise Database Allows you to read data from and
write data to a Oracle database.
Teradata Enterprise Database Allows you to read data from and
write data to a Teradata database.
Informix® Enterprise Database Allows you to read data from and
write data to an Informix database.
Transformer Processing Handles extracted data, performs any
conversions required, and passes data
to another active stage or a stage that
writes data to a target database or
file.
BASIC Transformer Processing Same as Transformer stage, but gives
access to WebSphere DataStage
BASIC functions.
Aggregator Processing Classifies incoming data into groups,
computes totals and other summary
functions for each group, and passes
them to another stage in the job.
Join Processing Performs join operations on two or
more data sets input to the stage and
then outputs the resulting data set.
Merge Processing Combines a sorted master data set
with one or more sorted update data
sets.
Lookup Processing Used to perform lookup operations
on a data set read into memory from
any other Parallel job stage that can
output data or provided by one of
the database stages that support
reference output links. It can also
perform a look up on a lookup table
contained in a Lookup File Set stage.
Sort Processing Sorts input columns.
Funnel Processing Copies multiple input data sets to a
single output data set.
Remove Duplicates Processing Takes a single sorted data set as
input, removes all duplicate records,
and writes the results to an output
data set.

38 Parallel Job Developer Guide

Stage Type Function
Compress Processing Uses the UNIX compress or GZIP
utility to compress a data set. It
converts a data set from a sequence
of records into a stream of raw
binary data.
Expand Processing Uses the UNIX uncompress or GZIP
utility to expand a data set. It
converts a previously compressed
data set back into a sequence of
records from a stream of raw binary
data.
Copy Processing Copies a single input data set to a
number of output data sets.
Modify Processing Alters the record schema of its input
data set.
Filter Processing Transfers, unmodified, the records of
the input data set which satisfy
requirements that you specify and
filters out all other records.
External Filter Processing Allows you to specify a UNIX
command that acts as a filter on the
data you are processing.
Change Capture Processing Takes two input data sets, denoted
before and after, and outputs a single
data set whose records represent the
changes made to the before data set
to obtain the after data set.
Change Apply Processing Takes the change data set, that
contains the changes in the before
and after data sets, from the Change
Capture stage and applies the
encoded change operations to a before
data set to compute an after data set.
Difference Processing Performs a record-by-record
comparison of two input data sets,
which are different versions of the
same data set.
Compare Processing Performs a column-by-column
comparison of records in two
presorted input data sets.
Encode Processing Encodes a data set using a UNIX
encoding command that you supply.
Decode Processing Decodes a data set using a UNIX
decoding command that you supply.
Switch Processing Takes a single data set as input and
assigns each input record to an
output data set based on the value of
a selector field.
FTP Processing Allows you to FTP data to another
machine.
SAS (SAS Connectivity Guide) Processing Allows you to execute part or all of
an SAS application in parallel.

Chapter 3. Stage editors 39

Stage Type Function
Generic Processing Lets you incorporate an Orchestrate®
Operator in your job.
Surrogate Key Processing Generates one or more surrogate key
columns and adds them to an
existing data set.
Column Import Restructure Imports data from a single column
and outputs it to one or more
columns.
Column Export Restructure Exports data from a number of
columns of different data types into a
single column of data type string or
binary.
Make Subrecord Restructure Combines specified vectors in an
input data set into a vector of
subrecords whose columns have the
names and data types of the original
vectors.
Split Subrecord Restructure Creates one new vector column for
each element of the original
subrecord.
Combine Records Restructure Combines records, in which
particular key-column values are
identical, into vectors of subrecords.
Promote Subrecord Restructure Promotes the columns of an input
subrecord to top-level columns.
Make Vector Restructure Combines specified columns of an
input data record into a vector of
columns of the same type.
Split Vector Restructure Promotes the elements of a
fixed-length vector to a set of
similarly named top-level columns.
Head Development/ Debug Selects the first N records from each
partition of an input data set and
copies the selected records to an
output data set.
Tail Development/ Debug Selects the last N records from each
partition of an input data set and
copies the selected records to an
output data set.
Sample Development/ Debug Samples an input data set.
Peek Development/ Debug Lets you print record column values
either to the job log or to a separate
output link as the stage copies
records from its input data set to one
or more output data sets.
Row Generator Development/ Debug Produces a set of mock data fitting
the specified meta data.
Column Generator Development/ Debug Adds columns to incoming data and
generates mock data for these
columns for each data row processed.

40 Parallel Job Developer Guide

Stage Type Function
Write Range Map Development/ Debug Allows you to write data to a range
map. The stage can have a single
input link.

All of the stage types use the same basic stage editor, but the pages that actually appear when you edit
the stage depend on the exact type of stage you are editing. The following sections describe all the page
types and sub tabs that are available. The individual descriptions of stage editors in the following
chapters tell you exactly which features of the generic editor each stage type uses.

Showing stage validation errors

If you enable the Show stage validation errors option in the Diagram menu (or toolbar), the Designer
will give you visual cues for parallel jobs or parallel shared containers. The visual cues display
compilation errors for every stage on the canvas, without you having to actually compile the job. The
option is enabled by default.

Here is an example of a parallel job showing visual cues:

The top Oracle stage has a warning triangle, showing that there is a compilation error. If you hover the
mouse pointer over the stage a tooltip appears, showing the particular errors for that stage.

Any local containers on your canvas will behave like a stage, i.e., all the compile errors for stages within
the container are displayed. You have to open a parallel shared container in order to see any compile
problems on the individual stages.

Note: Parallel transformer stages will only show certain errors; to detect C++ errors in the stage, you
have to actually compile the job containing it.

The stage page

All stage editors have a Stage page. This contains a number of subsidiary tabs depending on the stage
type. The only field the Stage page itself contains gives the name of the stage being edited.

General tab
All stage editors have a General tab, this allows you to enter an optional description of the stage.
Specifying a description here enhances job maintainability.

Chapter 3. Stage editors 41

Properties tab
A Properties tab appears on the Stage page where there are general properties that need setting for the
particular stage you are editing. Properties tabs can also occur under Input and Output pages where
there are link-specific properties that need to be set.

The properties for most general stages are set under the Stage page. The following figure shows an
example Properties tab.

The available properties are displayed in a tree structure. They are divided into categories to help you
find your way around them. All the mandatory properties are included in the tree by default and cannot
be removed. Properties that you must set a value for (i.e. which have not got a default value) are shown
in the warning color (red by default), but change to black when you have set a value. You can change the
warning color by opening the Options dialog box (select Tools → Options ... from the Designer main
menu) and choosing the Transformer item from the tree. Reset the Invalid column color by clicking on
the color bar and choosing a new color from the palette.

To set a property, select it in the list and specify the required property value in the property value field.
The title of this field and the method for entering a value changes according to the property you have
selected. In the example above, the Key property is selected so the Property Value field is called Key and
you set its value by choosing one of the available input columns from a drop down list. Key is shown in
red because you must select a key for the stage to work properly. The Information field contains details
about the property you currently have selected in the tree. Where you can browse for a property value,
or insert a job parameter whose value is provided at run time, a right arrow appears next to the field.
Click on this and a menu gives access to the Browse Files dialog box and/or a list of available job
parameters (job parameters are defined in the Job Properties dialog box - see WebSphere DataStage
Designer Client Guide).

Some properties have default values, and you can always return to the default by selecting it in the tree
and choosing Set to default from the shortcut menu.

42 Parallel Job Developer Guide

Some properties are optional. These appear in the Available properties to add field. Click on an optional
property to add it to the tree or choose to add it from the shortcut menu. You can remove it again by
selecting it in the tree and selecting Remove from the shortcut menu.

Some properties can be repeated. In the example above you can add multiple key properties. The Key
property appears in the Available properties to add list when you select the tree top level Properties
node. Click on the Key item to add multiple key properties to the tree. Where a repeatable property
expects a column as an argument, a dialog is available that lets you specify multiple columns at once. To
open this, click the column button next to the properties tree.

The Column Selection dialog box opens. The left pane lists all the available columns, use the arrow right
keys to select some or all of them (use the left arrow keys to move them back if you change your mind).
A separate property will appear for each column you have selected.

Some properties have dependents. These are properties which somehow relate to or modify the parent
property. They appear under the parent in a tree structure.

For some properties you can supply a job parameter as their value. At runtime the value of this
parameter will be used for the property. Such properties will have an arrow next to their Property Value
box. Click the arrow to get a drop-down menu, then choose Insert job parameter get a list of currently
defined job parameters to chose from (see WebSphere DataStage Designer Client Guide for information about
job parameters).

You can switch to a multiline editor for entering property values for some properties. Do this by clicking
on the arrow next to their Property Value box and choosing Switch to multiline editor from the menu.

The property capabilities are indicated by different icons in the tree as follows:

non-repeating property with no dependents

non-repeating property with dependents

repeating property with no dependents

repeating property with dependents

The properties for individual stage types are described in the chapter about the stage.

Advanced tab
All stage editors have an Advanced tab. This allows you to:
v Specify the execution mode of the stage. This allows you to choose between Parallel and Sequential
operation. If the execution mode for a particular type of stage cannot be changed, then this drop down
list is disabled. Selecting Sequential operation forces the stage to be executed on a single node. If you
have intermixed sequential and parallel stages this has implications for partitioning and collecting data
between the stages. You can also let WebSphere DataStage decide by choosing the default setting for
the stage (the drop down list tells you whether this is parallel or sequential).
v Set or clear the preserve partitioning flag (this field is not available for all stage types). It indicates
whether the stage wants to preserve partitioning at the next stage of the job. You choose between Set,
Clear and Propagate. For some stage types, Propagate is not available. The operation of each option is
as follows:
– Set. Sets the preserve partitioning flag, this indicates to the next stage in the job that it should
preserve existing partitioning if possible.

Chapter 3. Stage editors 43

 – Clear. Clears the preserve partitioning flag. Indicates that this stage does not care which partitioning
method the next stage uses.
– Propagate. Sets the flag to Set or Clear depending on what the previous stage in the job has set (or
if that is set to Propagate the stage before that and so on until a preserve partitioning flag setting is
encountered).
You can also let WebSphere DataStage decide by choosing the default setting for the stage (the drop
down list tells you whether this is set, clear, or propagate).
v Specify the combinability mode. Under the covers WebSphere DataStage can combine the operators
that underlie parallel stages so that they run in the same process. This saves a significant amount of
data copying and preparation in passing data between operators.
The combinability mode setting tells WebSphere DataStage your preferences for combining for a
particular stage. It has three possible settings:
– Auto. Use the default combination setting.
– Combinable. Ignore the operator’s default setting and combine if at all possible (some operators are
marked as noncombinable by default).
– Don’t Combine. Never combine operators.
In most cases the setting should be left to Auto.
v Specify node map or node pool or resource pool constraints. The configuration file allows you to set
up pools of related nodes or resources. The Advanced tab allows you to limit execution of a stage to a
particular node or resource pool. You can also use a map to specify a group of nodes that execution
will be limited to just in this stage. Supply details as follows:
– Node pool and resource constraints. Specify constraints in the grid. Select Node pool or Resource
pool from the Constraint drop-down list. Select a Type for a resource pool and, finally, select the
name of the pool you are limiting execution to. You can select multiple node or resource pools. This
is only enabled if you have defined multiple pools in the configuration file.
– Node map constraints. Select the option box and type in the nodes to which execution will be
limited in the text box. You can also browse through the available nodes to add to the text box.
Using this feature conceptually sets up an additional node pool which doesn’t appear in the
configuration file.
The lists of available nodes, available node pools, and available resource pools are derived from the
configuration file.

Link ordering tab

This tab allows you to order the links for stages that have more than one link and where ordering of the
links is required.

The tab allows you to order input links and/or output links as needed. Where link ordering is not
important or is not possible the tab does not appear.

The link label gives further information about the links being ordered. In the example we are looking at
the Link Ordering tab for a Join stage. The join operates in terms of having a left link and a right link,
and this tab tells you which actual link the stage regards as being left and which right. If you use the
arrow keys to change the link order, the link name changes but not the link label. In our example, if you
pressed the down arrow button, DSLink27 would become the left link, and DSLink26 the right.

44 Parallel Job Developer Guide

A Join stage can only have one output link, so in the example the Order the following output links
section is disabled.

The following example shows the Link Ordering tab from a Merge stage. In this case you can order both
input links and output links. The Merge stage handles reject links as well as a stream link and the tab
allows you to order these, although you cannot move them to the stream link position. Again the link
labels give the sense of how the links are being used.

Chapter 3. Stage editors 45

The individual stage descriptions tell you whether link ordering is possible and what options are
available.

NLS Map tab

If you have NLS enabled on your system, some of your stages will have an NLS Map tab. This allows
you to override the project default character set map for this stage, and in some cases, allows you to
enable per-column mapping. When per-column mapping is enabled, you can override the character set
map for particular columns (an NLS map field appears on the Columns tab allowing you to do this).

Select a map from the list, or click the arrow button next to the list to specify a job parameter.

The following stage types currently support this feature:

v Sequential File
v File Set
v Lookup File Set
v External Source
v External Target
v DB2/UDB Enterprise (not per-column mapping)
v Oracle Enterprise (not per-column mapping)

NLS Locale tab

If you have NLS enabled on your system, some of your stages will have an NLS Locale tab. It lets you
view the current default collate convention, and select a different one for the stage if required. You can
also use a job parameter to specify the locale, or browse for a file that defines custom collate rules. The
collate convention defines the order in which characters are collated, for example, the character Ä follows
A in Germany, but follows Z in Sweden.

46 Parallel Job Developer Guide

Select a locale from the list, or click the arrow button next to the list to use a job parameter or browse for
a collate file.

The following types of stage have an NLS Locale tab:

v Stages that evaluate expressions, such as the Transformer.
v Stages that need to evaluate the order of key columns.
v The Sort Stage.

Inputs page
The Input page gives information about links going into a stage. In the case of a file or database stage an
input link carries data being written to the file or database. In the case of a processing or restructure
stage it carries data that the stage will process before outputting to another stage. Where there are no
input links, the stage editor has no Input page.

Where it is present, the Input page contains various tabs depending on stage type. The only field the
Input page itself contains is Input name, which gives the name of the link being edited. Where a stage
has more than one input link, you can select the link you are editing from the Input name drop-down
list.

The Input page also has a Columns... button. Click this to open a window showing column names from
the meta data defined for this link. You can drag these columns to various fields in the Input page tabs as
required.

Certain stage types will also have a View Data... button. Press this to view the actual data associated
with the specified data source or data target. The button is available if you have defined meta data for
the link. Note the interface allowing you to view the file will be slightly different depending on stage and
link type.

General tab
The Input page always has a General tab. this allows you to enter an optional description of the link.
Specifying a description for each link enhances job maintainability.

Properties tab
Some types of file and database stages can have properties that are particular to specific input links. In
this case the Input page has a Properties tab. This has the same format as the Stage page Properties tab
(see ″Properties Tab″ ).

Partitioning tab
Most parallel stages have a default partitioning or collecting method associated with them. This is used
depending on the execution mode of the stage (i.e., parallel or sequential) and the execution mode of the
immediately preceding stage in the job. For example, if the preceding stage is processing data
sequentially and the current stage is processing in parallel, the data will be partitioned before it enters the
current stage. Conversely if the preceding stage is processing data in parallel and the current stage is
sequential, the data will be collected as it enters the current stage.

You can, if required, override the default partitioning or collecting method on the Partitioning tab. The
selected method is applied to the incoming data as it enters the stage on a particular link, and so the
Partitioning tab appears on the Input page. You can also use the tab to repartition data between two
parallel stages. If both stages are executing sequentially, you cannot select a partition or collection method
and the fields are disabled. The fields are also disabled if the particular stage does not permit selection of

Chapter 3. Stage editors 47

partitioning or collection methods. The following table shows what can be set from the Partitioning tab in
what circumstances:

Preceding Stage Current Stage Partition Tab Mode

Parallel Parallel Partition
Parallel Sequential Collect
Sequential Parallel Partition
Sequential Sequential None (disabled)

The Partitioning tab also allows you to specify that the data should be sorted as it enters.

The Partitioning tab has the following fields:

v Partition type. Choose the partitioning (or collecting) type from the drop-down list. The following
partitioning types are available:
– (Auto). WebSphere DataStage attempts to work out the best partitioning method depending on
execution modes of current and preceding stages and how many nodes are specified in the
Configuration file. This is the default method for many stages.
– Entire. Every processing node receives the entire data set. No further information is required.
– Hash. The records are hashed into partitions based on the value of a key column or columns
selected from the Available list.
– Modulus. The records are partitioned using a modulus function on the key column selected from
the Available list. This is commonly used to partition on tag fields.
– Random. The records are partitioned randomly, based on the output of a random number generator.
No further information is required.
– Round Robin. The records are partitioned on a round robin basis as they enter the stage. No further
information is required.
– Same. Preserves the partitioning already in place. No further information is required.
– DB2. Replicates the DB2 partitioning method of a specific DB2 table. Requires extra properties to be
set. Access these properties by clicking the properties button.
– Range. Divides a data set into approximately equal size partitions based on one or more partitioning
keys. Range partitioning is often a preprocessing step to performing a total sort on a data set.
Requires extra properties to be set. Access these properties by clicking the properties button.
The following collection types are available:
– (Auto). Normally, when you are using Auto mode, WebSphere DataStage will eagerly read any row
from any input partition as it becomes available. This is the fastest collecting method and is the
default collection method for many stages. In some circumstances WebSphere DataStage will detect
further requirements for collected data, for example, it might need to be sorted. Using Auto mode
will ensure data is sorted if required.
– Ordered. Reads all records from the first partition, then all records from the second partition, and so
on. Requires no further information.
– Round Robin. Reads a record from the first input partition, then from the second partition, and so
on. After reaching the last partition, the operator starts over.
– Sort Merge. Reads records in an order based on one or more columns of the record. This requires
you to select a collecting key column from the Available list.
v Available. This lists the input columns for the input link. Key columns are identified by a key icon. For
partitioning or collecting methods that require you to select columns, you click on the required column
in the list and it appears in the Selected list to the right. This list is also used to select columns to sort
on.
v Selected. This list shows which columns have been selected for partitioning on, collecting on, or
sorting on and displays information about them. The available information is whether a sort is being

48 Parallel Job Developer Guide

 performed (indicated by an arrow), if so the order of the sort (ascending or descending) and collating
sequence (sort as EBCDIC), and whether an alphanumeric key is case sensitive or not. Nullable
columns are marked to indicate if null columns take first or last position. You can select sort order, case
sensitivity, collating sequence, and nulls position from the shortcut menu. If applicable, the Usage field
indicates whether a particular key column is being used for sorting, partitioning, or both.
v Sorting. The check boxes in the section allow you to specify sort details. The availability of sorting
depends on the partitioning method chosen.
– Perform Sort. Select this to specify that data coming in on the link should be sorted. Select the
column or columns to sort on from the Available list.
– Stable. Select this if you want to preserve previously sorted data sets. The default is stable.
– Unique. Select this to specify that, if multiple records have identical sorting key values, only one
record is retained. If stable sort is also set, the first record is retained.
You can also specify sort direction, case sensitivity, whether sorted as EBCDIC, and whether null
columns will appear first or last for each column. Where you are using a keyed partitioning method,
you can also specify whether the column is used as a key for sorting, for partitioning, or for both.
Select the column in the Selected list and right-click to invoke the shortcut menu. The availability of
the sort options depends on the type of data in the column, whether it is nullable or not, and the
partitioning method chosen.
If you have NLS enabled, the sorting box has an additional button. Click this to open the NLS
Locales tab of the Sort Properties dialog box. This lets you view the current default collate
convention, and select a different one for the stage if required. You can also use a job parameter to
specify the locale, or browse for a file that defines custom collate rules. The collate convention
defines the order in which characters are collated, for example, the character Ä follows A in
Germany, but follows Z in Sweden. Select a locale from the list, or click the arrow button next to the
list to use a job parameter or browse for a collate file.
If you require a more complex sort operation, you should use the Sort stage (see Chapter 17, “Sort
stage,” on page 253).

DB2 partition properties

This dialog box appears when you select a Partition type of DB2 and click the properties button. It
allows you to specify the DB2 table whose partitioning method is to be replicated.

Range partition properties

This dialog box appears when you select a Partition type of Range and click the properties button. It
allows you to specify the range map that is to be used to determine the partitioning (you create a range
map file using the Write Range Map stage - see Chapter 51, “Write Range Map stage,” on page 533). Type
in a pathname or browse for a file.

Format tab
Stages that write to certain types of file (e.g., the Sequential File stage) also have a Format tab which
allows you to specify the format of the file or files being written to.

The Format tab is similar in structure to the Properties tab. A flat file has a number of properties that you
can set different attributes for. Select the property in the tree and select the attributes you want to set
from the Available properties to add box, it will then appear as a dependent property in the property
tree and you can set its value as required. This tab sets the format information for the file at row level.
You can override the settings for individual columns using the Edit Column Metadata dialog box (see
page Field Level).

If you click the Load button you can load the format information from a table definition in the
Repository.

Chapter 3. Stage editors 49

The shortcut menu from the property tree gives access to the following functions:
v Format as. This applies a predefined template of properties. Choose from the following:
– Delimited/quoted
– Fixed-width records
– UNIX line terminator
– DOS line terminator
– No terminator (fixed width)
– Mainframe (COBOL)
v Add sub-property. Gives access to a list of dependent properties for the currently selected property
(visible only if the property has dependents).
v Set to default. Appears if the currently selected property has been set to a non-default value, allowing
you to re-select the default.
v Remove. Removes the currently selected property. This is disabled if the current property is mandatory.
v Remove all. Removes all the non-mandatory properties.

Details of the properties you can set are given in the chapter describing the individual stage editors:
v Sequential File stage - Input Link Format Tab
v File Set stage - Input Link Format Tab
v External Target stage - Format Tab
v Column Export stage - Properties Tab

Columns Tab
The Input page always has a Columns tab. This displays the column meta data for the selected input link
in a grid.

There are various ways of populating the grid:

v If the other end of the link has meta data specified for it, this will be displayed in the Columns tab
(meta data is associated with, and travels with, a link).
v You can type the required meta data into the grid. When you have done this, you can click the Save...
button to save the meta data as a table definition in the Repository for subsequent reuse.
v You can load an existing table definition from the Repository. Click the Load... button to be offered a
choice of table definitions to load. Note that when you load in this way you bring in the columns
definitions, not any formatting information associated with them (to load that, go to the Format tab).
v You can drag a table definition from the Repository Window on the Designer onto a link on the
canvas. This transfers both the column definitions and the associated format information.

If you select the options in the Grid Properties dialog box (see WebSphere DataStage Designer Client Guide),
the Columns tab will also display two extra fields: Table Definition Reference and Column Definition
Reference. These show the table definition and individual columns that the columns on the tab were
derived from.

If you click in a row and select Edit Row... from the shortcut menu, the Edit Column Meta Data dialog
box appears, which allows you edit the row details in a dialog box format. It also has a Parallel tab
which allows you to specify properties that are peculiar to parallel job column definitions. The dialog box
only shows those properties that are relevant for the current link.

The Parallel tab enables you to specify properties that give more detail about each column, and
properties that are specific to the data type. Where you are specifying complex data types, you can
specify a level number, which causes the Level Number field to appear in the grid on the Columns page.

50 Parallel Job Developer Guide

If you have NLS enabled, and the column has an underlying string type, you can specify that the column
contains Unicode data by selecting the Extended (Unicode) check box. Where you can enter a character
for any property, this can usually be an ASCII character or a multi-byte Unicode character (if you have
NLS enabled).

Some table definitions need format information. This occurs where data is being written to a file where
WebSphere DataStage needs additional information in order to be able to locate columns and rows.
Properties for the table definition at row level are set on the Format tab of the relevant stage editor, but
you can override the settings for individual columns using the Parallel tab. The settings are made in a
properties tree under the following categories:

Field level
This has the following properties:
v Bytes to Skip. Skip the specified number of bytes from the end of the previous column to the
beginning of this column.
v Delimiter. Specifies the trailing delimiter of the column. Type an ASCII character or select one of
whitespace, end, none, null, comma, or tab.
– whitespace. The last column of each record will not include any trailing white spaces found at the
end of the record.
– end. The end of a field is taken as the delimiter, i.e., there is no separate delimiter. This is not the
same as a setting of `None’ which is used for fields with fixed-width columns.
– none. No delimiter (used for fixed-width).
– null. ASCII Null character is used.
– comma. ASCII comma character used.
– tab. ASCII tab character used.
v Delimiter string. Specify a string to be written at the end of the column. Enter one or more characters.
This is mutually exclusive with Delimiter, which is the default. For example, specifying `, ` (comma
space - you do not need to enter the inverted commas) would have the column delimited by `, `.
v Drop on input. Select this property when you must fully define the meta data for a data set, but do
not want the column actually read into the data set.
v Prefix bytes. Specifies that this column is prefixed by 1, 2, or 4 bytes containing, as a binary value,
either the column’s length or the tag value for a tagged column. You can use this option with
variable-length fields. Variable-length fields can be either delimited by a character or preceded by a 1-,
2-, or 4-byte prefix containing the field length. WebSphere DataStage inserts the prefix before each field.
This property is mutually exclusive with the Delimiter, Quote, and Final Delimiter properties, which
are used by default.
v Print field. This property is intended for use when debugging jobs. Set it to have WebSphere
DataStage produce a message for each of the columns it reads. The message has the format:
Importing N: D
where:
– N is the column name.
– D is the imported data of the column. Non-printable characters contained in D are prefixed with an
escape character and written as C string literals; if the column contains binary data, it is output in
octal format.
v Quote. Specifies that variable length columns are enclosed in single quotes, double quotes, or another
ASCII character or pair of ASCII characters. Choose Single or Double, or enter a character.
v Start position. Specifies the starting position of a column in the record. The starting position can be
either an absolute byte offset from the first record position (0) or the starting position of another
column.

Chapter 3. Stage editors 51

v Tag case value. Explicitly specifies the tag value corresponding to a subfield in a tagged subrecord. By
default the fields are numbered 0 to N-1, where N is the number of fields. (A tagged subrecord is a
column whose type can vary. The subfields of the tagged subrecord are the possible types. The tag case
value of the tagged subrecord selects which of those types is used to interpret the column’s value for
the record.)

String type
This has the following properties:
v Character Set. Choose from ASCII or EBCDIC (not available for ustring type (Unicode)).
v Default. The default value for a column. This is used for data written by a Generate stage. It also
supplies the value to substitute for a column that causes an error (whether written or read).
v Export EBCDIC as ASCII. Select this to specify that EBCDIC characters are written as ASCII characters
(not available for ustring type (Unicode)).
v Is link field. Selected to indicate that a column holds the length of another, variable-length column of
the record or of the tag value of a tagged record field.
v Import ASCII as EBCDIC. Select this to specify that ASCII characters are read as EBCDIC characters
(not available for ustring type (Unicode)).
v Field max width. The maximum number of bytes in a column represented as a string. Enter a number.
This is useful where you are storing numbers as text. If you are using a fixed-width character set, you
can calculate the length exactly. If you are using variable-length character set, calculate an adequate
maximum width for your fields. Applies to fields of all data types except date, time, timestamp, and
raw; and record, subrec, or tagged if they contain at least one field of this type.
v Field width. The number of bytes in a column represented as a string. Enter a number. This is useful
where you are storing numbers as text. If you are using a fixed-width charset, you can calculate the
number of bytes exactly. If it’s a variable length encoding, base your calculation on the width and
frequency of your variable-width characters. Applies to fields of all data types except date, time,
timestamp, and raw; and record, subrec, or tagged if they contain at least one field of this type.
v Pad char. Specifies the pad character used when strings or numeric values are written to an external
string representation. Enter a character (single-byte for strings, can be multi-byte for ustrings) or choose
null or space. The pad character is used when the external string representation is larger than required
to hold the written field. In this case, the external string is filled with the pad character to its full
length. Space is the default. Applies to string, ustring, and numeric data types and record, subrec, or
tagged types if they contain at least one field of this type.

Date type
v Byte order. Specifies how multiple byte data types are ordered. Choose from:
– little-endian. The high byte is on the right.
– big-endian. The high byte is on the left.
– native-endian. As defined by the native format of the machine.
v Character Set. Choose from ASCII or EBCDIC.
v Days since. Dates are written as a signed integer containing the number of days since the specified
date. Enter a date in the form %yyyy-%mm-%dd or in the default date format if you have defined a
new one on an NLS system.
v Data Format. Specifies the data representation format of a column. Choose from:
– binary
– text
For dates, binary is equivalent to specifying the julian property for the date field, text specifies that
the data to be written contains a text-based date in the form %yyyy-%mm-%dd or in the default date
format if you have defined a new one on an NLS system.
v Default. The default value for a column. This is used for data written by a Generate stage. It also
supplies the value to substitute for a column that causes an error (whether written or read).

52 Parallel Job Developer Guide

v Format string. The string format of a date. By default this is %yyyy-%mm-%dd. For details about the
format, see .
If this format string does not include a day, it is set to the first of the month in the destination field. If
the format string does not include the month and day, they default to January 1. Note that the format
string must contain a month if it also contains a day; that is, you cannot omit only the month.
v Is Julian. Select this to specify that dates are written as a numeric value containing the Julian day. A
Julian day specifies the date as the number of days from 4713 BCE January 1, 12:00 hours (noon) GMT.

Time type
v Byte order. Specifies how multiple byte data types are ordered. Choose from:
– little-endian. The high byte is on the right.
– big-endian. The high byte is on the left.
– native-endian. As defined by the native format of the machine.
v Character Set. Choose from ASCII or EBCDIC.
v Default. The default value for a column. This is used for data written by a Generate stage. It also
supplies the value to substitute for a column that causes an error (whether written or read).
v Data Format. Specifies the data representation format of a column. Choose from:
– binary
– text
For time, binary is equivalent to midnight_seconds, text specifies that the field represents time in the
text-based form %hh:%nn:%ss or in the default date format if you have defined a new one on an
NLS system.
v Format string. Specifies the format of columns representing time as a string. By default this is
%hh-%mm-%ss. For details about the format, see “Time formats” on page 33
v Is midnight seconds. Select this to specify that times are written as a binary 32-bit integer containing
the number of seconds elapsed from the previous midnight.

Timestamp type
v Byte order. Specifies how multiple byte data types are ordered. Choose from:
– little-endian. The high byte is on the right.
– big-endian. The high byte is on the left.
– native-endian. As defined by the native format of the machine.
v Character Set. Choose from ASCII or EBCDIC.
v Data Format. Specifies the data representation format of a column. Choose from:
– binary
– text
For timestamp, binary specifies that the first integer contains a Julian day count for the date portion
of the timestamp and the second integer specifies the time portion of the timestamp as the number
of seconds from midnight. A binary timestamp specifies that two 32-but integers are written. Text
specifies a text-based timestamp in the form %yyyy-%mm-%dd %hh:%nn:%ss or in the default date
format if you have defined a new one on an NLS system.
v Default. The default value for a column. This is used for data written by a Generate stage. It also
supplies the value to substitute for a column that causes an error (whether written or read).
v Format string. Specifies the format of a column representing a timestamp as a string. Defaults to
%yyyy-%mm-%dd %hh:%nn:%ss. The format combines the format for date strings and time strings. See
“Date formats” on page 30 and “Time formats” on page 33.

Integer type
v Byte order. Specifies how multiple byte data types are ordered. Choose from:
– little-endian. The high byte is on the right.

Chapter 3. Stage editors 53

 – big-endian. The high byte is on the left.
– native-endian. As defined by the native format of the machine.
v Character Set. Choose from ASCII or EBCDIC.
v C_format. Perform non-default conversion of data from a string to integer data. This property specifies
a C-language format string used for reading/writing integer strings. This is passed to sscanf() or
sprintf().
v Default. The default value for a column. This is used for data written by a Generate stage. It also
supplies the value to substitute for a column that causes an error (whether written or read).
v Data Format. Specifies the data representation format of a column. Choose from:
– binary
– text
v Field max width. The maximum number of bytes in a column represented as a string. Enter a number.
Enter a number. This is useful where you are storing numbers as text. If you are using a fixed-width
character set, you can calculate the length exactly. If you are using variable-length character set,
calculate an adequate maximum width for your fields. Applies to fields of all data types except date,
time, timestamp, and raw; and record, subrec, or tagged if they contain at least one field of this type.
v Field width. The number of bytes in a column represented as a string. Enter a number. This is useful
where you are storing numbers as text. If you are using a fixed-width charset, you can calculate the
number of bytes exactly. If it’s a variable length encoding, base your calculation on the width and
frequency of your variable-width characters. Applies to fields of all data types except date, time,
timestamp, and raw; and record, subrec, or tagged if they contain at least one field of this type.
v In_format. Format string used for conversion of data from string to integer. This is passed to sscanf().
By default, WebSphere DataStage invokes the C sscanf() function to convert a numeric field formatted
as a string to either integer or floating point data. If this function does not output data in a satisfactory
format, you can specify the in_format property to pass formatting arguments to sscanf().
v Is link field. Selected to indicate that a column holds the length of another, variable-length column of
the record or of the tag value of a tagged record field.
v Out_format. Format string used for conversion of data from integer to a string. This is passed to
sprintf(). By default, WebSphere DataStage invokes the C sprintf() function to convert a numeric field
formatted as integer data to a string. If this function does not output data in a satisfactory format, you
can specify the out_format property to pass formatting arguments to sprintf().
v Pad char. Specifies the pad character used when the integer is written to an external string
representation. Enter a character (single-bye for strings, can be multi-byte for ustrings) or choose null
or space. The pad character is used when the external string representation is larger than required to
hold the written field. In this case, the external string is filled with the pad character to its full length.
Space is the default.

Decimal type
v Allow all zeros. Specifies whether to treat a packed decimal column containing all zeros (which is
normally illegal) as a valid representation of zero. Select Yes or No.
v Character Set. Choose from ASCII or EBCDIC.
v Decimal separator. Specify the character that acts as the decimal separator (period by default).
v Default. The default value for a column. This is used for data written by a Generate stage. It also
supplies the value to substitute for a column that causes an error (whether written or read).
v Data Format. Specifies the data representation format of a column. Choose from:
– binary
– text
For decimals, binary means packed. Text represents a decimal in a string format with a leading
space or ’-’ followed by decimal digits with an embedded decimal point if the scale is not zero. The
destination string format is: [+ | -]ddd.[ddd] and any precision and scale arguments are ignored.

54 Parallel Job Developer Guide

v Field max width. The maximum number of bytes in a column represented as a string. Enter a number.
Enter a number. This is useful where you are storing numbers as text. If you are using a fixed-width
character set, you can calculate the length exactly. If you are using variable-length character set,
calculate an adequate maximum width for your fields. Applies to fields of all data types except date,
time, timestamp, and raw; and record, subrec, or tagged if they contain at least one field of this type.
v Field width. The number of bytes in a column represented as a string. Enter a number. This is useful
where you are storing numbers as text. If you are using a fixed-width charset, you can calculate the
number of bytes exactly. If it’s a variable length encoding, base your calculation on the width and
frequency of your variable-width characters. Applies to fields of all data types except date, time,
timestamp, and raw; and record, subrec, or tagged if they contain at least one field of this type.
v Packed. Select an option to specify what the decimal columns contain, choose from:
– Yes to specify that the decimal columns contain data in packed decimal format (the default). This
has the following sub-properties:
Check. Select Yes to verify that data is packed, or No to not verify.
Signed. Select Yes to use the existing sign when writing decimal columns. Select No to write a
positive sign (0xf) regardless of the columns’ actual sign value.
– No (separate) to specify that they contain unpacked decimal with a separate sign byte. This has the
following sub-property:
Sign Position. Choose leading or trailing as appropriate.
– No (zoned) to specify that they contain an unpacked decimal in either ASCII or EBCDIC text. This
has the following sub-property:
Sign Position. Choose leading or trailing as appropriate.
– No (overpunch) to specify that the field has a leading or end byte that contains a character which
specifies both the numeric value of that byte and whether the number as a whole is negatively or
positively signed. This has the following sub-property:
Sign Position. Choose leading or trailing as appropriate.
v Precision. Specifies the precision where a decimal column is represented in text format. Enter a
number. When a decimal is written to a string representation, WebSphere DataStage uses the precision
and scale defined for the source decimal field to determine the length of the destination string. The
precision and scale properties override this default. When they are defined, WebSphere DataStage
truncates or pads the source decimal to fit the size of the destination string. If you have also specified
the field width property, WebSphere DataStage truncates or pads the source decimal to fit the size
specified by field width.
v Rounding. Specifies how to round the source field to fit into the destination decimal when reading a
source field to a decimal. Choose from:
– up (ceiling). Truncate source column towards positive infinity. This mode corresponds to the IEEE
754 Round Up mode. For example, 1.4 becomes 2, -1.6 becomes -1.
– down (floor). Truncate source column towards negative infinity. This mode corresponds to the IEEE
754 Round Down mode. For example, 1.6 becomes 1, -1.4 becomes -2.
– nearest value. Round the source column towards the nearest representable value. This mode
corresponds to the COBOL ROUNDED mode. For example, 1.4 becomes 1, 1.5 becomes 2, -1.4
becomes -1, -1.5 becomes -2.
– truncate towards zero. This is the default. Discard fractional digits to the right of the right-most
fractional digit supported by the destination, regardless of sign. For example, if the destination is an
integer, all fractional digits are truncated. If the destination is another decimal with a smaller scale,
truncate to the scale size of the destination decimal. This mode corresponds to the COBOL
INTEGER-PART function. Using this method 1.6 becomes 1, -1.6 becomes -1.
v Scale. Specifies how to round a source decimal when its precision and scale are greater than those of
the destination. By default, when the WebSphere DataStage writes a source decimal to a string
representation, it uses the precision and scale defined for the source decimal field to determine the
length of the destination string. You can override the default by means of the precision and scale

Chapter 3. Stage editors 55

 properties. When you do, WebSphere DataStage truncates or pads the source decimal to fit the size of
the destination string. If you have also specified the field width property, WebSphere DataStage
truncates or pads the source decimal to fit the size specified by field width. Specifies how to round a
source decimal when its precision and scale are greater than those of the destination.

Float type
v C_format. Perform non-default conversion of data from a string to floating-point data. This property
specifies a C-language format string used for reading floating point strings. This is passed to sscanf().
v Character Set. Choose from ASCII or EBCDIC.
v Default. The default value for a column. This is used for data written by a Generate stage. It also
supplies the value to substitute for a column that causes an error (whether written or read).
v Data Format. Specifies the data representation format of a column. Choose from:
– binary
– text
v Field max width. The maximum number of bytes in a column represented as a string. Enter a number.
Enter a number. This is useful where you are storing numbers as text. If you are using a fixed-width
character set, you can calculate the length exactly. If you are using variable-length character set,
calculate an adequate maximum width for your fields. Applies to fields of all data types except date,
time, timestamp, and raw; and record, subrec, or tagged if they contain at least one field of this type.
v Field width. The number of bytes in a column represented as a string. Enter a number. This is useful
where you are storing numbers as text. If you are using a fixed-width charset, you can calculate the
number of bytes exactly. If it’s a variable length encoding, base your calculation on the width and
frequency of your variable-width characters. Applies to fields of all data types except date, time,
timestamp, and raw; and record, subrec, or tagged if they contain at least one field of this type.
v In_format. Format string used for conversion of data from string to floating point. This is passed to
sscanf(). By default, WebSphere DataStage invokes the C sscanf() function to convert a numeric field
formatted as a string to floating point data. If this function does not output data in a satisfactory
format, you can specify the in_format property to pass formatting arguments to sscanf().
v Is link field. Selected to indicate that a column holds the length of a another, variable-length column
of the record or of the tag value of a tagged record field.
v Out_format. Format string used for conversion of data from floating point to a string. This is passed to
sprintf(). By default, WebSphere DataStage invokes the C sprintf() function to convert a numeric field
formatted as floating point data to a string. If this function does not output data in a satisfactory
format, you can specify the out_format property to pass formatting arguments to sprintf().
v Pad char. Specifies the pad character used when the floating point number is written to an external
string representation. Enter a character (single-bye for strings, can be multi-byte for ustrings) or choose
null or space. The pad character is used when the external string representation is larger than required
to hold the written field. In this case, the external string is filled with the pad character to its full
length. Space is the default.

Nullable
This appears for nullable fields.
v Actual field length. Specifies the number of bytes to fill with the Fill character when a field is
identified as null. When WebSphere DataStage identifies a null field, it will write a field of this length
full of Fill characters. This is mutually exclusive with Null field value.
v Null field length. The length in bytes of a variable-length field that contains a null. When a
variable-length field is read, a length of null field length in the source field indicates that it contains a
null. When a variable-length field is written, WebSphere DataStage writes a length value of null field
length if the field contains a null. This property is mutually exclusive with null field value.
v Null field value. Specifies the value given to a null field if the source is set to null. Can be a number,
string, or C-type literal escape character. For example, you can represent a byte value by \ooo, where

56 Parallel Job Developer Guide

 each o is an octal digit 0 - 7 and the first o is < 4, or by \xhh, where each h is a hexadecimal digit 0 - F.
You must use this form to encode non-printable byte values.
This property is mutually exclusive with Null field length and Actual length. For a fixed width data
representation, you can use Pad char (from the general section of Type defaults) to specify a repeated
trailing character if the value you specify is shorter than the fixed width of the field. On reading,
specifies the value given to a field containing a null. On writing, specifies the value given to a field if
the source is set to null. Can be a number, string, or C-type literal escape character.

Generator
If the column is being used in a Row Generator or Column Generator stage, this allows you to specify
extra details about the mock data being generated. The exact fields that appear depend on the data type
of the column being generated. They allow you to specify features of the data being generated, for
example, for integers they allow you to specify if values are random or whether they cycle. If they cycle
you can specify an initial value, an increment, and a limit. If they are random, you can specify a seed
value for the random number generator, whether to include negative numbers, and a limit

The diagram below shows the Generate options available for the various data types:

Chapter 3. Stage editors 57

 Cycle Value
String Algorithm
Alphabet String

Increment
Initial value
Cycle Limit
Date
Random Limit
Epoch Seed
Percent invalid Signed
Use current date
Increment
Initial value
Cycle Limit
Time
Random Limit
Scale factor Seed
Percent invalid Signed

Increment
Initial value
Cycle Limit
Timestamp
Random Limit
Epoch Seed
Percent invalid Signed
Use current date
Increment
Initial value
Cycle Limit
Integer
Random Limit
Seed
Signed

Increment
Initial value
Cycle Limit
Decimal
Random Limit
Percent zero Seed
Percent invalid Signed

Increment
Initial value
Cycle Limit
Float
Random Limit
Seed
Signed

All data types

All data types other than string have two Types of operation, cycle and random:
v Cycle. The cycle option generates a repeating pattern of values for a column. It has the following
optional dependent properties:
– Increment. The increment value added to produce the field value in the next output record. The
default value is 1 (integer) or 1.0 (float).
– Initial value. is the initial field value (value of the first output record). The default value is 0.
– Limit. The maximum field value. When the generated field value is greater than Limit, it wraps back
to Initial value. The default value of Limit is the maximum allowable value for the field’s data type.

58 Parallel Job Developer Guide

 You can set these to `part’ to use the partition number (e.g., 0, 1, 2, 3 on a four node system), or
`partcount’ to use the total number of executing partitions (e.g., 4 on a four node system).
v Random. The random option generates random values for a field. It has the following optional
dependent properties:
– Limit. Maximum generated field value. The default value of limit is the maximum allowable value
for the field’s data type.
– Seed. The seed value for the random number generator used by the stage for the field. You do not
have to specify seed. By default, the stage uses the same seed value for all fields containing the
random option.
– Signed. Specifies that signed values are generated for the field (values between -limit and +limit).
Otherwise, the operator creates values between 0 and +limit.
You can limit and seed to `part’ to use the partition number (e.g., 0, 1, 2, 3 on a four node system), or
`partcount’ to use the total number of executing partitions (e.g., 4 on a four node system).

Strings

By default the generator stages initialize all bytes of a string field to the same alphanumeric character.
The stages use the following characters, in the following order:
abcdefghijklmnopqrstuvwxyz0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ

For example, the following a string with a length of 5 would produce successive string fields with the
values:
aaaaa
bbbbb
ccccc
ddddd
...

After the last character, capital Z, values wrap back to lowercase a and the cycle repeats.

You can also use the algorithm property to determine how string values are generated, this has two
possible values: cycle and alphabet:
v Cycle. Values are assigned to a generated string field as a set of discrete string values to cycle through.
This has the following dependent property:
– Values. Repeat this property to specify the string values that the generated data cycles through.
v Alphabet. Values are assigned to a generated string field as a character string each of whose characters
is taken in turn. This is like the default mode of operation except that you can specify the string cycled
through using the dependent property String.

Decimal

As well as the Type property, decimal columns have the following properties:
v Percent invalid. The percentage of generated columns that will contain invalid values. Set to 10% by
default.
v Percent zero. The percentage of generated decimal columns where all bytes of the decimal are set to
binary zero (0x00). Set to 10% by default.

Date

As well as the Type property, date columns have the following properties:
v Epoch. Use this to specify the earliest generated date value, in the format yyyy-mm-dd (leading zeros
must be supplied for all parts). The default is 1960-01-01.

Chapter 3. Stage editors 59

v Percent invalid. The percentage of generated columns that will contain invalid values. Set to 10% by
default.
v Use current date. Set this to generate today’s date in this column for every row generated. If you set
this all other properties are ignored.

Time

As well as the Type property, time columns have the following properties:
v Percent invalid. The percentage of generated columns that will contain invalid values. Set to 10% by
default.
v Scale factor. Specifies a multiplier to the increment value for time. For example, a scale factor of 60
and an increment of 1 means the field increments by 60 seconds.

Timestamp

As well as the Type property, time columns have the following properties:
v Epoch. Use this to specify the earliest generated date value, in the format yyyy-mm-dd (leading zeros
must be supplied for all parts). The default is 1960-01-01.
v Use current date. Set this to generate today’s date in this column for every row generated. If you set
this all other properties are ignored.
v Percent invalid. The percentage of generated columns that will contain invalid values. Set to 10% by
default.
v Scale factor. Specifies a multiplier to the increment value for time. For example, a scale factor of 60
and an increment of 1 means the field increments by 60 seconds.

Vectors
If the row you are editing represents a column which is a variable length vector, tick the Variable check
box. The Vector properties appear, these give the size of the vector in one of two ways:
v Link Field Reference. The name of a column containing the number of elements in the variable length
vector. This should have an integer or float type, and have its Is Link field property set.
v Vector prefix. Specifies 1-, 2-, or 4-byte prefix containing the number of elements in the vector.

If the row you are editing represents a column which is a vector of known length, enter the number of
elements in the Vector Occurs box.

Subrecords
If the row you are editing represents a column which is part of a subrecord the Level Number column
indicates the level of the column within the subrecord structure.

If you specify Level numbers for columns, the column immediately preceding will be identified as a
subrecord. Subrecords can be nested, so can contain further subrecords with higher level numbers (i.e.,
level 06 is nested within level 05). Subrecord fields have a Tagged check box to indicate that this is a
tagged subrecord.

Extended
For certain data types the Extended check box appears to allow you to modify the data type as follows:
v Char, VarChar, LongVarChar. Select to specify that the underlying data type is a ustring.
v Time. Select to indicate that the time field includes microseconds.
v Timestamp. Select to indicate that the timestamp field includes microseconds.

60 Parallel Job Developer Guide

v TinyInt, SmallInt, Integer, BigInt types. Select to indicate that the underlying data type is the
equivalent uint field.

Advanced tab
The Advanced tab allows you to specify how WebSphere DataStage buffers data being input this stage.
By default WebSphere DataStage buffers data in such a way that no deadlocks can arise; a deadlock being
the situation where a number of stages are mutually dependent, and are waiting for input from another
stage and cannot output until they have received it.

The size and operation of the buffer are usually the same for all links on all stages (the default values
that the settings take can be set using environment variables).

The Advanced tab allows you to specify buffer settings on a per-link basis. You should only change the
settings if you fully understand the consequences of your actions (otherwise you might cause deadlock
situations to arise).

Any changes you make on this tab will automatically be reflected in the Output Page Advanced tab of
the stage at the other end of this link.

The settings are as follows:

v Buffering mode. Select one of the following from the drop-down list.
– (Default). This will take whatever the default settings are as specified by the environment variables
(this will be Auto-buffer unless you have explicitly changed the value of the APT_BUFFERING
_POLICY environment variable).
– Auto buffer. Buffer output data only if necessary to prevent a dataflow deadlock situation.
– Buffer. This will unconditionally buffer all data output from this stage.
– No buffer. Do not buffer output data under any circumstances. This could potentially lead to
deadlock situations if not used carefully.

If you choose the Auto buffer or Buffer options, you can also set the values of the various buffering
parameters:
v Maximum memory buffer size (bytes). Specifies the maximum amount of virtual memory, in bytes,
used per buffer. The default size is 3145728 (3 MB).
v Buffer free run (percent). Specifies how much of the available in-memory buffer to consume before the
buffer resists. This is expressed as a percentage of Maximum memory buffer size. When the amount of
data in the buffer is less than this value, new data is accepted automatically. When the data exceeds it,
the buffer first tries to write some of the data it contains before accepting more.
The default value is 50% of the Maximum memory buffer size. You can set it to greater than 100%, in
which case the buffer continues to store data up to the indicated multiple of Maximum memory buffer
size before writing to disk.
v Queue upper bound size (bytes). Specifies the maximum amount of data buffered at any time using
both memory and disk. The default value is zero, meaning that the buffer size is limited only by the
available disk space as specified in the configuration file (resource scratchdisk). If you set Queue upper
bound size (bytes) to a non-zero value, the amount of data stored in the buffer will not exceed this
value (in bytes) plus one block (where the data stored in a block cannot exceed 32 KB).
If you set Queue upper bound size to a value equal to or slightly less than Maximum memory buffer
size, and set Buffer free run to 1.0, you will create a finite capacity buffer that will not write to disk.
However, the size of the buffer is limited by the virtual memory of your system and you can create
deadlock if the buffer becomes full.
v Disk write increment (bytes). Sets the size, in bytes, of blocks of data being moved to/from disk by
the buffering operator. The default is 1048576 (1 MB). Adjusting this value trades amount of disk access
against throughput for small amounts of data. Increasing the block size reduces disk access, but may

Chapter 3. Stage editors 61

 decrease performance when data is being read/written in smaller units. Decreasing the block size
increases throughput, but may increase the amount of disk access.

Output page
The Output page gives information about links going out of a stage. In the case of a file or database stage
an input link carries data being read from the file or database. In the case of a processing or restructure
stage it carries data that the stage has processed. Where there are no output links the stage editor has no
Output page.

Where it is present, the Output page contains various tabs depending on stage type. The only field the
Output page itself contains is Output name, which gives the name of the link being edited. Where a
stage has more than one output link, you can select the link you are editing from the Output name
drop-down list.

The Output page also has a Columns... button. Click Columns... to open a window showing column
names from the meta data defined for this link. You can drag these columns to various fields in the
Output page tabs as required.

Certain stage types will also have a View Data... button. Press this to view the actual data associated
with the specified data source or data target. The button is available if you have defined meta data for
the link.

The Sequential File stage has a Show File... button, rather than View Data... . This shows the flat file as it
has been created on disk.

General tab
The Output page always has a General tab. this allows you to enter an optional description of the link.
Specifying a description for each link enhances job maintainability.

Properties tab
Some types of file and database stages can have properties that are particular to specific output links. In
this case the Output page has a Properties tab. This has the same format as the Stage page Properties tab
(see ″Properties Tab″ on p).

Format tab
Stages that read from certain types of file (e.g., the Sequential File stage) also have a Format tab which
allows you to specify the format of the file or files being read from.

The Format page is similar in structure to the Properties page. A flat file has a number of properties that
you can set different attributes for. Select the property in the tree and select the attributes you want to set
from the Available properties to add window, it will then appear as a dependent property in the
property tree and you can set its value as required. This tab sets the format information for the file at row
level. You can override the settings for individual columns using the Edit Column Metadata dialog box
(see Field Level).

Format details are also stored with table definitions, and you can use the Load... button to load a format
from a table definition stored in the Repository.

The short-cut menu from the property tree gives access to the following functions:
v Format as. This applies a predefined template of properties. Choose from the following:

62 Parallel Job Developer Guide

 – Delimited/quoted
– Fixed-width records
– UNIX line terminator
– DOS line terminator
– No terminator (fixed width)
– Mainframe (COBOL)
v Add sub-property. Gives access to a list of dependent properties for the currently selected property
(visible only if the property has dependents).
v Set to default. Appears if the currently selected property has been set to a non-default value, allowing
you to re-select the default.
v Remove. Removes the currently selected property. This is disabled if the current property is mandatory.
v Remove all. Removes all the non-mandatory properties.

Details of the properties you can set are given in the chapter describing the individual stage editors:
v Sequential File stage - Output Link Format Tab
v File Set stage - Output Link Format Tab
v External Source stage - Format Tab
v Column Import stage - Properties Tab

Columns tab
The Output page always has a Columns tab. This displays the column meta data for the selected output
link in a grid.

There are various ways of populating the grid:

v If the other end of the link has meta data specified for it, this will be displayed in the Columns tab
(meta data is associated with, and travels with a link).
v You can type the required meta data into the grid. When you have done this, you can click the Save...
button to save the meta data as a table definition in the Repository for subsequent reuse.
v You can load an existing table definition from the Repository. Click the Load... button to be offered a
choice of table definitions to load.
v If the stage you are editing is a general or restructure stage with a Mapping tab, you can drag data
from the left pane to the right pane. This automatically populates the right pane and the Columns tab.

If runtime column propagation is enabled in the WebSphere DataStage Administrator, you can select the
Runtime column propagation option to specify that columns encountered by the stage can be used even
if they are not explicitly defined in the meta data. There are some special considerations when using
runtime column propagation with certain stage types:
v Sequential File
v File Set
v External Source
v External Target

See the individual stage descriptions for details of these.

If the selected output link is a reject link, the column meta data grid is read only and cannot be modified.

Chapter 3. Stage editors 63

If you select the options in the Grid Properties dialog box (seeWebSphere DataStage Designer Client
Reference Guide), the Columns tab will also display two extra fields: Table Definition Reference and
Column Definition Reference. These show the table definition and individual columns that the columns
on the tab were derived from.

If you click in a row and select Edit Row... from the shortcut menu, the Edit Column meta data dialog
box appears, which allows you edit the row details in a dialog box format. It also has a Parallel tab
which allows you to specify properties that are peculiar to parallel job column definitions. The properties
you can specify here are the same as those specified for input links).

Mapping tab
For processing and restructure stages the Mapping tab allows you to specify how the output columns are
derived, i.e., what input columns map onto them or how they are generated.

The left pane shows the input columns and/or the generated columns. These are read only and cannot be
modified on this tab. These columns represent the data that the stage has produced after it has processed
the input data.

The right pane shows the output columns for each link. This has a Derivations field where you can
specify how the column is derived. You can fill it in by dragging input columns over, or by using the
Auto-match facility. If you have not yet defined any output column definitions, dragging columns over
will define them for you. If you have already defined output column definitions, WebSphere DataStage
performs the mapping for you as far as possible: you can do this explicitly using the auto-match facility,
or implicitly by just visiting the Mapping tab and clicking OK (which is the equivalent of auto-matching
on name).

There is also a shortcut menu which gives access to a range of column selection and editing functions,
including the facilities for selecting multiple columns and editing multiple derivations (this functionality
is described in the Transformer chapter).

You may choose not to map all the left hand columns, for example if your output data is a subset of your
input data, but be aware that, if you have Runtime Column Propagation turned on for that link, the data
you have not mapped will appear on the output link anyway.

You can also perform mapping without actually opening the stage editor. Select the stage in the Designer
canvas and choose Auto-map from the shortcut menu.

In the above example the left pane represents the data after it has been joined. The Expression field
shows how the column has been derived, the Column Name shows the column after it has been joined.
The right pane represents the data being output by the stage after the join. In this example the data has
been mapped straight across.

More details about mapping operations for the different stages are given in the individual stage
descriptions:

Stage Chapter Stage Chapter

Aggregator Chapter 13, “Aggregator Change Capture Chapter 26, “Change
stage,” on page 205 Capture stage,” on page
331
Join Chapter 14, “Join stage,” on Change Apply Chapter 27, “Change Apply
page 219 stage,” on page 341
Funnel Chapter 18, “Funnel Stage,” Difference Chapter 28, “Difference
on page 267 stage,” on page 351

64 Parallel Job Developer Guide

Stage Chapter Stage Chapter
Lookup Chapter 16, “Lookup Column Import Chapter 37, “Column
Stage,” on page 235 Import stage,” on page 415
Sort Chapter 17, “Sort stage,” on Column Export Chapter 38, “Column
page 253 Export stage,” on page 425
Merge Chapter 15, “Merge Stage,” Head Chapter 45, “Head stage,”
on page 227 on page 489
Remove Duplicates Chapter 19, “Remove Tail Chapter 46, “Tail stage,” on
Duplicates Stage,” on page page 497
277
Sample Chapter 47, “Sample stage,” Peek Chapter 48, “Peek stage,”
on page 503 on page 513
Column Generator Chapter 50, “Column SAS SAS Connectivity Guide
Generator stage,” on page
525
Copy Chapter 22, “Copy stage,”
on page 291

A shortcut menu can be invoked from the right pane that allows you to:
v Find and replace column names.
v Validate a derivation you have entered.
v Clear an existing derivation.
v Append a new column.
v Select all columns.
v Insert a new column at the current position.
v Delete the selected column or columns.
v Cut and copy columns.
v Paste a whole column.
v Paste just the derivation from a column.

The Find button opens a dialog box which allows you to search for particular output columns.

The Auto-Match button opens a dialog box which will automatically map left pane columns onto right
pane columns according to the specified criteria.

Select Location match to map input columns onto the output ones occupying the equivalent position.
Select Name match to match by names. You can specify that all columns are to be mapped by name, or
only the ones you have selected. You can also specify that prefixes and suffixes are ignored for input and
output columns, and that case can be ignored.

Advanced tab
The Advanced tab allows you to specify how WebSphere DataStage buffers data being output from this
stage. By default WebSphere DataStage buffers data in such a way that no deadlocks can arise; a
deadlock being the situation where a number of stages are mutually dependent, and are waiting for input
from another stage and cannot output until they have received it.

The size and operation of the buffer are usually the same for all links on all stages (the default values
that the settings take can be set using environment variables - see WebSphere DataStage Installatiuon and
Configuration Guide).

Chapter 3. Stage editors 65

The Advanced tab allows you to specify buffer settings on a per-link basis. You should only change the
settings if you fully understand the consequences of your actions (otherwise you might cause deadlock
situations to arise).

Any changes you make on this tab will automatically be reflected in the Input page Advanced tab of the
stage at the other end of this link

The settings are as follows:

v Buffering mode. Select one of the following from the drop-down list.
– (Default). This will take whatever the default settings are as specified by the environment variables
(this will be Auto-buffer unless you have explicitly changed the value of the APT_BUFFERING
_POLICY environment variable).
– Auto buffer. Buffer output data only if necessary to prevent a dataflow deadlock situation.
– Buffer. This will unconditionally buffer all data output from this stage.
– No buffer. Do not buffer output data under any circumstances. This could potentially lead to
deadlock situations if not used carefully.

If you choose the Auto buffer or Buffer options, you can also set the values of the various buffering
parameters:
v Maximum memory buffer size (bytes). Specifies the maximum amount of virtual memory, in bytes,
used per buffer. The default size is 3145728 (3 MB).
v Buffer free run (percent). Specifies how much of the available in-memory buffer to consume before the
buffer resists. This is expressed as a percentage of Maximum memory buffer size. When the amount of
data in the buffer is less than this value, new data is accepted automatically. When the data exceeds it,
the buffer first tries to write some of the data it contains before accepting more.
The default value is 50% of the Maximum memory buffer size. You can set it to greater than 100%, in
which case the buffer continues to store data up to the indicated multiple of Maximum memory buffer
size before writing to disk.
v Queue upper bound size (bytes). Specifies the maximum amount of data buffered at any time using
both memory and disk. The default value is zero, meaning that the buffer size is limited only by the
available disk space as specified in the configuration file (resource scratchdisk). If you set Queue upper
bound size (bytes) to a non-zero value, the amount of data stored in the buffer will not exceed this
value (in bytes) plus one block (where the data stored in a block cannot exceed 32 KB).
If you set Queue upper bound size to a value equal to or slightly less than Maximum memory buffer
size, and set Buffer free run to 1.0, you will create a finite capacity buffer that will not write to disk.
However, the size of the buffer is limited by the virtual memory of your system and you can create
deadlock if the buffer becomes full.
v Disk write increment (bytes). Sets the size, in bytes, of blocks of data being moved to/from disk by
the buffering operator. The default is 1048576 (1 MB). Adjusting this value trades amount of disk access
against throughput for small amounts of data. Increasing the block size reduces disk access, but may
decrease performance when data is being read/written in smaller units. Decreasing the block size
increases throughput, but may increase the amount of disk access.

66 Parallel Job Developer Guide

Chapter 4. Data set stage
The Data Set stage is a file stage. It allows you to read data from or write data to a data set. The stage
can have a single input link or a single output link. It can be configured to execute in parallel or
sequential mode.

What is a data set? parallel jobs use data sets to manage data within a job. You can think of each link in a
job as carrying a data set. The Data Set stage allows you to store data being operated on in a persistent
form, which can then be used by other WebSphere DataStage jobs. Data sets are operating system files,
each referred to by a control file, which by convention has the suffix .ds. Using data sets wisely can be
key to good performance in a set of linked jobs. You can also manage data sets independently of a job
using the Data Set Management utility, available from the WebSphere DataStage Designer or Director, see
Chapter 53, “Managing data sets,” on page 547.

The stage editor has up to three pages, depending on whether you are reading or writing a data set:
v Stage Page. This is always present and is used to specify general information about the stage.
v Input Page. This is present when you are writing to a data set. This is where you specify details about
the data set being written to.
v Output Page. This is present when you are reading from a data set. This is where you specify details
about the data set being read from.

Must do’s
WebSphere DataStage has many defaults which means that it can be very easy to include Data Set stages
in a job. This section specifies the minimum steps to take to get a Data Set stage functioning. WebSphere
DataStage provides a versatile user interface, and there are many shortcuts to achieving a particular end,
this section describes the basic methods, you will learn where the shortcuts are when you get familiar
with the product.

The steps required depend on whether you are using the Data Set stage to read or write a data set.

© Copyright IBM Corp. 2006 67

Writing to a data set
v In the Input Link Properties Tab specify the pathname of the control file for the target data set. Set the
Update Policy property, or accept the default setting of Overwrite.
v Ensure column meta data has been specified for the data set (this may have already been done in a
preceding stage).

Reading from a data set

v In the Output Link Properties Tab specify the pathname of the control file for the source data set.
v Ensure column meta data has been specified for the data set.

Stage page
The General tab allows you to specify an optional description of the stage. The Advanced tab allows you
to specify how the stage executes.

Advanced tab
This tab allows you to specify the following:
v Execution Mode. The stage can execute in parallel mode or sequential mode. In parallel mode the
contents of the data set are processed by the available nodes as specified in the Configuration file, and
by any node constraints specified on the Advanced tab. In Sequential mode the entire contents of the
data set are processed by the conductor node.
v Combinability mode. This is Auto by default, which allows WebSphere DataStage to combine the
operators that underlie parallel stages so that they run in the same process if it is sensible for this type
of stage.
v Preserve partitioning. You can select Propagate, Set or Clear. If you select Set file read operations will
request that the next stage preserves the partitioning as is. Propagate takes the setting of the flag from
the previous stage.
v Node pool and resource constraints. Select this option to constrain parallel execution to the node pool
or pools and/or resource pool or pools specified in the grid. The grid allows you to make choices from
drop down lists populated from the Configuration file.
v Node map constraint. Select this option to constrain parallel execution to the nodes in a defined node
map. You can define a node map by typing node numbers into the text box or by clicking the browse
button to open the Available Nodes dialog box and selecting nodes from there. You are effectively
defining a new node pool for this stage (in addition to any node pools defined in the Configuration
file).

Input page
The Input page allows you to specify details about how the Data Set stage writes data to a data set. The
Data Set stage can have only one input link.

The General tab allows you to specify an optional description of the input link. The Properties tab allows
you to specify details of exactly what the link does. The Columns tab specifies the column definitions of
the data. The Advanced tab allows you to change the default buffering settings for the input link.

Details about Data Set stage properties are given in the following sections. See ″Stage Editors,″ for a
general description of the other tabs.

68 Parallel Job Developer Guide

Input link properties tab
The Properties tab allows you to specify properties for the input link. These dictate how incoming data is
written and to what data set. Some of the properties are mandatory, although many have default settings.
Properties without default settings appear in the warning color (red by default) and turn black when you
supply a value for them.

The following table gives a quick reference list of the properties and their attributes. A more detailed
description of each property follows:

Category/
Property Values Default Mandatory? Repeats? Dependent of
Target/File pathname N/A Y N N/A
Target/Update Append/Create Overwrite Y N N/A
Policy (Error if
exists)/
Overwrite/Use
existing (Discard
records)/Use
existing (Discard
records and
schema)

Target Category
File

The name of the control file for the data set. You can browse for the file or enter a job parameter. By
convention, the file has the suffix .ds.

Update Policy

Specifies what action will be taken if the data set you are writing to already exists. Choose from:
v Append. Append any new data to the existing data.
v Create (Error if exists). WebSphere DataStage reports an error if the data set already exists.
v Overwrite. Overwrites any existing data with new data.
v Use existing (Discard records). Keeps the existing data and discards any new data.
v Use existing (Discard records and schema). Keeps the existing data and discards any new data and its
associated schema.

The default is Overwrite.

Partitioning tab
The Partitioning tab allows you to specify details about how the incoming data is partitioned or collected
before it is written to the data set. It also allows you to specify that the data should be sorted before
being written.

By default the stage partitions in Auto mode. This attempts to work out the best partitioning method
depending on execution modes of current and preceding stages and how many nodes are specified in the
Configuration file.

If the Data Set stage is operating in sequential mode, it will first collect the data before writing it to the
file using the default Auto collection method.

Chapter 4. Data set stage 69

The Partitioning tab allows you to override this default behavior. The exact operation of this tab depends
on:
v Whether the Data Set stage is set to execute in parallel or sequential mode.
v Whether the preceding stage in the job is set to execute in parallel or sequential mode.

If the Data Set stage is set to execute in parallel, then you can set a partitioning method by selecting from
the Partition type drop-down list. This will override any current partitioning.

If the Data Set stage is set to execute in sequential mode, but the preceding stage is executing in parallel,
then you can set a collection method from the Collector type drop-down list. This will override the
default auto collection method.

The following partitioning methods are available:

v (Auto). WebSphere DataStage attempts to work out the best partitioning method depending on
execution modes of current and preceding stages and how many nodes are specified in the
Configuration file. This is the default partitioning method for the Data Set stage.
v Entire. Each file written to receives the entire data set.
v Hash. The records are hashed into partitions based on the value of a key column or columns selected
from the Available list.
v Modulus. The records are partitioned using a modulus function on the key column selected from the
Available list. This is commonly used to partition on tag fields.
v Random. The records are partitioned randomly, based on the output of a random number generator.
v Round Robin. The records are partitioned on a round robin basis as they enter the stage.
v Same. Preserves the partitioning already in place.
v DB2. Replicates the DB2 partitioning method of a specific DB2 table. Requires extra properties to be
set. Access these properties by clicking the properties button.
v Range. Divides a data set into approximately equal size partitions based on one or more partitioning
keys. Range partitioning is often a preprocessing step to performing a total sort on a data set. Requires
extra properties to be set. Access these properties by clicking the properties button.

The following Collection methods are available:

v (Auto). This is the default collection method for the Data Set stage. Normally, when you are using
Auto mode, WebSphere DataStage will eagerly read any row from any input partition as it becomes
available.
v Ordered. Reads all records from the first partition, then all records from the second partition, and so
on.
v Round Robin. Reads a record from the first input partition, then from the second partition, and so on.
After reaching the last partition, the operator starts over.
v Sort Merge. Reads records in an order based on one or more columns of the record. This requires you
to select a collecting key column from the Available list.

The Partitioning tab also allows you to specify that data arriving on the input link should be sorted
before being written to the data set. The sort is always carried out within data partitions. If the stage is
partitioning incoming data the sort occurs after the partitioning. If the stage is collecting data, the sort
occurs before the collection. The availability of sorting depends on the partitioning or collecting method
chosen (it is not available with Auto methods).

Select the check boxes as follows:

v Sort. Select this to specify that data coming in on the link should be sorted. Select the column or
columns to sort on from the Available list.
v Stable. Select this if you want to preserve previously sorted data sets. This is the default.

70 Parallel Job Developer Guide

v Unique. Select this to specify that, if multiple records have identical sorting key values, only one
record is retained. If stable sort is also set, the first record is retained.

If NLS is enabled an additional button opens a dialog box allowing you to select a locale specifying the
collate convention for the sort.

You can also specify sort direction, case sensitivity, whether sorted as ASCII or EBCDIC, and whether null
columns will appear first or last for each column. Where you are using a keyed partitioning method, you
can also specify whether the column is used as a key for sorting, for partitioning, or for both. Select the
column in the Selected list and right-click to invoke the shortcut menu.

Output page
The Output page allows you to specify details about how the Data Set stage reads data from a data set.
The Data Set stage can have only one output link.

The General tab allows you to specify an optional description of the output link. The Properties tab
allows you to specify details of exactly what the link does. The Columns tab specifies the column
definitions of incoming data. The Advanced tab allows you to change the default buffering settings for
the output link.

Details about Data Set stage properties and formatting are given in the following sections. See ″Stage
Editors,″ for a general description of the other tabs.

Output link properties tab

The Properties tab allows you to specify properties for the output link. These dictate how incoming data
is read from the data set. A Data Set stage only has one property, but this is mandatory.

Category/
Property Values Default Mandatory? Repeats? Dependent of
Source/File pathname N/A Y N N/A

Source category
File

The name of the control file for the data set. You can browse for the file or enter a job parameter. By
convention the file has the suffix .ds.

Chapter 4. Data set stage 71

72 Parallel Job Developer Guide
Chapter 5. Sequential file stage
The Sequential File stage is a file stage. It allows you to read data from or write data one or more flat
files. The stage can have a single input link or a single output link, and a single rejects link.

When you edit a Sequential File stage, the Sequential File stage editor appears. This is based on the
generic stage editor described in ″Stage Editors.″

© Copyright IBM Corp. 2006 73

The stage executes in parallel mode if reading multiple files but executes sequentially if it is only reading
one file. By default a complete file will be read by a single node (although each node might read more
than one file). For fixed-width files, however, you can configure the stage to behave differently:
v You can specify that single files can be read by multiple nodes. This can improve performance on
cluster systems. See ″Read From Multiple Nodes″
v You can specify that a number of readers run on a single node. This means, for example, that a single
file can be partitioned as it is read (even though the stage is constrained to running sequentially on the
conductor node). See ″Number Of Readers Per Node″.

(These two options are mutually exclusive.)

The stage executes in parallel if writing to multiple files, but executes sequentially if writing to a single
file. Each node writes to a single file, but a node can write more than one file.

When reading or writing a flat file, WebSphere DataStage needs to know something about the format of
the file. The information required is how the file is divided into rows and how rows are divided into
columns. You specify this on the Format tab. Settings for individual columns can be overridden on the
Columns tab using the Edit Column Metadata dialog box.

The stage editor has up to three pages, depending on whether you are reading or writing a file:
v Stage Page. This is always present and is used to specify general information about the stage.
v Input Page. This is present when you are writing to a flat file. This is where you specify details about
the file or files being written to.
v Output Page. This is present when you are reading from a flat file and/or have a reject link. This is
where you specify details about the file or files being read from.

There are one or two special points to note about using runtime column propagation (RCP) with
Sequential stages. See 98 for details.

Example of writing a sequential file

In the following example, the Sequential File stage is set up to write a comma-delimited file. Here is a
sample of the data as it will be written:
"GC10001","PEMBERTON CREEK SUBDIVISION","ONE LIEBICH LN ","2/13/1984 "
"GC10011","BROOK HIGHLAND TOWNES","BROOK HIGHLAND PKWY","8/30/1983 "
"GC10015","SUMMIT PIPE & SUPPLY","6501 MCFARLAND BOULEVARD","4/28/1986 "
"GC10017","HOFFMAN INSTRUMENTATION SUPPLY","14271 NW SCEINCE PARK DR","4/4/1986 "
"GC10022","M & C EQUIPMEMT","2106 HWY 290E","9/15/1983 "
"GC10037","BAYER CORPORATION","1530 BUSHY PARK RD","5/21/1985 "
"GC10061","PLATEAU EQUIPMENT SUPPLY CO","805 S 8TH ST","9/9/1983 "
"GC10063","STATEWIDE CABLING INC","719 KIRKMAN ROAD","9/2/1983 "
"GC10072","X10PRO","10014 NORTH DALE MABRY HWY","9/16/1983 "
"GC10074","RUSSELL OLSEN CONSTRUCTION","2820 HELENA FLATS RD","9/8/1983 "
"GC10079","PLATEAU INSULATION CO","14200 EAST 33RD PL","9/12/1983 "
"GC10128","LIGHT BULB DEPOT","1523 WILDE ROCK WAY","9/1/1983 "
"GC10134","MACMILLAN BLOEDEL PCKGING INC","1901 E 22ND STREET","2/7/1986 "
"GC10138","SANDY PINES PH 4","SANDY PINES","9/8/1983 "
"GC10144","PONTE VEDRA DERMATOLOGY","224 PONTE VEDRA PARK DR","9/12/1983 "," ",""
"GC10148","RACK STRAP INC","808 MOLALLA AVE","9/14/1983 "
"GC10152","PINAL COUNTY JUVENILE & ADULT","820 E COTTONWOOD LANE","8/31/1983 "
"GC10163","B & B UNDERGROUND CONTRACTORS ","16545 FARM RD","10/10/1983"
"GC10172","XTRA LITE LIGHTING INC","207-21ST AVENUE SOUTH","8/31/1983 "
"GC10176","CANES CENTRAL","1711 UPLAND RD","4/10/1979 "
"GC10182","O CET INC","420 JACKSON ST","8/31/1983 "

74 Parallel Job Developer Guide

The metadata for the file is defined in the Columns tab as follows:
Table 5. Example metadata for writing to a sequential file
Column name Key SQL Type Length Nullable
CUSTOMER_NUMBER yes char 7 no
CUST_NAME varchar 30 no
ADDR_1 varchar 30 no
SETUP_DATE char 10 no

The Format tab is set as follows to define that the stage will write a file where each column is delimited
by a comma, there is no final delimiter, and any dates in the data are expected to have the format
mm/dd/yyyy with or without leading zeroes for month and day, rather than yyyy-mm-dd, which is the
default format:

Example of reading a sequential file

In the following example, the sequential file stage is set up to read a fixed width file. Here is a sample of
the data in the file:
0136.801205/04/2001
0210.001525/04/2001
0316.803002/01/2002
0414.704002/01/2002
0517.200202/01/2002
0616.003002/01/2002
0744.001012/08/2001

Chapter 5. Sequential file stage 75

0814.403002/01/2002
0950.002502/01/2002
1026.201012/08/2001
1120.701012/08/2001
1239.401012/08/2001
1310.000302/01/2002
1412.000502/01/2002
1528.800102/01/2002
1636.802021/06/2001

The meta data for the file is defined in the Columns tab as follows:
Table 6. Example metadata for reading a sequential file
Column name Key SQL Type Length Nullable
OrderID yes char 2 no
Price char 5 no
Quantity char 2 no
Order_Date char 10 no

The Format tab is set as follows to define that the stage is reading a fixed width file where each row is
delimited by a UNIX newline, and the columns have no delimiter:

76 Parallel Job Developer Guide

Must do’s
WebSphere DataStage has many defaults which means that it can be very easy to include Sequential File
stages in a job. This section specifies the minimum steps to take to get a Sequential File stage functioning.
WebSphere DataStage provides a versatile user interface, and there are many shortcuts to achieving a
particular end, this section describes the basic method, you will learn where the shortcuts are when you
get familiar with the product.

The steps required depend on whether you are using the Sequential File stage to read or write a file.

Writing to a file
v In the Input Link Properties Tab specify the pathname of the file being written to (repeat this for
writing to multiple files). The other properties all have default values, which you can change or not as
required.
v In the Input Link Format Tab specify format details for the file(s) you are writing to, or accept the
defaults (variable length columns enclosed in double quotes and delimited by commas, rows delimited
with UNIX newlines).
v Ensure column meta data has been specified for the file(s) (this can be achieved via a schema file if
required).

Reading from a file

v In the Output Link Properties Tab:
– In Read Method, specify whether to read specific files (the default) or all files whose name fits a
pattern.
– If you are reading specific files, specify the pathname of the file being read from (repeat this for
reading multiple files).
– If you are reading files that fit a pattern, specify the name pattern to match.
– Accept the default for the options or specify new settings (available options depend on the Read
Method).
v In the Output Link Format Tab specify format details for the file(s) you are reading from, or accept the
defaults (variable length columns enclosed in double quotes and delimited by commas, rows delimited
with UNIX newlines).
v Ensure column meta data has been specified for the file(s) (this can be achieved via a schema file if
required).

Stage page
The General tab allows you to specify an optional description of the stage. The Advanced tab allows you
to specify how the stage executes. The NLS Map tab appears if you have NLS enabled on your system, it
allows you to specify a character set map for the stage.

Advanced tab
This tab allows you to specify the following:
v Execution Mode. The stage can execute in parallel mode or sequential mode. When a stage is reading
or writing a single file the Execution Mode is sequential and you cannot change it. When a stage is
reading or writing multiple files, the Execution Mode is parallel and you cannot change it. In parallel
mode, the files are processed by the available nodes as specified in the Configuration file, and by any
node constraints specified on the Advanced tab. In Sequential mode the entire contents of the file are
processed by the conductor node.

Chapter 5. Sequential file stage 77

v Combinability mode. This is Auto by default, which allows WebSphere DataStage to combine the
operators that underlie parallel stages so that they run in the same process if it is sensible for this type
of stage.
v Preserve partitioning. You can select Set or Clear. If you select Set file read operations will request
that the next stage preserves the partitioning as is (it is ignored for file write operations). If you set the
Keep File Partitions output property this will automatically set the preserve partitioning flag.
v Node pool and resource constraints. Select this option to constrain parallel execution to the node pool
or pools and/or resource pool or pools specified in the grid. The grid allows you to make choices from
drop down lists populated from the Configuration file.
v Node map constraint. Select this option to constrain parallel execution to the nodes in a defined node
map. You can define a node map by typing node numbers into the text box or by clicking the browse
button to open the Available Nodes dialog box and selecting nodes from there. You are effectively
defining a new node pool for this stage (in addition to any node pools defined in the Configuration
file).

NLS Map tab

The NLS Map tab allows you to define a character set map for the Sequential File stage. This overrides
the default character set map set for the project or the job. You can specify that the map be supplied as a
job parameter if required. You can also select Allow per-column mapping. This allows character set maps
to be specified for individual columns within the data processed by the Sequential File stage. An extra
property, NLS Map, appears in the Columns grid in the Columns tab, but note that only ustring data
types allow you to set an NLS map value (see ″Data Types″).

Input page
The Input page allows you to specify details about how the Sequential File stage writes data to one or
more flat files. The Sequential File stage can have only one input link, but this can write to multiple files.

The General tab allows you to specify an optional description of the input link. The Properties tab allows
you to specify details of exactly what the link does. The Partitioning tab allows you to specify how
incoming data is partitioned before being written to the file or files. The Formats tab gives information
about the format of the files being written. The Columns tab specifies the column definitions of data
being written. The Advanced tab allows you to change the default buffering settings for the input link.

Details about Sequential File stage properties, partitioning, and formatting are given in the following
sections. See ″Stage Editors,″ for a general description of the other tabs.

Input link properties tab

The Properties tab allows you to specify properties for the input link. These dictate how incoming data is
written and to what files. Some of the properties are mandatory, although many have default settings.
Properties without default settings appear in the warning color (red by default) and turn black when you
supply a value for them.

The following table gives a quick reference list of the properties and their attributes. A more detailed
description of each property follows.

Category/
Property Values Default Mandatory? Repeats? Dependent of
Target/File Pathname N/A Y Y N/A
Target/File Append/ Create/ Overwrite Y N N/A
Update Mode Overwrite

78 Parallel Job Developer Guide

Category/
Property Values Default Mandatory? Repeats? Dependent of
Options/Cleanup True/False True Y N N/A
On Failure
Options/Reject Continue/Fail/ Continue Y N N/A
Mode Save
Options/Filter Command N/A N N N/A
Options/Schema Pathname N/A N N N/A
File

Target category
File

This property defines the flat file that the incoming data will be written to. You can type in a pathname,
or browse for a file. You can specify multiple files by repeating the File property. Do this by selecting the
Properties item at the top of the tree, and clicking on File in the Available properties to add box. Do this
for each extra file you want to specify.

You must specify at least one file to be written to, which must exist unless you specify a File Update
Mode of Create or Overwrite.

File update mode

This property defines how the specified file or files are updated. The same method applies to all files
being written to. Choose from Append to append to existing files, Overwrite to overwrite existing files,
or Create to create a new file. If you specify the Create property for a file that already exists you will get
an error at runtime.

By default this property is set to Overwrite.

Options category
Cleanup on failure

This is set to True by default and specifies that the stage will delete any partially written files if the stage
fails for any reason. Set this to False to specify that partially written files should be left.

Reject mode

This specifies what happens to any data records that are not written to a file for some reason. Choose
from Continue to continue operation and discard any rejected rows, Fail to cease writing if any rows are
rejected, or Save to send rejected rows down a reject link.

Continue is set by default.

Filter

This is an optional property. You can use this to specify that the data is passed through a filter program
before being written to the file or files. Specify the filter command, and any required arguments, in the
Property Value box.

Schema file

This is an optional property. By default the Sequential File stage will use the column definitions defined
on the Columns and Format tabs as a schema for writing to the file. You can, however, specify a file

Chapter 5. Sequential file stage 79

containing a schema instead (note, however, that if you have defined columns on the Columns tab, you
should ensure these match the schema file). Type in a pathname or browse for a schema file.

Partitioning tab
The Partitioning tab allows you to specify details about how the incoming data is partitioned or collected
before it is written to the file or files. It also allows you to specify that the data should be sorted before
being written.

By default the stage partitions in Auto mode. This attempts to work out the best partitioning method
depending on execution modes of current and preceding stages and how many nodes are specified in the
Configuration file.

If the Sequential File stage is operating in sequential mode, it will first collect the data before writing it to
the file using the default Auto collection method.

The Partitioning tab allows you to override this default behavior. The exact operation of this tab depends
on:
v Whether the Sequential File stage is set to execute in parallel or sequential mode.
v Whether the preceding stage in the job is set to execute in parallel or sequential mode.

If the Sequential File stage is set to execute in parallel (i.e., is writing to multiple files), then you can set a
partitioning method by selecting from the Partition type drop-down list. This will override any current
partitioning.

If the Sequential File stage is set to execute in sequential mode (i.e., is writing to a single file), but the
preceding stage is executing in parallel, then you can set a collection method from the Collector type
drop-down list. This will override the default auto collection method.

The following partitioning methods are available:

v (Auto). WebSphere DataStage attempts to work out the best partitioning method depending on
execution modes of current and preceding stages and how many nodes are specified in the
Configuration file. This is the default partitioning method for the Sequential File stage.
v Entire. Each file written to receives the entire data set.
v Hash. The records are hashed into partitions based on the value of a key column or columns selected
from the Available list.
v Modulus. The records are partitioned using a modulus function on the key column selected from the
Available list. This is commonly used to partition on tag fields.
v Random. The records are partitioned randomly, based on the output of a random number generator.
v Round Robin. The records are partitioned on a round robin basis as they enter the stage.
v Same. Preserves the partitioning already in place.
v DB2. Replicates the DB2 partitioning method of a specific DB2 table. Requires extra properties to be
set. Access these properties by clicking the properties button.
v Range. Divides a data set into approximately equal size partitions based on one or more partitioning
keys. Range partitioning is often a preprocessing step to performing a total sort on a data set. Requires
extra properties to be set. Access these properties by clicking the properties button.

The following Collection methods are available:

v (Auto). This is the default collection method for the Sequential File stage. Normally, when you are
using Auto mode, WebSphere DataStage will eagerly read any row from any input partition as it
becomes available.

80 Parallel Job Developer Guide

v Ordered. Reads all records from the first partition, then all records from the second partition, and so
on.
v Round Robin. Reads a record from the first input partition, then from the second partition, and so on.
After reaching the last partition, the operator starts over.
v Sort Merge. Reads records in an order based on one or more columns of the record. This requires you
to select a collecting key column from the Available list.

The Partitioning tab also allows you to specify that data arriving on the input link should be sorted
before being written to the file or files. The sort is always carried out within data partitions. If the stage is
partitioning incoming data the sort occurs after the partitioning. If the stage is collecting data, the sort
occurs before the collection. The availability of sorting depends on the partitioning or collecting method
chosen (it is not available with the Auto methods).

Select the check boxes as follows:

v Perform Sort. Select this to specify that data coming in on the link should be sorted. Select the column
or columns to sort on from the Available list.
v Stable. Select this if you want to preserve previously sorted data sets. This is the default.
v Unique. Select this to specify that, if multiple records have identical sorting key values, only one
record is retained. If stable sort is also set, the first record is retained.

If NLS is enabled an additional button opens a dialog box allowing you to select a locale specifying the
collate convention for the sort.

You can also specify sort direction, case sensitivity, whether sorted as ASCII or EBCDIC, and whether null
columns will appear first or last for each column. Where you are using a keyed partitioning method, you
can also specify whether the column is used as a key for sorting, for partitioning, or for both. Select the
column in the Selected list and right-click to invoke the shortcut menu.

Input link format tab

The Format tab allows you to supply information about the format of the flat file or files to which you
are writing. The tab has a similar format to the Properties tab.

If you do not alter any of the Format settings, the Sequential File stage will produce a file of the
following format:
v File comprises variable length columns contained within double quotes.
v All columns are delimited by a comma, except for the final column in a row.
v Rows are delimited by a UNIX newline.

You can use the Format As item from the shortcut menu in the Format tab to quickly change to a
fixed-width column format, using DOS newlines as row delimiters, or producing a COBOL format file.

You can use the Defaults button to change your default settings. Use the Format tab to specify your
required settings, then click Defaults → Save current as default. All your sequential files will use your
settings by default from now on. If your requirements change, you can choose Defaults → Reset defaults
from factory settings to go back to the original defaults as described above. Once you have done this,
you then have to click Defaults → Set current from default for the new defaults to take effect.

To change individual properties, select a property type from the main tree then add the properties you
want to set to the tree structure by clicking on them in the Available properties to set window. You can
then set a value for that property in the Property Value box. Pop-up help for each of the available
properties appears if you hover the mouse pointer over it.

Chapter 5. Sequential file stage 81

Any property that you set on this tab can be overridden at the column level by setting properties for
individual columns on the Edit Column Metadata dialog box (see Columns Tab).

This description uses the terms ″record″ and ″row″ and ″field″ and ″column″ interchangeably.

The following sections list the property types and properties available for each type.

Record level

These properties define details about how data records are formatted in the flat file. Where you can enter
a character, this can usually be an ASCII character or a multi-byte Unicode character (if you have NLS
enabled). The available properties are:

Fill char

Specify an ASCII character or a value in the range 0 to 255. You can also choose Space or Null from a
drop-down list. This character is used to fill any gaps in a written record caused by column positioning
properties. Set to 0 by default (which is the NULL character). For example, to set it to space you could
also type in the space character or enter 32. Note that this value is restricted to one byte, so you cannot
specify a multi-byte Unicode character.

Final delimiter string

Specify a string to be written after the last column of a record in place of the column delimiter. Enter one
or more characters, this precedes the record delimiter if one is used. Mutually exclusive with Final
delimiter, which is the default. For example, if you set Delimiter to comma and Final delimiter string to `,
` (comma space - you do not need to enter the inverted commas) all fields are delimited by a comma,
except the final field, which is delimited by a comma followed by an ASCII space character.

Final delimiter

Specify a single character to be written after the last column of a record in place of the field delimiter.
Type a character or select one of whitespace, end, none, null, tab, or comma. See the following diagram
for an illustration.
v whitespace. The last column of each record will not include any trailing white spaces found at the end
of the record.
v end. The last column of each record does not include the field delimiter. This is the default setting.
v none. The last column of each record does not have a delimiter; used for fixed-width fields.
v null. The last column of each record is delimited by the ASCII null character.
v comma. The last column of each record is delimited by the ASCII comma character.
v tab. The last column of each record is delimited by the ASCII tab character.
record delimiter

Field , Field , Field , Last field nl

Final delimiter = end

field delimiter

Field , Field , Field , Last field , nl

Final delimiter = comma
82 Parallel Job Developer Guide
When writing, a space is now inserted after every field except the last in the record. Previously, a space
was inserted after every field including the last. (If you want to revert to the pre-release 7.5 behavior of
inserting a space after the last field, set the APT_FINAL_DELIM_COMPATIBLE environment variable.

Intact

The intact property specifies an identifier of a partial schema. A partial schema specifies that only the
column(s) named in the schema can be modified by the stage. All other columns in the row are passed
through unmodified. The file containing the partial schema is specified in the Schema File property on
the Properties tab. This property has a dependent property, Check intact, but this is not relevant to input
links.

Record delimiter string

Specify a string to be written at the end of each record. Enter one or more characters. This is mutually
exclusive with Record delimiter, which is the default, record type and record prefix.

Record delimiter

Specify a single character to be written at the end of each record. Type a character or select one of the
following:
v UNIX Newline (the default)
v null

(To implement a DOS newline, use the Record delimiter string property set to ″\R\N″ or chooseFormat
as → DOS line terminator from the shortcut menu.)

Note: Record delimiter is mutually exclusive with Record delimiter string, Record prefix, and Record
type.

Record length

Select Fixed where fixed length fields are being written. WebSphere DataStage calculates the appropriate
length for the record. Alternatively specify the length of fixed records as number of bytes. This is not
used by default (default files are comma-delimited). The record is padded to the specified length with
either zeros or the fill character if one has been specified.

Record Prefix

Specifies that a variable-length record is prefixed by a 1-, 2-, or 4-byte length prefix. It is set to 1 by
default. This is mutually exclusive with Record delimiter, which is the default, and record delimiter string
and record type.

Record type

Specifies that data consists of variable-length blocked records (varying) or implicit records (implicit). If
you choose the implicit property, data is written as a stream with no explicit record boundaries. The end
of the record is inferred when all of the columns defined by the schema have been parsed. The varying
property allows you to specify one of the following IBM blocked or spanned formats: V, VB, VS, VBS, or
VR.

This property is mutually exclusive with Record length, Record delimiter, Record delimiter string, and
Record prefix and by default is not used.

Chapter 5. Sequential file stage 83

Field defaults

Defines default properties for columns written to the file or files. These are applied to all columns
written, but can be overridden for individual columns from the Columns tab using the Edit Column
Metadata dialog box. Where you can enter a character, this can usually be an ASCII character or a
multi-byte Unicode character (if you have NLS enabled). The available properties are:
v Actual field length. Specifies the number of bytes to fill with the Fill character when a field is
identified as null. When WebSphere DataStage identifies a null field, it will write a field of this length
full of Fill characters. This is mutually exclusive with Null field value.
v Delimiter. Specifies the trailing delimiter of all fields in the record. Type an ASCII character or select
one of whitespace, end, none, null, comma, or tab.
– whitespace. Whitespace characters at the end of a column are ignored, i.e., are not treated as part of
the column.
– end. The end of a field is taken as the delimiter, i.e., there is no separate delimiter. This is not the
same as a setting of `None’ which is used for fields with fixed-width columns.
– none. No delimiter (used for fixed-width).
– null. ASCII Null character is used.
– comma. ASCII comma character is used.
– tab. ASCII tab character is used.
v Delimiter string. Specify a string to be written at the end of each field. Enter one or more characters.
This is mutually exclusive with Delimiter, which is the default. For example, specifying `, ` (comma
space - you do not need to enter the inverted commas) would have each field delimited by `, ` unless
overridden for individual fields.
v Null field length. The length in bytes of a variable-length field that contains a null. When a
variable-length field is written, WebSphere DataStage writes a length value of null field length if the
field contains a null. This property is mutually exclusive with null field value.
v Null field value. Specifies the value written to null field if the source is set to null. Can be a number,
string, or C-type literal escape character. For example, you can represent a byte value by \ooo, where
each o is an octal digit 0 - 7 and the first o is < 4, or by \xhh, where each h is a hexadecimal digit 0 - F.
You must use this form to encode non-printable byte values.
This property is mutually exclusive with Null field length and Actual length. For a fixed width data
representation, you can use Pad char (from the general section of Type defaults) to specify a repeated
trailing character if the value you specify is shorter than the fixed width of the field.
v Prefix bytes. Specifies that each column in the data file is prefixed by 1, 2, or 4 bytes containing, as a
binary value, either the column’s length or the tag value for a tagged field.
You can use this option with variable-length fields. Variable-length fields can be either delimited by a
character or preceded by a 1-, 2-, or 4-byte prefix containing the field length. WebSphere DataStage
inserts the prefix before each field.
This property is mutually exclusive with the Delimiter, Quote, and Final Delimiter properties, which
are used by default.
v Print field. This property is not relevant for input links.
v Quote. Specifies that variable length fields are enclosed in single quotes, double quotes, or another
character or pair of characters. Choose Single or Double, or enter a character. This is set to double
quotes by default.
When writing, WebSphere DataStage inserts the leading quote character, the data, and a trailing quote
character. Quote characters are not counted as part of a field’s length.
v Vector prefix. For fields that are variable length vectors, specifies a 1-, 2-, or 4-byte prefix containing
the number of elements in the vector. You can override this default prefix for individual vectors.
Variable-length vectors must use either a prefix on the vector or a link to another field in order to
specify the number of elements in the vector. If the variable length vector has a prefix, you use this

84 Parallel Job Developer Guide

 property to indicate the prefix length. WebSphere DataStage inserts the element count as a prefix of
each variable-length vector field. By default, the prefix length is assumed to be one byte.

Type defaults

These are properties that apply to all columns of a specific data type unless specifically overridden at the
column level. They are divided into a number of subgroups according to data type.

General

These properties apply to several data types (unless overridden at column level):
v Byte order. Specifies how multiple byte data types (except string and raw data types) are ordered.
Choose from:
– little-endian. The high byte is on the right.
– big-endian. The high byte is on the left.
– native-endian. As defined by the native format of the machine. This is the default.
v Data Format. Specifies the data representation format of a field. Applies to fields of all data types
except string, ustring, and raw and to record, subrec or tagged fields containing at least one field that
is neither string nor raw. Choose from:
– binary
– text (the default)
A setting of binary has different meanings when applied to different data types:
– For decimals, binary means packed.
– For other numerical data types, binary means ″not text″.
– For dates, binary is equivalent to specifying the julian property for the date field.
– For time, binary is equivalent to midnight_seconds.
– For timestamp, binary specifies that the first integer contains a Julian day count for the date portion
of the timestamp and the second integer specifies the time portion of the timestamp as the number
of seconds from midnight. A binary timestamp specifies that two 32-but integers are written.
By default data is formatted as text, as follows:
– For the date data type, text specifies that the data to be written contains a text-based date in the
form %yyyy-%mm-%dd or in the default date format if you have defined a new one on an NLS
system (see WebSphere DataStage NLS Guide).
– For the decimal data type: a field represents a decimal in a string format with a leading space or ’-’
followed by decimal digits with an embedded decimal point if the scale is not zero. The destination
string format is: [+ | -]ddd.[ddd] and any precision and scale arguments are ignored.
– For numeric fields (int8, int16, int32, uint8, uint16, uint32, sfloat, and dfloat): WebSphere DataStage
assumes that numeric fields are represented as text.
– For the time data type: text specifies that the field represents time in the text-based form
%hh:%nn:%ss or in the default date format if you have defined a new one on an NLS system (see
WebSphere DataStage NLS Guide).
– For the timestamp data type: text specifies a text-based timestamp in the form %yyyy-%mm-%dd
%hh:%nn:%ss or in the default date format if you have defined a new one on an NLS system (see
WebSphere DataStage NLS Guide).
v Field max width. The maximum number of bytes in a column represented as a string. Enter a number.
This is useful where you are storing numbers as text. If you are using a fixed-width character set, you
can calculate the length exactly. If you are using variable-length character set, calculate an adequate
maximum width for your fields. Applies to fields of all data types except date, time, timestamp, and
raw; and record, subrec, or tagged if they contain at least one field of this type.
v Field width. The number of bytes in a field represented as a string. Enter a number. This is useful
where you are storing numbers as text. If you are using a fixed-width charset, you can calculate the

Chapter 5. Sequential file stage 85

 number of bytes exactly. If it’s a variable length encoding, base your calculation on the width and
frequency of your variable-width characters. Applies to fields of all data types except date, time,
timestamp, and raw; and record, subrec, or tagged if they contain at least one field of this type.
If you specify neither field width nor field max width, numeric fields written as text have the
following number of bytes as their maximum width:
– 8-bit signed or unsigned integers: 4 bytes
– 16-bit signed or unsigned integers: 6 bytes
– 32-bit signed or unsigned integers: 11 bytes
– 64-bit signed or unsigned integers: 21 bytes
– single-precision float: 14 bytes (sign, digit, decimal point, 7 fraction, ″E″, sign, 2 exponent)
– double-precision float: 24 bytes (sign, digit, decimal point, 16 fraction, ″E″, sign, 3 exponent)
v Pad char. Specifies the pad character used when strings or numeric values are written to an external
string representation. Enter a character (single-byte for strings, can be multi-byte for ustrings) or choose
null or space. The pad character is used when the external string representation is larger than required
to hold the written field. In this case, the external string is filled with the pad character to its full
length. Space is the default. Applies to string, ustring, and numeric data types and record, subrec, or
tagged types if they contain at least one field of this type.
v Character set. Specifies the character set. Choose from ASCII or EBCDIC. The default is ASCII. Applies
to all data types except raw and ustring and record, subrec, or tagged containing no fields other than
raw or ustring.

String

These properties are applied to columns with a string data type, unless overridden at column level.
v Export EBCDIC as ASCII. Select this to specify that EBCDIC characters are written as ASCII
characters. Applies to fields of the string data type and record, subrec, or tagged fields if they contain
at least one field of this type.
v Import ASCII as EBCDIC. Not relevant for input links.
For ASCII-EBCDIC and EBCDIC-ASCII conversion tables, see WebSphere DataStage Developer’s Help.

Decimal

These properties are applied to columns with a decimal data type unless overridden at column level.
v Allow all zeros. Specifies whether to treat a packed decimal column containing all zeros (which is
normally illegal) as a valid representation of zero. Select Yes or No. The default is No.
v Decimal separator. Specify the ASCII character that acts as the decimal separator (period by default).
v Packed. Select an option to specify what the decimal columns contain, choose from:
– Yes to specify that the decimal columns contain data in packed decimal format (the default). This
has the following sub-properties:
Check. Select Yes to verify that data is packed, or No to not verify.
Signed. Select Yes to use the existing sign when writing decimal columns. Select No to write a
positive sign (0xf) regardless of the columns’ actual sign value.
– No (separate) to specify that they contain unpacked decimal with a separate sign byte. This has the
following sub-property:
Sign Position. Choose leading or trailing as appropriate.
– No (zoned) to specify that they contain an unpacked decimal in either ASCII or EBCDIC text. This
has the following sub-property:
Sign Position. Choose leading or trailing as appropriate.

86 Parallel Job Developer Guide

 – No (overpunch) to specify that the field has a leading or end byte that contains a character which
specifies both the numeric value of that byte and whether the number as a whole is negatively or
positively signed. This has the following sub-property:
Sign Position. Choose leading or trailing as appropriate.
v Precision. Specifies the precision where a decimal column is written in text format. Enter a number.
When a decimal is written to a string representation, WebSphere DataStage uses the precision and scale
defined for the source decimal field to determine the length of the destination string. The precision and
scale properties override this default. When they are defined, WebSphere DataStage truncates or pads
the source decimal to fit the size of the destination string. If you have also specified the field width
property, WebSphere DataStage truncates or pads the source decimal to fit the size specified by field
width.
v Rounding. Specifies how to round a decimal column when writing it. Choose from:
– up (ceiling). Truncate source column towards positive infinity. This mode corresponds to the IEEE
754 Round Up mode. For example, 1.4 becomes 2, -1.6 becomes -1.
– down (floor). Truncate source column towards negative infinity. This mode corresponds to the IEEE
754 Round Down mode. For example, 1.6 becomes 1, -1.4 becomes -2.
– nearest value. Round the source column towards the nearest representable value. This mode
corresponds to the COBOL ROUNDED mode. For example, 1.4 becomes 1, 1.5 becomes 2, -1.4
becomes -1, -1.5 becomes -2.
– truncate towards zero. This is the default. Discard fractional digits to the right of the right-most
fractional digit supported by the destination, regardless of sign. For example, if the destination is an
integer, all fractional digits are truncated. If the destination is another decimal with a smaller scale,
truncate to the scale size of the destination decimal. This mode corresponds to the COBOL
INTEGER-PART function. Using this method 1.6 becomes 1, -1.6 becomes -1.
v Scale. Specifies how to round a source decimal when its precision and scale are greater than those of
the destination. By default, when the WebSphere DataStage writes a source decimal to a string
representation, it uses the precision and scale defined for the source decimal field to determine the
length of the destination string. You can override the default by means of the precision and scale
properties. When you do, WebSphere DataStage truncates or pads the source decimal to fit the size of
the destination string. If you have also specified the field width property, WebSphere DataStage
truncates or pads the source decimal to fit the size specified by field width.

Numeric

These properties apply to integer and float fields unless overridden at column level.
v C_format. Perform non-default conversion of data from integer or floating-point data to a string. This
property specifies a C-language format string used for writing integer or floating point strings. This is
passed to sprintf(). For example, specifying a C-format of %x and a field width of 8 ensures that
integers are written as 8-byte hexadecimal strings.
v In_format. This property is not relevant for input links..
v Out_format. Format string used for conversion of data from integer or floating-point data to a string.
This is passed to sprintf(). By default, WebSphere DataStage invokes the C sprintf() function to convert a
numeric field formatted as either integer or floating point data to a string. If this function does not
output data in a satisfactory format, you can specify the out_format property to pass formatting
arguments to sprintf().

Date

These properties are applied to columns with a date data type unless overridden at column level. All of
these are incompatible with a Data Format setting of Text.
v Days since. Dates are written as a signed integer containing the number of days since the specified
date. Enter a date in the form %yyyy-%mm-%dd or in the default date format if you have defined a
new one on an NLS system (see WebSphere DataStage NLS Guide).

Chapter 5. Sequential file stage 87

v Format string. The string format of a date. By default this is %yyyy-%mm-%dd. For details about the
format, see .
v Is Julian. Select this to specify that dates are written as a numeric value containing the Julian day. A
Julian day specifies the date as the number of days from 4713 BCE January 1, 12:00 hours (noon) GMT.

Time

These properties are applied to columns with a time data type unless overridden at column level. All of
these are incompatible with a Data Format setting of Text.
v Format string. Specifies the format of columns representing time as a string. For details about the
format, see “Time formats” on page 33
v Is midnight seconds. Select this to specify that times are written as a binary 32-bit integer containing
the number of seconds elapsed from the previous midnight.

Timestamp

These properties are applied to columns with a timestamp data type unless overridden at column level.
v Format string. Specifies the format of a column representing a timestamp as a string. Defaults to
%yyyy-%mm-%dd %hh:%nn:%ss. The format combines the format for date strings and time strings. See
“Date formats” on page 30 and “Time formats” on page 33.

Output page
The Output page allows you to specify details about how the Sequential File stage reads data from one
or more flat files. The Sequential File stage can have only one output link, but this can read from multiple
files.

It can also have a single reject link. This is typically used when you are writing to a file and provides a
location where records that have failed to be written to a file for some reason can be sent. When you are
reading files, you can use a reject link as a destination for rows that do not match the expected column
definitions.

The Output name drop-down list allows you to choose whether you are looking at details of the main
output link (the stream link) or the reject link.

The General tab allows you to specify an optional description of the output link. The Properties tab
allows you to specify details of exactly what the link does. The Formats tab gives information about the
format of the files being read. The Columns tab specifies the column definitions of the data. The
Advanced tab allows you to change the default buffering settings for the output link.

Details about Sequential File stage properties and formatting are given in the following sections. See
Chapter 3, “Stage editors,” on page 37, ″Stage Editors,″ for a general description of the other tabs.

Output link properties tab

The Properties tab allows you to specify properties for the output link. These dictate how incoming data
is read from what files. Some of the properties are mandatory, although many have default settings.
Properties without default settings appear in the warning color (red by default) and turn black when you
supply a value for them.

The following table gives a quick reference list of the properties and their attributes. A more detailed
description of each property follows.

88 Parallel Job Developer Guide

Category/
Property Values Default Mandatory? Repeats? Dependent of
Source/File pathname N/A Y if Read Method Y N/A
= Specific Files(s)
Source/File pathname N/A Y if Read Method N N/A
Pattern = Field Pattern
Source/Read Specific Specific Files(s) Y N N/A
Method File(s)/File
Pattern
Options/Missing Error/OK/ Depends Y if File used N N/A
File Mode Depends
Options/Keep file True/False False Y N N/A
Partitions
Options/Reject Continue/ Continue Y N N/A
Mode Fail/Save
Options/Report Yes/No Yes Y N N/A
Progress
Options/Filter command N/A N N N/A
Options/File column name fileNameColumn N N N/A
Name Column
Options/Number number 1 N N N/A
Of Readers Per
Node
Options/Schema pathname N/A N N N/A
File

Source category
File

This property defines the flat file that data will be read from. You can type in a pathname, or browse for
a file. You can specify multiple files by repeating the File property. Do this by selecting the Properties
item at the top of the tree, and clicking on File in the Available properties to add window. Do this for
each extra file you want to specify.

File pattern

Specifies a group of files to import. Specify file containing a list of files or a job parameter representing
the file. The file could also contain be any valid shell expression, in Bourne shell syntax, that generates a
list of file names.

Read method

This property specifies whether you are reading from a specific file or files or using a file pattern to select
files (e.g., *.txt).

Options category
Missing file mode

Specifies the action to take if one of your File properties has specified a file that does not exist. Choose
from Error to stop the job, OK to skip the file, or Depends, which means the default is Error, unless the
file has a node name prefix of *: in which case it is OK. The default is Depends.

Chapter 5. Sequential file stage 89

Keep file partitions

Set this to True to partition the imported data set according to the organization of the input file(s). So, for
example, if you are reading three files you will have three partitions. Defaults to False.

Reject mode

Allows you to specify behavior if a read record does not match the expected schema. Choose from
Continue to continue operation and discard any rejected rows, Fail to cease reading if any rows are
rejected, or Save to send rejected rows down a reject link. Defaults to Continue.

Report progress

Choose Yes or No to enable or disable reporting. By default the stage displays a progress report at each
10% interval when it can ascertain file size. Reporting occurs only if the file is greater than 100 KB,
records are fixed length, and there is no filter on the file.

Filter

This is an optional property. You can use this to specify that the data is passed through a filter program
after being read from the files. Specify the filter command, and any required arguments, in the Property
Value box.

File name column

This is an optional property. It adds an extra column of type VarChar to the output of the stage,
containing the pathname of the file the record is read from. You should also add this column manually to
the Columns definitions to ensure that the column is not dropped if you are not using runtime column
propagation, or it is turned off at some point.

Number Of readers per node

This is an optional property and only applies to files containing fixed-length records, it is mutually
exclusive with the Read from multiple nodes property. Specifies the number of instances of the file read
operator on a processing node. The default is one operator per node per input data file. If numReaders is
greater than one, each instance of the file read operator reads a contiguous range of records from the
input file. The starting record location in the file for each operator, or seek location, is determined by the
data file size, the record length, and the number of instances of the operator, as specified by numReaders.

The resulting data set contains one partition per instance of the file read operator, as determined by
numReaders.

This provides a way of partitioning the data contained in a single file. Each node reads a single file, but
the file can be divided according to the number of readers per node, and written to separate partitions.
This method can result in better I/O performance on an SMP system.

90 Parallel Job Developer Guide

 number of readers
per node = 4
file partitioned data set

reader
reader
reader
reader

node

Read from multiple nodes

This is an optional property and only applies to files containing fixed-length records, it is mutually
exclusive with the Number of Readers Per Node property. Set this to Yes to allow individual files to be
read by several nodes. This can improve performance on a cluster system.

WebSphere DataStage knows the number of nodes available, and using the fixed length record size, and
the actual size of the file to be read, allocates the reader on each node a separate region within the file to
process. The regions will be of roughly equal size.

read from multiple

nodes = yes

reader
file partitioned data set
node

reader
node

reader
node

reader
node

Schema file

This is an optional property. By default the Sequential File stage will use the column definitions defined
on the Columns and Format tabs as a schema for reading the file. You can, however, specify a file
containing a schema instead (note, however, that if you have defined columns on the Columns tab, you
should ensure these match the schema file). Type in a pathname or browse for a schema file.

Reject Links
You cannot change the properties of a Reject link. The Properties tab for a reject link is blank.

Chapter 5. Sequential file stage 91

Similarly, you cannot edit the column definitions for a reject link. For writing files, the link uses the
column definitions for the input link. For reading files, the link uses a single column called rejected
containing raw data for columns rejected after reading because they do not match the schema.

Output link format tab

The Format tab allows you to supply information about the format of the flat file or files that you are
reading. The tab has a similar format to the Properties tab.

If you do not alter any of the Format settings, the Sequential File stage will produce a file of the
following format:
v File comprises variable length columns contained within double quotes.
v All columns are delimited by a comma, except for the final column in a row.
v Rows are delimited by a UNIX newline.

You can use the Format As item from the shortcut menu in the Format tab to quickly change to a
fixed-width column format, using DOS newlines as row delimiters, or producing a COBOL format file.

You can use the Defaults button to change your default settings. Use the Format tab to specify your
required settings, then click Defaults → Save current as default. All your sequential files will use your
settings by default from now on. If your requirements change, you can choose Defaults → Reset defaults
from factory settings to go back to the original defaults as described above. Once you have done this,
you then have to click Defaults → Set current from default for the new defaults to take effect.

To change individual properties, select a property type from the main tree then add the properties you
want to set to the tree structure by clicking on them in the Available properties to set window. You can
then set a value for that property in the Property Value box. Pop-up help for each of the available
properties appears if you hover the mouse pointer over it.

Any property that you set on this tab can be overridden at the column level by setting properties for
individual columns on the Edit Column Metadata dialog box (see page Columns Tab).

This description uses the terms ″record″ and ″row″ and ″field″ and ″column″ interchangeably.

The following sections list the property types and properties available for each type.

Record level

These properties define details about how data records are formatted in the flat file. Where you can enter
a character, this can usually be an ASCII character or a multi-byte Unicode character (if you have NLS
enabled). The available properties are:
v Fill char. Does not apply to output links.
v Final delimiter string. Specify the string written after the last column of a record in place of the
column delimiter. Enter one or more characters, this precedes the record delimiter if one is used.
Mutually exclusive with Final delimiter, which is the default. For example, if you set Delimiter to
comma and Final delimiter string to `, ` (comma space - you do not need to enter the inverted
commas) all fields are delimited by a comma, except the final field, which is delimited by a comma
followed by an ASCII space character. WebSphere DataStage skips the specified delimiter string when
reading the file.
v Final delimiter. Specify the single character written after the last column of a record in place of the
field delimiter. Type a character or select one of whitespace, end, none, null, tab, or comma. WebSphere
DataStage skips the specified delimiter string when reading the file. See the following diagram for an
illustration.

92 Parallel Job Developer Guide

 – whitespace. The last column of each record will not include any trailing white spaces found at the
end of the record.
– end. The last column of each record does not include the field delimiter. This is the default setting.
– none. The last column of each record does not have a delimiter, used for fixed-width fields.
– null. The last column of each record is delimited by the ASCII null character.
– comma. The last column of each record is delimited by the ASCII comma character.
– tab. The last column of each record is delimited by the ASCII tab character.
record delimiter

Field , Field , Field , Last field nl

Final delimiter = end

field delimiter

Field , Field , Field , Last field , nl

Final delimiter = comma
v Intact. The intact property specifies an identifier of a partial schema. A partial schema specifies that
only the column(s) named in the schema can be modified by the stage. All other columns in the row
are passed through unmodified. The file containing the partial schema is specified in the Schema File
property on the Outputs tab. This property has a dependent property:
– Check intact. Select this to force validation of the partial schema as the file or files are imported.
Note that this can degrade performance.
v Record delimiter string. Specify the string at the end of each record. Enter one or more characters.
This is mutually exclusive with Record delimiter, which is the default, and record type and record
prefix.
v Record delimiter. Specify the single character at the end of each record. Type a character or select one
of the following:
– UNIX Newline (the default)
– null
(To specify a DOS newline, use the Record delimiter string property set to ″\R\N″ or choose Format
as → DOS line terminator from the shortcut menu.)
Record delimiter is mutually exclusive with Record delimiter string, Record prefix, and record type.
v Record length. Select Fixed where fixed length fields are being read. WebSphere DataStage calculates
the appropriate length for the record. Alternatively specify the length of fixed records as number of
bytes. This is not used by default (default files are comma-delimited).
v Record Prefix. Specifies that a variable-length record is prefixed by a 1-, 2-, or 4-byte length prefix. It is
set to 1 by default. This is mutually exclusive with Record delimiter, which is the default, and record
delimiter string and record type.
v Record type. Specifies that data consists of variable-length blocked records (varying) or implicit records
(implicit). If you choose the implicit property, data is written as a stream with no explicit record
boundaries. The end of the record is inferred when all of the columns defined by the schema have
been parsed. The varying property allows you to specify one of the following IBM blocked or spanned
formats: V, VB, VS, VBS, or VR.
This property is mutually exclusive with Record length, Record delimiter, Record delimiter string, and
Record prefix and by default is not used.

Chapter 5. Sequential file stage 93

Field Defaults

Defines default properties for columns read from the file or files. These are applied to all columns, but
can be overridden for individual columns from the Columns tab using the Edit Column Metadata dialog
box. Where you can enter a character, this can usually be an ASCII character or a multi-byte Unicode
character (if you have NLS enabled). The available properties are:
v Actual field length. Specifies the actual number of bytes to skip if the field’s length equals the setting
of the null field length property.
v Delimiter. Specifies the trailing delimiter of all fields in the record. Type an ASCII character or select
one of whitespace, end, none, null, comma, or tab. WebSphere DataStage skips the delimiter when
reading.
– whitespace. Whitespace characters at the end of a column are ignored, i.e., are not treated as part of
the column.
– end. The end of a field is taken as the delimiter, i.e., there is no separate delimiter. This is not the
same as a setting of `None’ which is used for fields with fixed-width columns.
– none. No delimiter (used for fixed-width).
– null. ASCII Null character is used.
– comma. ASCII comma character is used.
– tab. ASCII tab character is used.
v Delimiter string. Specify the string at the end of each field. Enter one or more characters. This is
mutually exclusive with Delimiter, which is the default. For example, specifying `, ` (comma space -
you do not need to enter the inverted commas) specifies each field is delimited by `, ` unless
overridden for individual fields. WebSphere DataStage skips the delimiter string when reading.
v Null field length. The length in bytes of a variable-length field that contains a null. When a
variable-length field is read, a length of null field length in the source field indicates that it contains a
null. This property is mutually exclusive with null field value.
v Null field value. Specifies the value given to a null field if the source is set to null. Can be a number,
string, or C-type literal escape character. For example, you can represent a byte value by \ooo, where
each o is an octal digit 0 - 7 and the first o is < 4, or by \xhh, where each h is a hexadecimal digit 0 - F.
You must use this form to encode non-printable byte values.
This property is mutually exclusive with Null field length and Actual length. For a fixed width data
representation, you can use Pad char (from the general section of Type defaults) to specify a repeated
trailing character if the value you specify is shorter than the fixed width of the field.
v Prefix bytes. You can use this option with variable-length fields. Variable-length fields can be either
delimited by a character or preceded by a 1-, 2-, or 4-byte prefix containing the field length. WebSphere
DataStage reads the length prefix but does not include the prefix as a separate field in the data set it
reads from the file.
This property is mutually exclusive with the Delimiter, Quote, and Final Delimiter properties, which
are used by default.
v Print field. This property is intended for use when debugging jobs. Set it to have WebSphere
DataStage produce a message for every field it reads. The message has the format:
Importing N: D
where:
– N is the field name.
– D is the imported data of the field. Non-printable characters contained in D are prefixed with an
escape character and written as C string literals; if the field contains binary data, it is output in octal
format.
v Quote. Specifies that variable length fields are enclosed in single quotes, double quotes, or another
character or pair of characters. Choose Single or Double, or enter a character. This is set to double
quotes by default.

94 Parallel Job Developer Guide

 When reading, WebSphere DataStage ignores the leading quote character and reads all bytes up to but
not including the trailing quote character.
v Vector prefix. For fields that are variable length vectors, specifies that a 1-, 2-, or 4-byte prefix contains
the number of elements in the vector. You can override this default prefix for individual vectors.
Variable-length vectors must use either a prefix on the vector or a link to another field in order to
specify the number of elements in the vector. If the variable length vector has a prefix, you use this
property to indicate the prefix length. WebSphere DataStage reads the length prefix but does not
include it as a separate field in the data set. By default, the prefix length is assumed to be one byte.

Type Defaults

These are properties that apply to all columns of a specific data type unless specifically overridden at the
column level. They are divided into a number of subgroups according to data type.

General

These properties apply to several data types (unless overridden at column level):
v Byte order. Specifies how multiple byte data types (except string and raw data types) are ordered.
Choose from:
– little-endian. The high byte is on the right.
– big-endian. The high byte is on the left.
– native-endian. As defined by the native format of the machine. This is the default.
v Data Format. Specifies the data representation format of a field. Applies to fields of all data types
except string, ustring, and raw and to record, subrec or tagged fields containing at least one field that
is neither string nor raw. Choose from:
– binary
– text (the default)
A setting of binary has different meanings when applied to different data types:
– For decimals, binary means packed.
– For other numerical data types, binary means ″not text″.
– For dates, binary is equivalent to specifying the julian property for the date field.
– For time, binary is equivalent to midnight_seconds.
– For timestamp, binary specifies that the first integer contains a Julian day count for the date portion
of the timestamp and the second integer specifies the time portion of the timestamp as the number
of seconds from midnight. A binary timestamp specifies that two 32-but integers are written.
By default data is formatted as text, as follows:
– For the date data type, text specifies that the data read, contains a text-based date in the form
%yyyy-%mm-%dd or in the default date format if you have defined a new one on an NLS system
(see WebSphere DataStage NLS Guide).
– For the decimal data type: a field represents a decimal in a string format with a leading space or ’-’
followed by decimal digits with an embedded decimal point if the scale is not zero. The destination
string format is: [+ | -]ddd.[ddd] and any precision and scale arguments are ignored.
– For numeric fields (int8, int16, int32, uint8, uint16, uint32, sfloat, and dfloat): WebSphere DataStage
assumes that numeric fields are represented as text.
– For the time data type: text specifies that the field represents time in the text-based form
%hh:%nn:%ss or in the default date format if you have defined a new one on an NLS system (see
WebSphere DataStage NLS Guide).
– For the timestamp data type: text specifies a text-based timestamp in the form %yyyy-%mm-%dd
%hh:%nn:%ss or in the default date format if you have defined a new one on an NLS system (see
WebSphere DataStage NLS Guide).

Chapter 5. Sequential file stage 95

v Field max width. The maximum number of bytes in a column represented as a string. Enter a number.
This is useful where you are storing numbers as text. If you are using a fixed-width character set, you
can calculate the length exactly. If you are using variable-length character set, calculate an adequate
maximum width for your fields. Applies to fields of all data types except date, time, timestamp, and
raw; and record, subrec, or tagged if they contain at least one field of this type.
v Field width. The number of bytes in a field represented as a string. Enter a number. This is useful
where you are storing numbers as text. If you are using a fixed-width charset, you can calculate the
number of bytes exactly. If it’s a variable length encoding, base your calculation on the width and
frequency of your variable-width characters. Applies to fields of all data types except date, time,
timestamp, and raw; and record, subrec, or tagged if they contain at least one field of this type.
If you specify neither field width nor field max width, numeric fields written as text have the
following number of bytes as their maximum width:
– 8-bit signed or unsigned integers: 4 bytes
– 16-bit signed or unsigned integers: 6 bytes
– 32-bit signed or unsigned integers: 11 bytes
– 64-bit signed or unsigned integers: 21 bytes
– single-precision float: 14 bytes (sign, digit, decimal point, 7 fraction, ″E″, sign, 2 exponent)
– double-precision float: 24 bytes (sign, digit, decimal point, 16 fraction, ″E″, sign, 3 exponent)
v Pad char. This property is ignored for output links.
v Character set. Specifies the character set. Choose from ASCII or EBCDIC. The default is ASCII. Applies
to all data types except raw and ustring and record, subrec, or tagged containing no fields other than
raw or ustring.

String

These properties are applied to columns with a string data type, unless overridden at column level.
v Export EBCDIC as ASCII. Not relevant for output links.
v Import ASCII as EBCDIC. Select this to specify that ASCII characters are read as EBCDIC characters.

Decimal

These properties are applied to columns with a decimal data type unless overridden at column level.
v Allow all zeros. Specifies whether to treat a packed decimal column containing all zeros (which is
normally illegal) as a valid representation of zero. Select Yes or No. The default is No.
v Decimal separator. Specify the ASCII character that acts as the decimal separator (period by default).
v Packed. Select an option to specify what the decimal columns contain, choose from:
– Yes to specify that the decimal fields contain data in packed decimal format (the default). This has
the following sub-properties:
Check. Select Yes to verify that data is packed, or No to not verify.
Signed. Select Yes to use the existing sign when reading decimal fields. Select No to write a positive
sign (0xf) regardless of the fields’ actual sign value.
– No (separate) to specify that they contain unpacked decimal with a separate sign byte. This has the
following sub-property:
Sign Position. Choose leading or trailing as appropriate.
– No (zoned) to specify that they contain an unpacked decimal in either ASCII or EBCDIC text. This
has the following sub-property:
Sign Position. Choose leading or trailing as appropriate.
– No (overpunch) to specify that the field has a leading or end byte that contains a character which
specifies both the numeric value of that byte and whether the number as a whole is negatively or
positively signed. This has the following sub-property:

96 Parallel Job Developer Guide

 Sign Position. Choose leading or trailing as appropriate.
v Precision. Specifies the precision of a packed decimal. Enter a number.
v Rounding. Specifies how to round the source field to fit into the destination decimal when reading a
source field to a decimal. Choose from:
– up (ceiling). Truncate source column towards positive infinity. This mode corresponds to the IEEE
754 Round Up mode. For example, 1.4 becomes 2, -1.6 becomes -1.
– down (floor). Truncate source column towards negative infinity. This mode corresponds to the IEEE
754 Round Down mode. For example, 1.6 becomes 1, -1.4 becomes -2.
– nearest value. Round the source column towards the nearest representable value. This mode
corresponds to the COBOL ROUNDED mode. For example, 1.4 becomes 1, 1.5 becomes 2, -1.4
becomes -1, -1.5 becomes -2.
– truncate towards zero. This is the default. Discard fractional digits to the right of the right-most
fractional digit supported by the destination, regardless of sign. For example, if the destination is an
integer, all fractional digits are truncated. If the destination is another decimal with a smaller scale,
truncate to the scale size of the destination decimal. This mode corresponds to the COBOL
INTEGER-PART function. Using this method 1.6 becomes 1, -1.6 becomes -1.
v Scale. Specifies the scale of a source packed decimal.

Numeric

These properties apply to integer and float fields unless overridden at column level.
v C_format. Perform non-default conversion of data from string data to a integer or floating-point. This
property specifies a C-language format string used for reading integer or floating point strings. This is
passed to sscanf(). For example, specifying a C-format of %x and a field width of 8 ensures that a 32-bit
integer is formatted as an 8-byte hexadecimal string.
v In_format. Format string used for conversion of data from string to integer or floating-point data This
is passed to sscanf(). By default, WebSphere DataStage invokes the C sscanf() function to convert a
numeric field formatted as a string to either integer or floating point data. If this function does not
output data in a satisfactory format, you can specify the in_format property to pass formatting
arguments to sscanf().
v Out_format. This property is not relevant for output links.

Date

These properties are applied to columns with a date data type unless overridden at column level. All of
these are incompatible with a Data Format setting of Text.
v Days since. Dates are written as a signed integer containing the number of days since the specified
date. Enter a date in the form %yyyy-%mm-%dd or in the default date format if you have defined a
new one on an NLS system (see WebSphere DataStage NLS Guide).
v Format string. The string format of a date. By default this is %yyyy-%mm-%dd. For details about the
format, see .
v Is Julian. Select this to specify that dates are written as a numeric value containing the Julian day. A
Julian day specifies the date as the number of days from 4713 BCE January 1, 12:00 hours (noon) GMT.

Time

These properties are applied to columns with a time data type unless overridden at column level. All of
these are incompatible with a Data Format setting of Text.
v Format string. Specifies the format of columns representing time as a string. By default this is
%hh-%mm-%ss. For details about the format, see “Time formats” on page 33
v Is midnight seconds. Select this to specify that times are written as a binary 32-bit integer containing
the number of seconds elapsed from the previous midnight.

Chapter 5. Sequential file stage 97

Timestamp

These properties are applied to columns with a timestamp data type unless overridden at column level.
v Format string. Specifies the format of a column representing a timestamp as a string. The format
combines the format for date strings and time strings. See “Date formats” on page 30 and “Time
formats” on page 33.

Using RCP With Sequential Stages

Runtime column propagation (RCP) allows WebSphere DataStage to be flexible about the columns you
define in a job. If RCP is enabled for a project, you can just define the columns you are interested in
using in a job, but ask WebSphere DataStage to propagate the other columns through the various stages.
So such columns can be extracted from the data source and end up on your data target without explicitly
being operated on in between.

Sequential files, unlike most other data sources, do not have inherent column definitions, and so
WebSphere DataStage cannot always tell where there are extra columns that need propagating. You can
only use RCP on sequential files if you have used the Schema File property (see ″Schema File″ on page
Schema File and on page Schema File) to specify a schema which describes all the columns in the
sequential file. You need to specify the same schema file for any similar stages in the job where you want
to propagate columns. Stages that will require a schema file are:
v Sequential File
v File Set
v External Source
v External Target
v Column Import
v Column Export

98 Parallel Job Developer Guide

Chapter 6. File set stage
The File Set stage is a file stage. It allows you to read data from or write data to a file set. The stage can
have a single input link, a single output link, and a single rejects link. It only executes in parallel mode.

What is a file set? WebSphere DataStage can generate and name exported files, write them to their
destination, and list the files it has generated in a file whose extension is, by convention, .fs. The data
files and the file that lists them are called a file set. This capability is useful because some operating
systems impose a 2 GB limit on the size of a file and you need to distribute files among nodes to prevent
overruns.

The amount of data that can be stored in each destination data file is limited by the characteristics of the
file system and the amount of free disk space available. The number of files created by a file set depends
on:
v The number of processing nodes in the default node pool
v The number of disks in the export or default disk pool connected to each processing node in the
default node pool
v The size of the partitions of the data set

The File Set stage enables you to create and write to file sets, and to read data back from file sets.

Unlike data sets, file sets carry formatting information that describe the format of the files to be read or
written.

When you edit a File Set stage, the File Set stage editor appears. This is based on the generic stage editor
described in″Stage Editors.″

The stage editor has up to three pages, depending on whether you are reading or writing a file set:
v Stage Page. This is always present and is used to specify general information about the stage.

© Copyright IBM Corp. 2006 99

v Input Page. This is present when you are writing to a file set. This is where you specify details about
the file set being written to.
v Output Page. This is present when you are reading from a file set. This is where you specify details
about the file set being read from.

There are one or two special points to note about using runtime column propagation (RCP) with File Set
stages. See ″Using RCP With File Set Stages″ for details.

Must do’s
WebSphere DataStage has many defaults which means that it can be very easy to include File Set stages
in a job. This section specifies the minimum steps to take to get a File Set stage functioning. WebSphere
DataStage provides a versatile user interface, and there are many shortcuts to achieving a particular end,
this section describes the basic methods, you will learn where the shortcuts are when you get familiar
with the product.

The steps required depend on whether you are using the File Set stage to read or write a file.

Writing to a file
v In the Input Link Properties Tab specify the pathname of the file set being written to. The other
properties all have default values, which you can change or not as required.
v In the Input Link Format Tab specify format details for the file set you are writing to, or accept the
defaults (variable length columns enclosed in double quotes and delimited by commas, rows delimited
with UNIX newlines).
v Ensure column meta data has been specified for the file set.

Reading from a file

v In the Output Link Properties Tab specify the pathname of the file set being read from. The other
properties all have default values, which you can change or not as required.
v In the Output Link Format Tab specify format details for the file set you are reading from, or accept
the defaults (variable length columns enclosed in double quotes and delimited by commas, rows
delimited with UNIX newlines).
v Ensure column meta data has been specified for the file set (this can be achieved via a schema file if
required).

Stage page
The General tab allows you to specify an optional description of the stage. The Advanced tab allows you
to specify how the stage executes. The NLS Map tab appears if you have NLS enabled on your system, it
allows you to specify a character set map for the stage.

Advanced tab
This tab allows you to specify the following:
v Execution Mode. This is set to parallel and cannot be changed.
v Combinability mode. This is Auto by default, which allows WebSphere DataStage to combine the
operators that underlie parallel stages so that they run in the same process if it is sensible for this type
of stage.
v Preserve partitioning. You can select Set or Clear. If you select Set, file set read operations will request
that the next stage preserves the partitioning as is (it is ignored for file set write operations).

100 Parallel Job Developer Guide

v Node pool and resource constraints. Select this option to constrain parallel execution to the node pool
or pools and/or resource pool or pools specified in the grid. The grid allows you to make choices from
drop down lists populated from the Configuration file.
v Node map constraint. Select this option to constrain parallel execution to the nodes in a defined node
map. You can define a node map by typing node numbers into the text box or by clicking the browse
button to open the Available Nodes dialog box and selecting nodes from there. You are effectively
defining a new node pool for this stage (in addition to any node pools defined in the Configuration
file).

NLS Map tab

The NLS Map tab allows you to define a character set map for the File Set stage. This overrides the
default character set map set for the project or the job. You can specify that the map be supplied as a job
parameter if required. You can also select Allow per-column mapping. This allows character set maps to
be specified for individual columns within the data processed by the File Set stage An extra property,
NLS Map, appears in the Columns grid in the Columns tab, but note that only ustring data types allow
you to set an NLS map value (see ″Data Types″ ).

Input page
The Input page allows you to specify details about how the File Set stage writes data to a file set. The
File Set stage can have only one input link.

The General tab allows you to specify an optional description of the input link. The Properties tab allows
you to specify details of exactly what the link does. The Partitioning tab allows you to specify how
incoming data is partitioned before being written to the file set. The Formats tab gives information about
the format of the files being written. The Columns tab specifies the column definitions of the data. The
Advanced tab allows you to change the default buffering settings for the input link.

Details about File Set stage properties, partitioning, and formatting are given in the following sections.
See ″Stage Editors,″ for a general description of the other tabs.

Input link properties tab

The Properties tab allows you to specify properties for the input link. These dictate how incoming data is
written and to what file set. Some of the properties are mandatory, although many have default settings.
Properties without default settings appear in the warning color (red by default) and turn black when you
supply a value for them.

The following table gives a quick reference list of the properties and their attributes. A more detailed
description of each property follows.

Category/
Property Values Default Mandatory? Repeats? Dependent of
Target/File Set pathname N/A Y N N/A
Target/File Set Create (Error if Overwrite Y N N/A
Update Policy exists)
/Overwrite/Use
Existing (Discard
records)/ Use
Existing (Discard
schema &
records)
Target/File Set Write/Omit Write Y N N/A
Schema policy

Chapter 6. File set stage 101

Category/
Property Values Default Mandatory? Repeats? Dependent of
Options/Cleanup True/False True Y N N/A
on Failure
Options/Single True/False False Y N N/A
File Per Partition.
Options/Reject Continue/Fail/ Continue Y N N/A
Mode Save
Options/Diskpool string N/A N N N/A
Options/File string export.username N N N/A
Prefix
Options/File string none N N N/A
Suffix
Options/ number MB N/A N N N/A
Maximum File
Size
Options/Schema pathname N/A N N N/A
File

Target category
File set

This property defines the file set that the incoming data will be written to. You can type in a pathname
of, or browse for a file set descriptor file (by convention ending in .fs).

File set update policy

Specifies what action will be taken if the file set you are writing to already exists. Choose from:
v Create (Error if exists)
v Overwrite
v Use Existing (Discard records)
v Use Existing (Discard schema & records)

The default is Overwrite.

File set schema policy

Specifies whether the schema should be written to the file set. Choose from Write or Omit. The default is
Write.

Options category
Cleanup on failure

This is set to True by default and specifies that the stage will delete any partially written files if the stage
fails for any reason. Set this to False to specify that partially written files should be left.

Single file per partition

Set this to True to specify that one file is written for each partition. The default is False.

102 Parallel Job Developer Guide

Reject mode

Allows you to specify behavior if a record fails to be written for some reason. Choose from Continue to
continue operation and discard any rejected rows, Fail to cease reading if any rows are rejected, or Save
to send rejected rows down a reject link. Defaults to Continue.

Diskpool

This is an optional property. Specify the name of the disk pool into which to write the file set. You can
also specify a job parameter.

File prefix

This is an optional property. Specify a prefix for the name of the file set components. If you do not
specify a prefix, the system writes the following: export.username, where username is your login. You can
also specify a job parameter.

File suffix

This is an optional property. Specify a suffix for the name of the file set components. The suffix is omitted
by default.

Maximum file size

This is an optional property. Specify the maximum file size in MB. The value must be equal to or greater
than 1.

Schema file

This is an optional property. By default the File Set stage will use the column definitions defined on the
Columns tab and formatting information from the Format tab as a schema for writing the file. You can,
however, specify a file containing a schema instead (note, however, that if you have defined columns on
the Columns tab, you should ensure these match the schema file). Type in a pathname or browse for a
schema file.

Partitioning tab
The Partitioning tab allows you to specify details about how the incoming data is partitioned or collected
before it is written to the file set. It also allows you to specify that the data should be sorted before being
written.

By default the stage partitions in Auto mode. This attempts to work out the best partitioning method
depending on execution modes of current and preceding stages and how many nodes are specified in the
Configuration file.

If the File Set stage is operating in sequential mode, it will first collect the data before writing it to the file
using the default Auto collection method.

The Partitioning tab allows you to override this default behavior. The exact operation of this tab depends
on:
v Whether the File Set stage is set to execute in parallel or sequential mode.
v Whether the preceding stage in the job is set to execute in parallel or sequential mode.

If the File Set stage is set to execute in parallel, then you can set a partitioning method by selecting from
the Partition type drop-down list. This will override any current partitioning.

Chapter 6. File set stage 103

If the File Set stage is set to execute in sequential mode, but the preceding stage is executing in parallel,
then you can set a collection method from the Collector type drop-down list. This will override the
default collection method.

The following partitioning methods are available:

v (Auto). WebSphere DataStage attempts to work out the best partitioning method depending on
execution modes of current and preceding stages and how many nodes are specified in the
Configuration file. This is the default method for the File Set stage.
v Entire. Each file written to receives the entire data set.
v Hash. The records are hashed into partitions based on the value of a key column or columns selected
from the Available list.
v Modulus. The records are partitioned using a modulus function on the key column selected from the
Available list. This is commonly used to partition on tag fields.
v Random. The records are partitioned randomly, based on the output of a random number generator.
v Round Robin. The records are partitioned on a round robin basis as they enter the stage.
v Same. Preserves the partitioning already in place.
v DB2. Replicates the DB2 partitioning method of a specific DB2 table. Requires extra properties to be
set. Access these properties by clicking the properties button.
v Range. Divides a data set into approximately equal size partitions based on one or more partitioning
keys. Range partitioning is often a preprocessing step to performing a total sort on a data set. Requires
extra properties to be set. Access these properties by clicking the properties button.

The following Collection methods are available:

v (Auto). This is the default method for the File Set stage. Normally, when you are using Auto mode,
WebSphere DataStage will eagerly read any row from any input partition as it becomes available.
v Ordered. Reads all records from the first partition, then all records from the second partition, and so
on.
v Round Robin. Reads a record from the first input partition, then from the second partition, and so on.
After reaching the last partition, the operator starts over.
v Sort Merge. Reads records in an order based on one or more columns of the record. This requires you
to select a collecting key column from the Available list.
The Partitioning tab also allows you to specify that data arriving on the input link should be sorted
before being written to the file or files. The sort is always carried out within data partitions. If the
stage is partitioning incoming data the sort occurs after the partitioning. If the stage is collecting data,
the sort occurs before the collection. The availability of sorting depends on the partitioning or
collecting method chosen (it is not available with the Auto methods).

Select the check boxes as follows:

v Perform Sort. Select this to specify that data coming in on the link should be sorted. Select the column
or columns to sort on from the Available list.
v Stable. Select this if you want to preserve previously sorted data sets. This is the default.
v Unique. Select this to specify that, if multiple records have identical sorting key values, only one
record is retained. If stable sort is also set, the first record is retained.

If NLS is enabled an additional button opens a dialog box allowing you to select a locale specifying the
collate convention for the sort.

You can also specify sort direction, case sensitivity, whether sorted as ASCII or EBCDIC, and whether null
columns will appear first or last for each column. Where you are using a keyed partitioning method, you
can also specify whether the column is used as a key for sorting, for partitioning, or for both. Select the
column in the Selected list and right-click to invoke the shortcut menu.

104 Parallel Job Developer Guide

Input link format tab
The Format tab allows you to supply information about the format of the files in the file set to which you
are writing. The tab has a similar format to the Properties tab and is described on page Format Tab.

If you do not alter any of the Format settings, the File Set stage will produce files of the following format:
v Files comprise variable length columns contained within double quotes.
v All columns are delimited by a comma, except for the final column in a row.
v Rows are delimited by a UNIX newline.

You can use the Format As item from the shortcut menu in the Format tab to quickly change to a
fixed-width column format, using DOS newlines as row delimiters, or producing a COBOL format file.

To change individual properties, select a property type from the main tree then add the properties you
want to set to the tree structure by clicking on them in the Available properties to set window. You can
then set a value for that property in the Property Value box. Pop-up help for each of the available
properties appears if you hover the mouse pointer over it.

Any property that you set on this tab can be overridden at the column level by setting properties for
individual columns on the Edit Column Metadata dialog box (see page Columns Tab).

This description uses the terms ″record″ and ″row″ and ″field″ and ″column″ interchangeably.

The following sections list the Property types and properties available for each type.

Record level

These properties define details about how data records are formatted in the flat file. Where you can enter
a character, this can usually be an ASCII character or a multi-byte Unicode character (if you have NLS
enabled). The available properties are:

Fill char

Specify an ASCII character or a value in the range 0 to 255. You can also choose Space or Null from a
drop-down list. This character is used to fill any gaps in a written record caused by column positioning
properties. Set to 0 by default (which is the NULL character). For example, to set it to space you could
also type in the space character or enter 32. Note that this value is restricted to one byte, so you cannot
specify a multi-byte Unicode character.

Final delimiter string

Specify a string to be written after the last column of a record in place of the column delimiter. Enter one
or more characters, this precedes the record delimiter if one is used. Mutually exclusive with Final
delimiter, which is the default. For example, if you set Delimiter to comma and Final delimiter string to `,
` (comma space - you do not need to enter the inverted commas) all fields are delimited by a comma,
except the final field, which is delimited by a comma followed by an ASCII space character.

Final delimiter

Specify a single character to be written after the last column of a record in place of the field delimiter.
Type a character or select one of whitespace, end, none, null, tab, or comma. See the following diagram
for an illustration.
v whitespace. The last column of each record will not include any trailing white spaces found at the end
of the record.

Chapter 6. File set stage 105

v end. The last column of each record does not include the field delimiter. This is the default setting.
v none. The last column of each record does not have a delimiter; used for fixed-width fields.
v null. The last column of each record is delimited by the ASCII null character.
v comma. The last column of each record is delimited by the ASCII comma character.
v tab. The last column of each record is delimited by the ASCII tab character.
record delimiter

Field , Field , Field , Last field nl

Final delimiter = end

field delimiter

Field , Field , Field , Last field , nl

Final delimiter = comma

When writing, a space is now inserted after every field except the last in the record. Previously, a space
was inserted after every field including the last. (If you want to revert to the pre-release 7.5 behavior of
inserting a space after the last field, set the APT_FINAL_DELIM_COMPATIBLE environment variable.

Intact

The intact property specifies an identifier of a partial schema. A partial schema specifies that only the
column(s) named in the schema can be modified by the stage. All other columns in the row are passed
through unmodified. The file containing the partial schema is specified in the Schema File property on
the Properties tab. This property has a dependent property, Check intact, but this is not relevant to input
links.

Record delimiter string

Specify a string to be written at the end of each record. Enter one or more characters. This is mutually
exclusive with Record delimiter, which is the default, record type and record prefix.

Record delimiter

Specify a single character to be written at the end of each record. Type a character or select one of the
following:
v UNIX Newline (the default)
v null

(To implement a DOS newline, use the Record delimiter string property set to ″\R\N″ or chooseFormat
as → DOS line terminator from the shortcut menu.)

Note: Record delimiter is mutually exclusive with Record delimiter string, Record prefix, and Record
type.

Record length

Select Fixed where fixed length fields are being written. WebSphere DataStage calculates the appropriate
length for the record. Alternatively specify the length of fixed records as number of bytes. This is not

106 Parallel Job Developer Guide

used by default (default files are comma-delimited). The record is padded to the specified length with
either zeros or the fill character if one has been specified.

Record Prefix

Specifies that a variable-length record is prefixed by a 1-, 2-, or 4-byte length prefix. It is set to 1 by
default. This is mutually exclusive with Record delimiter, which is the default, and record delimiter string
and record type.

Record type

Specifies that data consists of variable-length blocked records (varying) or implicit records (implicit). If
you choose the implicit property, data is written as a stream with no explicit record boundaries. The end
of the record is inferred when all of the columns defined by the schema have been parsed. The varying
property allows you to specify one of the following IBM blocked or spanned formats: V, VB, VS, VBS, or
VR.

This property is mutually exclusive with Record length, Record delimiter, Record delimiter string, and
Record prefix and by default is not used.

Field defaults

Defines default properties for columns written to the file or files. These are applied to all columns
written, but can be overridden for individual columns from the Columns tab using the Edit Column
Metadata dialog box. Where you can enter a character, this can usually be an ASCII character or a
multi-byte Unicode character (if you have NLS enabled). The available properties are:
v Actual field length. Specifies the number of bytes to fill with the Fill character when a field is
identified as null. When WebSphere DataStage identifies a null field, it will write a field of this length
full of Fill characters. This is mutually exclusive with Null field value.
v Delimiter. Specifies the trailing delimiter of all fields in the record. Type an ASCII character or select
one of whitespace, end, none, null, comma, or tab.
– whitespace. Whitespace characters at the end of a column are ignored, i.e., are not treated as part of
the column.
– end. The end of a field is taken as the delimiter, i.e., there is no separate delimiter. This is not the
same as a setting of `None’ which is used for fields with fixed-width columns.
– none. No delimiter (used for fixed-width).
– null. ASCII Null character is used.
– comma. ASCII comma character is used.
– tab. ASCII tab character is used.
v Delimiter string. Specify a string to be written at the end of each field. Enter one or more characters.
This is mutually exclusive with Delimiter, which is the default. For example, specifying `, ` (comma
space - you do not need to enter the inverted commas) would have each field delimited by `, ` unless
overridden for individual fields.
v Null field length. The length in bytes of a variable-length field that contains a null. When a
variable-length field is written, WebSphere DataStage writes a length value of null field length if the
field contains a null. This property is mutually exclusive with null field value.
v Null field value. Specifies the value written to null field if the source is set to null. Can be a number,
string, or C-type literal escape character. For example, you can represent a byte value by \ooo, where
each o is an octal digit 0 - 7 and the first o is < 4, or by \xhh, where each h is a hexadecimal digit 0 - F.
You must use this form to encode non-printable byte values.
This property is mutually exclusive with Null field length and Actual length. For a fixed width data
representation, you can use Pad char (from the general section of Type defaults) to specify a repeated
trailing character if the value you specify is shorter than the fixed width of the field.

Chapter 6. File set stage 107

v Prefix bytes. Specifies that each column in the data file is prefixed by 1, 2, or 4 bytes containing, as a
binary value, either the column’s length or the tag value for a tagged field.
You can use this option with variable-length fields. Variable-length fields can be either delimited by a
character or preceded by a 1-, 2-, or 4-byte prefix containing the field length. WebSphere DataStage
inserts the prefix before each field.
This property is mutually exclusive with the Delimiter, Quote, and Final Delimiter properties, which
are used by default.
v Print field. This property is not relevant for input links.
v Quote. Specifies that variable length fields are enclosed in single quotes, double quotes, or another
character or pair of characters. Choose Single or Double, or enter a character. This is set to double
quotes by default.
When writing, WebSphere DataStage inserts the leading quote character, the data, and a trailing quote
character. Quote characters are not counted as part of a field’s length.
v Vector prefix. For fields that are variable length vectors, specifies a 1-, 2-, or 4-byte prefix containing
the number of elements in the vector. You can override this default prefix for individual vectors.
Variable-length vectors must use either a prefix on the vector or a link to another field in order to
specify the number of elements in the vector. If the variable length vector has a prefix, you use this
property to indicate the prefix length. WebSphere DataStage inserts the element count as a prefix of
each variable-length vector field. By default, the prefix length is assumed to be one byte.

Type defaults

These are properties that apply to all columns of a specific data type unless specifically overridden at the
column level. They are divided into a number of subgroups according to data type.

General

These properties apply to several data types (unless overridden at column level):
v Byte order. Specifies how multiple byte data types (except string and raw data types) are ordered.
Choose from:
– little-endian. The high byte is on the right.
– big-endian. The high byte is on the left.
– native-endian. As defined by the native format of the machine. This is the default.
v Data Format. Specifies the data representation format of a field. Applies to fields of all data types
except string, ustring, and raw and to record, subrec or tagged fields containing at least one field that
is neither string nor raw. Choose from:
– binary
– text (the default)
A setting of binary has different meanings when applied to different data types:
– For decimals, binary means packed.
– For other numerical data types, binary means ″not text″.
– For dates, binary is equivalent to specifying the julian property for the date field.
– For time, binary is equivalent to midnight_seconds.
– For timestamp, binary specifies that the first integer contains a Julian day count for the date portion
of the timestamp and the second integer specifies the time portion of the timestamp as the number
of seconds from midnight. A binary timestamp specifies that two 32-but integers are written.
By default data is formatted as text, as follows:
– For the date data type, text specifies that the data to be written contains a text-based date in the
form %yyyy-%mm-%dd or in the default date format if you have defined a new one on an NLS
system (see WebSphere DataStage NLS Guide).

108 Parallel Job Developer Guide

 – For the decimal data type: a field represents a decimal in a string format with a leading space or ’-’
followed by decimal digits with an embedded decimal point if the scale is not zero. The destination
string format is: [+ | -]ddd.[ddd] and any precision and scale arguments are ignored.
– For numeric fields (int8, int16, int32, uint8, uint16, uint32, sfloat, and dfloat): WebSphere DataStage
assumes that numeric fields are represented as text.
– For the time data type: text specifies that the field represents time in the text-based form
%hh:%nn:%ss or in the default date format if you have defined a new one on an NLS system (see
WebSphere DataStage NLS Guide).
– For the timestamp data type: text specifies a text-based timestamp in the form %yyyy-%mm-%dd
%hh:%nn:%ss or in the default date format if you have defined a new one on an NLS system (see
WebSphere DataStage NLS Guide).
v Field max width. The maximum number of bytes in a column represented as a string. Enter a number.
This is useful where you are storing numbers as text. If you are using a fixed-width character set, you
can calculate the length exactly. If you are using variable-length character set, calculate an adequate
maximum width for your fields. Applies to fields of all data types except date, time, timestamp, and
raw; and record, subrec, or tagged if they contain at least one field of this type.
v Field width. The number of bytes in a field represented as a string. Enter a number. This is useful
where you are storing numbers as text. If you are using a fixed-width charset, you can calculate the
number of bytes exactly. If it’s a variable length encoding, base your calculation on the width and
frequency of your variable-width characters. Applies to fields of all data types except date, time,
timestamp, and raw; and record, subrec, or tagged if they contain at least one field of this type.
If you specify neither field width nor field max width, numeric fields written as text have the
following number of bytes as their maximum width:
– 8-bit signed or unsigned integers: 4 bytes
– 16-bit signed or unsigned integers: 6 bytes
– 32-bit signed or unsigned integers: 11 bytes
– 64-bit signed or unsigned integers: 21 bytes
– single-precision float: 14 bytes (sign, digit, decimal point, 7 fraction, ″E″, sign, 2 exponent)
– double-precision float: 24 bytes (sign, digit, decimal point, 16 fraction, ″E″, sign, 3 exponent)
v Pad char. Specifies the pad character used when strings or numeric values are written to an external
string representation. Enter a character (single-byte for strings, can be multi-byte for ustrings) or choose
null or space. The pad character is used when the external string representation is larger than required
to hold the written field. In this case, the external string is filled with the pad character to its full
length. Space is the default. Applies to string, ustring, and numeric data types and record, subrec, or
tagged types if they contain at least one field of this type.
v Character set. Specifies the character set. Choose from ASCII or EBCDIC. The default is ASCII. Applies
to all data types except raw and ustring and record, subrec, or tagged containing no fields other than
raw or ustring.

String

These properties are applied to columns with a string data type, unless overridden at column level.
v Export EBCDIC as ASCII. Select this to specify that EBCDIC characters are written as ASCII
characters. Applies to fields of the string data type and record, subrec, or tagged fields if they contain
at least one field of this type.
v Import ASCII as EBCDIC. Not relevant for input links.
For ASCII-EBCDIC and EBCDIC-ASCII conversion tables, see WebSphere DataStage Developer’s Help.

Decimal

These properties are applied to columns with a decimal data type unless overridden at column level.

Chapter 6. File set stage 109

v Allow all zeros. Specifies whether to treat a packed decimal column containing all zeros (which is
normally illegal) as a valid representation of zero. Select Yes or No. The default is No.
v Decimal separator. Specify the ASCII character that acts as the decimal separator (period by default).
v Packed. Select an option to specify what the decimal columns contain, choose from:
– Yes to specify that the decimal columns contain data in packed decimal format (the default). This
has the following sub-properties:
Check. Select Yes to verify that data is packed, or No to not verify.
Signed. Select Yes to use the existing sign when writing decimal columns. Select No to write a
positive sign (0xf) regardless of the columns’ actual sign value.
– No (separate) to specify that they contain unpacked decimal with a separate sign byte. This has the
following sub-property:
Sign Position. Choose leading or trailing as appropriate.
– No (zoned) to specify that they contain an unpacked decimal in either ASCII or EBCDIC text. This
has the following sub-property:
Sign Position. Choose leading or trailing as appropriate.
– No (overpunch) to specify that the field has a leading or end byte that contains a character which
specifies both the numeric value of that byte and whether the number as a whole is negatively or
positively signed. This has the following sub-property:
Sign Position. Choose leading or trailing as appropriate.
v Precision. Specifies the precision where a decimal column is written in text format. Enter a number.
When a decimal is written to a string representation, WebSphere DataStage uses the precision and scale
defined for the source decimal field to determine the length of the destination string. The precision and
scale properties override this default. When they are defined, WebSphere DataStage truncates or pads
the source decimal to fit the size of the destination string. If you have also specified the field width
property, WebSphere DataStage truncates or pads the source decimal to fit the size specified by field
width.
v Rounding. Specifies how to round a decimal column when writing it. Choose from:
– up (ceiling). Truncate source column towards positive infinity. This mode corresponds to the IEEE
754 Round Up mode. For example, 1.4 becomes 2, -1.6 becomes -1.
– down (floor). Truncate source column towards negative infinity. This mode corresponds to the IEEE
754 Round Down mode. For example, 1.6 becomes 1, -1.4 becomes -2.
– nearest value. Round the source column towards the nearest representable value. This mode
corresponds to the COBOL ROUNDED mode. For example, 1.4 becomes 1, 1.5 becomes 2, -1.4
becomes -1, -1.5 becomes -2.
– truncate towards zero. This is the default. Discard fractional digits to the right of the right-most
fractional digit supported by the destination, regardless of sign. For example, if the destination is an
integer, all fractional digits are truncated. If the destination is another decimal with a smaller scale,
truncate to the scale size of the destination decimal. This mode corresponds to the COBOL
INTEGER-PART function. Using this method 1.6 becomes 1, -1.6 becomes -1.
v Scale. Specifies how to round a source decimal when its precision and scale are greater than those of
the destination. By default, when the WebSphere DataStage writes a source decimal to a string
representation, it uses the precision and scale defined for the source decimal field to determine the
length of the destination string. You can override the default by means of the precision and scale
properties. When you do, WebSphere DataStage truncates or pads the source decimal to fit the size of
the destination string. If you have also specified the field width property, WebSphere DataStage
truncates or pads the source decimal to fit the size specified by field width.

Numeric

These properties apply to integer and float fields unless overridden at column level.

110 Parallel Job Developer Guide

v C_format. Perform non-default conversion of data from integer or floating-point data to a string. This
property specifies a C-language format string used for writing integer or floating point strings. This is
passed to sprintf(). For example, specifying a C-format of %x and a field width of 8 ensures that
integers are written as 8-byte hexadecimal strings.
v In_format. This property is not relevant for input links..
v Out_format. Format string used for conversion of data from integer or floating-point data to a string.
This is passed to sprintf(). By default, WebSphere DataStage invokes the C sprintf() function to convert a
numeric field formatted as either integer or floating point data to a string. If this function does not
output data in a satisfactory format, you can specify the out_format property to pass formatting
arguments to sprintf().

Date

These properties are applied to columns with a date data type unless overridden at column level. All of
these are incompatible with a Data Format setting of Text.
v Days since. Dates are written as a signed integer containing the number of days since the specified
date. Enter a date in the form %yyyy-%mm-%dd or in the default date format if you have defined a
new one on an NLS system (see WebSphere DataStage NLS Guide).
v Format string. The string format of a date. By default this is %yyyy-%mm-%dd. For details about the
format, see .
v Is Julian. Select this to specify that dates are written as a numeric value containing the Julian day. A
Julian day specifies the date as the number of days from 4713 BCE January 1, 12:00 hours (noon) GMT.

Time

These properties are applied to columns with a time data type unless overridden at column level. All of
these are incompatible with a Data Format setting of Text.
v Format string. Specifies the format of columns representing time as a string. For details about the
format, see “Time formats” on page 33
v Is midnight seconds. Select this to specify that times are written as a binary 32-bit integer containing
the number of seconds elapsed from the previous midnight.

Timestamp

These properties are applied to columns with a timestamp data type unless overridden at column level.
v Format string. Specifies the format of a column representing a timestamp as a string. Defaults to
%yyyy-%mm-%dd %hh:%nn:%ss. The format combines the format for date strings and time strings. See
“Date formats” on page 30 and “Time formats” on page 33.

Output page
The Output page allows you to specify details about how the File Set stage reads data from a file set. The
File Set stage can have only one output link. It can also have a single reject link, where rows that have
failed to be written or read for some reason can be sent. The Output name drop-down list allows you to
choose whether you are looking at details of the main output link (the stream link) or the reject link.

The General tab allows you to specify an optional description of the output link. The Properties tab
allows you to specify details of exactly what the link does. The Formats tab gives information about the
format of the files being read. The Columns tab specifies the column definitions of the data. The
Advanced tab allows you to change the default buffering settings for the output link.

Details about File Set stage properties and formatting are given in the following sections. See Chapter 3,
“Stage editors,” on page 37, ″Stage Editors,″ for a general description of the other tabs.

Chapter 6. File set stage 111

Output link properties tab
The Properties tab allows you to specify properties for the output link. These dictate how incoming data
is read from files in the file set. Some of the properties are mandatory, although many have default
settings. Properties without default settings appear in the warning color (red by default) and turn black
when you supply a value for them.

The following table gives a quick reference list of the properties and their attributes. A more detailed
description of each property follows.

Category/
Property Values Default Mandatory? Repeats? Dependent of
Source/File Set pathname N/A Y N N/A
Options/Keep file True/False False Y N N/A
Partitions
Options/Reject Continue/Fail/ Continue Y N N/A
Mode Save
Options/Report Yes/No Yes Y N N/A
Progress
Options/Filter command N/A N N N/A
Options/Schema pathname N/A N N N/A
File
Options/Use True/False False Y N N/A
Schema Defined
in File Set
Options/File column name fileNameColumn N N N/A
Name Column

Source category
File set

This property defines the file set that the data will be read from. You can type in a pathname of, or
browse for, a file set descriptor file (by convention ending in .fs).

Options category
Keep file partitions

Set this to True to partition the read data set according to the organization of the input file(s). So, for
example, if you are reading three files you will have three partitions. Defaults to False.

Reject mode

Allows you to specify behavior for read rows that do not match the expected schema. Choose from
Continue to continue operation and discard any rejected rows, Fail to cease reading if any rows are
rejected, or Save to send rejected rows down a reject link. Defaults to Continue.

Report progress

Choose Yes or No to enable or disable reporting. By default the stage displays a progress report at each
10% interval when it can ascertain file size. Reporting occurs only if the file is greater than 100 KB,
records are fixed length, and there is no filter on the file.

112 Parallel Job Developer Guide

Filter

This is an optional property. You can use this to specify that the data is passed through a filter program
after being read from the files. Specify the filter command, and any required arguments, in the Property
Value box.

Schema file

This is an optional property. By default the File Set stage will use the column definitions defined on the
Columns and Format tabs as a schema for reading the file. You can, however, specify a file containing a
schema instead (note, however, that if you have defined columns on the Columns tab, you should ensure
these match the schema file). Type in a pathname or browse for a schema file. This property is mutually
exclusive with Use Schema Defined in File Set.

Use schema defined in file set

When you create a file set you have an option to save the schema along with it. When you read the file
set you can use this schema in preference to the column definitions by setting this property to True. This
property is mutually exclusive with Schema File.

File name column

This is an optional property. It adds an extra column of type VarChar to the output of the stage,
containing the pathname of the file the record is read from. You should also add this column manually to
the Columns definitions to ensure that the column is not dropped if you are not using runtime column
propagation, or it is turned off at some point.

Reject link properties

You cannot change the properties of a Reject link. The Properties tab for a reject link is blank.

Similarly, you cannot edit the column definitions for a reject link. For writing file sets, the link uses the
column definitions for the input link. For reading file sets, the link uses a single column called rejected
containing raw data for columns rejected after reading because they do not match the schema.

Output link Format tab

The Format tab allows you to supply information about the format of the flat file or files that you are
writing. The tab has a similar format to the Properties tab.

If you do not alter any of the Format settings, the stage will produce a file of the following format:
v File comprises variable length columns contained within double quotes.
v All columns are delimited by a comma, except for the final column in a row.
v Rows are delimited by a UNIX newline.

You can use the Format As item from the shortcut menu in the Format tab to quickly change to a
fixed-width column format, using DOS newlines as row delimiters, or producing a COBOL format file.

You can use the Defaults button to change your default settings. Use the Format tab to specify your
required settings, then click Defaults → Save current as default. All your sequential files will use your
settings by default from now on. If your requirements change, you can choose Defaults → Reset defaults
from factory settings to go back to the original defaults as described above. Once you have done this,
you then have to click Defaults → Set current from default for the new defaults to take effect.

Chapter 6. File set stage 113

To change individual properties, select a property type from the main tree then add the properties you
want to set to the tree structure by clicking on them in the Available properties to set window. You can
then set a value for that property in the Property Value box. Pop-up help for each of the available
properties appears if you hover the mouse pointer over it.

Any property that you set on this tab can be overridden at the column level by setting properties for
individual columns on the Edit Column Metadata dialog box (see page Columns Tab).

This description uses the terms ″record″ and ″row″ and ″field″ and ″column″ interchangeably.

The following sections list the property types and properties available for each type.

Record level
These properties define details about how data records are formatted in the flat file. Where you can enter
a character, this can usually be an ASCII character or a multi-byte Unicode character (if you have NLS
enabled). The available properties are:
v Fill char. Does not apply to output links.
v Final delimiter string. Specify the string written after the last column of a record in place of the
column delimiter. Enter one or more characters, this precedes the record delimiter if one is used.
Mutually exclusive with Final delimiter, which is the default. For example, if you set Delimiter to
comma and Final delimiter string to `, ` (comma space - you do not need to enter the inverted
commas) all fields are delimited by a comma, except the final field, which is delimited by a comma
followed by an ASCII space character. WebSphere DataStage skips the specified delimiter string when
reading the file.
v Final delimiter. Specify the single character written after the last column of a record in place of the
field delimiter. Type a character or select one of whitespace, end, none, null, tab, or comma. WebSphere
DataStage skips the specified delimiter string when reading the file. See the following diagram for an
illustration.
– whitespace. The last column of each record will not include any trailing white spaces found at the
end of the record.
– end. The last column of each record does not include the field delimiter. This is the default setting.
– none. The last column of each record does not have a delimiter, used for fixed-width fields.
– null. The last column of each record is delimited by the ASCII null character.
– comma. The last column of each record is delimited by the ASCII comma character.
– tab. The last column of each record is delimited by the ASCII tab character.
record delimiter

Field , Field , Field , Last field nl

Final delimiter = end

field delimiter

Field , Field , Field , Last field , nl

Final delimiter = comma
v Intact. The intact property specifies an identifier of a partial schema. A partial schema specifies that
only the column(s) named in the schema can be modified by the stage. All other columns in the row
are passed through unmodified. The file containing the partial schema is specified in the Schema File
property on the Outputs tab. This property has a dependent property:

114 Parallel Job Developer Guide

 – Check intact. Select this to force validation of the partial schema as the file or files are imported.
Note that this can degrade performance.
v Record delimiter string. Specify the string at the end of each record. Enter one or more characters.
This is mutually exclusive with Record delimiter, which is the default, and record type and record
prefix.
v Record delimiter. Specify the single character at the end of each record. Type a character or select one
of the following:
– UNIX Newline (the default)
– null
(To specify a DOS newline, use the Record delimiter string property set to ″\R\N″ or choose Format
as → DOS line terminator from the shortcut menu.)
Record delimiter is mutually exclusive with Record delimiter string, Record prefix, and record type.
v Record length. Select Fixed where fixed length fields are being read. WebSphere DataStage calculates
the appropriate length for the record. Alternatively specify the length of fixed records as number of
bytes. This is not used by default (default files are comma-delimited).
v Record Prefix. Specifies that a variable-length record is prefixed by a 1-, 2-, or 4-byte length prefix. It is
set to 1 by default. This is mutually exclusive with Record delimiter, which is the default, and record
delimiter string and record type.
v Record type. Specifies that data consists of variable-length blocked records (varying) or implicit records
(implicit). If you choose the implicit property, data is written as a stream with no explicit record
boundaries. The end of the record is inferred when all of the columns defined by the schema have
been parsed. The varying property allows you to specify one of the following IBM blocked or spanned
formats: V, VB, VS, VBS, or VR.
This property is mutually exclusive with Record length, Record delimiter, Record delimiter string, and
Record prefix and by default is not used.

Field Defaults

Defines default properties for columns read from the file or files. These are applied to all columns, but
can be overridden for individual columns from the Columns tab using the Edit Column Metadata dialog
box. Where you can enter a character, this can usually be an ASCII character or a multi-byte Unicode
character (if you have NLS enabled). The available properties are:
v Actual field length. Specifies the actual number of bytes to skip if the field’s length equals the setting
of the null field length property.
v Delimiter. Specifies the trailing delimiter of all fields in the record. Type an ASCII character or select
one of whitespace, end, none, null, comma, or tab. WebSphere DataStage skips the delimiter when
reading.
– whitespace. Whitespace characters at the end of a column are ignored, i.e., are not treated as part of
the column.
– end. The end of a field is taken as the delimiter, i.e., there is no separate delimiter. This is not the
same as a setting of `None’ which is used for fields with fixed-width columns.
– none. No delimiter (used for fixed-width).
– null. ASCII Null character is used.
– comma. ASCII comma character is used.
– tab. ASCII tab character is used.
v Delimiter string. Specify the string at the end of each field. Enter one or more characters. This is
mutually exclusive with Delimiter, which is the default. For example, specifying `, ` (comma space -
you do not need to enter the inverted commas) specifies each field is delimited by `, ` unless
overridden for individual fields. WebSphere DataStage skips the delimiter string when reading.

Chapter 6. File set stage 115

v Null field length. The length in bytes of a variable-length field that contains a null. When a
variable-length field is read, a length of null field length in the source field indicates that it contains a
null. This property is mutually exclusive with null field value.
v Null field value. Specifies the value given to a null field if the source is set to null. Can be a number,
string, or C-type literal escape character. For example, you can represent a byte value by \ooo, where
each o is an octal digit 0 - 7 and the first o is < 4, or by \xhh, where each h is a hexadecimal digit 0 - F.
You must use this form to encode non-printable byte values.
This property is mutually exclusive with Null field length and Actual length. For a fixed width data
representation, you can use Pad char (from the general section of Type defaults) to specify a repeated
trailing character if the value you specify is shorter than the fixed width of the field.
v Prefix bytes. You can use this option with variable-length fields. Variable-length fields can be either
delimited by a character or preceded by a 1-, 2-, or 4-byte prefix containing the field length. WebSphere
DataStage reads the length prefix but does not include the prefix as a separate field in the data set it
reads from the file.
This property is mutually exclusive with the Delimiter, Quote, and Final Delimiter properties, which
are used by default.
v Print field. This property is intended for use when debugging jobs. Set it to have WebSphere
DataStage produce a message for every field it reads. The message has the format:
Importing N: D
where:
– N is the field name.
– D is the imported data of the field. Non-printable characters contained in D are prefixed with an
escape character and written as C string literals; if the field contains binary data, it is output in octal
format.
v Quote. Specifies that variable length fields are enclosed in single quotes, double quotes, or another
character or pair of characters. Choose Single or Double, or enter a character. This is set to double
quotes by default.
When reading, WebSphere DataStage ignores the leading quote character and reads all bytes up to but
not including the trailing quote character.
v Vector prefix. For fields that are variable length vectors, specifies that a 1-, 2-, or 4-byte prefix contains
the number of elements in the vector. You can override this default prefix for individual vectors.
Variable-length vectors must use either a prefix on the vector or a link to another field in order to
specify the number of elements in the vector. If the variable length vector has a prefix, you use this
property to indicate the prefix length. WebSphere DataStage reads the length prefix but does not
include it as a separate field in the data set. By default, the prefix length is assumed to be one byte.

Type Defaults

These are properties that apply to all columns of a specific data type unless specifically overridden at the
column level. They are divided into a number of subgroups according to data type.

General

These properties apply to several data types (unless overridden at column level):
v Byte order. Specifies how multiple byte data types (except string and raw data types) are ordered.
Choose from:
– little-endian. The high byte is on the right.
– big-endian. The high byte is on the left.
– native-endian. As defined by the native format of the machine. This is the default.
v Data Format. Specifies the data representation format of a field. Applies to fields of all data types
except string, ustring, and raw and to record, subrec or tagged fields containing at least one field that
is neither string nor raw. Choose from:
116 Parallel Job Developer Guide
 – binary
– text (the default)
A setting of binary has different meanings when applied to different data types:
– For decimals, binary means packed.
– For other numerical data types, binary means ″not text″.
– For dates, binary is equivalent to specifying the julian property for the date field.
– For time, binary is equivalent to midnight_seconds.
– For timestamp, binary specifies that the first integer contains a Julian day count for the date portion
of the timestamp and the second integer specifies the time portion of the timestamp as the number
of seconds from midnight. A binary timestamp specifies that two 32-but integers are written.
By default data is formatted as text, as follows:
– For the date data type, text specifies that the data read, contains a text-based date in the form
%yyyy-%mm-%dd or in the default date format if you have defined a new one on an NLS system
(see WebSphere DataStage NLS Guide).
– For the decimal data type: a field represents a decimal in a string format with a leading space or ’-’
followed by decimal digits with an embedded decimal point if the scale is not zero. The destination
string format is: [+ | -]ddd.[ddd] and any precision and scale arguments are ignored.
– For numeric fields (int8, int16, int32, uint8, uint16, uint32, sfloat, and dfloat): WebSphere DataStage
assumes that numeric fields are represented as text.
– For the time data type: text specifies that the field represents time in the text-based form
%hh:%nn:%ss or in the default date format if you have defined a new one on an NLS system (see
WebSphere DataStage NLS Guide).
– For the timestamp data type: text specifies a text-based timestamp in the form %yyyy-%mm-%dd
%hh:%nn:%ss or in the default date format if you have defined a new one on an NLS system (see
WebSphere DataStage NLS Guide).
v Field max width. The maximum number of bytes in a column represented as a string. Enter a number.
This is useful where you are storing numbers as text. If you are using a fixed-width character set, you
can calculate the length exactly. If you are using variable-length character set, calculate an adequate
maximum width for your fields. Applies to fields of all data types except date, time, timestamp, and
raw; and record, subrec, or tagged if they contain at least one field of this type.
v Field width. The number of bytes in a field represented as a string. Enter a number. This is useful
where you are storing numbers as text. If you are using a fixed-width charset, you can calculate the
number of bytes exactly. If it’s a variable length encoding, base your calculation on the width and
frequency of your variable-width characters. Applies to fields of all data types except date, time,
timestamp, and raw; and record, subrec, or tagged if they contain at least one field of this type.
If you specify neither field width nor field max width, numeric fields written as text have the
following number of bytes as their maximum width:
– 8-bit signed or unsigned integers: 4 bytes
– 16-bit signed or unsigned integers: 6 bytes
– 32-bit signed or unsigned integers: 11 bytes
– 64-bit signed or unsigned integers: 21 bytes
– single-precision float: 14 bytes (sign, digit, decimal point, 7 fraction, ″E″, sign, 2 exponent)
– double-precision float: 24 bytes (sign, digit, decimal point, 16 fraction, ″E″, sign, 3 exponent)
v Pad char. This property is ignored for output links.
v Character set. Specifies the character set. Choose from ASCII or EBCDIC. The default is ASCII. Applies
to all data types except raw and ustring and record, subrec, or tagged containing no fields other than
raw or ustring.

String

Chapter 6. File set stage 117

These properties are applied to columns with a string data type, unless overridden at column level.
v Export EBCDIC as ASCII. Not relevant for output links.
v Import ASCII as EBCDIC. Select this to specify that ASCII characters are read as EBCDIC characters.

Decimal

These properties are applied to columns with a decimal data type unless overridden at column level.
v Allow all zeros. Specifies whether to treat a packed decimal column containing all zeros (which is
normally illegal) as a valid representation of zero. Select Yes or No. The default is No.
v Decimal separator. Specify the ASCII character that acts as the decimal separator (period by default).
v Packed. Select an option to specify what the decimal columns contain, choose from:
– Yes to specify that the decimal fields contain data in packed decimal format (the default). This has
the following sub-properties:
Check. Select Yes to verify that data is packed, or No to not verify.
Signed. Select Yes to use the existing sign when reading decimal fields. Select No to write a positive
sign (0xf) regardless of the fields’ actual sign value.
– No (separate) to specify that they contain unpacked decimal with a separate sign byte. This has the
following sub-property:
Sign Position. Choose leading or trailing as appropriate.
– No (zoned) to specify that they contain an unpacked decimal in either ASCII or EBCDIC text. This
has the following sub-property:
Sign Position. Choose leading or trailing as appropriate.
– No (overpunch) to specify that the field has a leading or end byte that contains a character which
specifies both the numeric value of that byte and whether the number as a whole is negatively or
positively signed. This has the following sub-property:
Sign Position. Choose leading or trailing as appropriate.
v Precision. Specifies the precision of a packed decimal. Enter a number.
v Rounding. Specifies how to round the source field to fit into the destination decimal when reading a
source field to a decimal. Choose from:
– up (ceiling). Truncate source column towards positive infinity. This mode corresponds to the IEEE
754 Round Up mode. For example, 1.4 becomes 2, -1.6 becomes -1.
– down (floor). Truncate source column towards negative infinity. This mode corresponds to the IEEE
754 Round Down mode. For example, 1.6 becomes 1, -1.4 becomes -2.
– nearest value. Round the source column towards the nearest representable value. This mode
corresponds to the COBOL ROUNDED mode. For example, 1.4 becomes 1, 1.5 becomes 2, -1.4
becomes -1, -1.5 becomes -2.
– truncate towards zero. This is the default. Discard fractional digits to the right of the right-most
fractional digit supported by the destination, regardless of sign. For example, if the destination is an
integer, all fractional digits are truncated. If the destination is another decimal with a smaller scale,
truncate to the scale size of the destination decimal. This mode corresponds to the COBOL
INTEGER-PART function. Using this method 1.6 becomes 1, -1.6 becomes -1.
v Scale. Specifies the scale of a source packed decimal.

Numeric

These properties apply to integer and float fields unless overridden at column level.
v C_format. Perform non-default conversion of data from string data to a integer or floating-point. This
property specifies a C-language format string used for reading integer or floating point strings. This is
passed to sscanf(). For example, specifying a C-format of %x and a field width of 8 ensures that a 32-bit
integer is formatted as an 8-byte hexadecimal string.

118 Parallel Job Developer Guide

v In_format. Format string used for conversion of data from string to integer or floating-point data This
is passed to sscanf(). By default, WebSphere DataStage invokes the C sscanf() function to convert a
numeric field formatted as a string to either integer or floating point data. If this function does not
output data in a satisfactory format, you can specify the in_format property to pass formatting
arguments to sscanf().
v Out_format. This property is not relevant for output links.

Date

These properties are applied to columns with a date data type unless overridden at column level. All of
these are incompatible with a Data Format setting of Text.
v Days since. Dates are written as a signed integer containing the number of days since the specified
date. Enter a date in the form %yyyy-%mm-%dd or in the default date format if you have defined a
new one on an NLS system (see WebSphere DataStage NLS Guide).
v Format string. The string format of a date. By default this is %yyyy-%mm-%dd. For details about the
format, see .
v Is Julian. Select this to specify that dates are written as a numeric value containing the Julian day. A
Julian day specifies the date as the number of days from 4713 BCE January 1, 12:00 hours (noon) GMT.

Time

These properties are applied to columns with a time data type unless overridden at column level. All of
these are incompatible with a Data Format setting of Text.
v Format string. Specifies the format of columns representing time as a string. By default this is
%hh-%mm-%ss. For details about the format, see “Time formats” on page 33
v Is midnight seconds. Select this to specify that times are written as a binary 32-bit integer containing
the number of seconds elapsed from the previous midnight.

Timestamp

These properties are applied to columns with a timestamp data type unless overridden at column level.
v Format string. Specifies the format of a column representing a timestamp as a string. The format
combines the format for date strings and time strings. See “Date formats” on page 30 and “Time
formats” on page 33.

Using RCP With file set stages

Runtime column propagation (RCP) allows WebSphere DataStage to be flexible about the columns you
define in a job. If RCP is enabled for a project, you can just define the columns you are interested in
using in a job, but ask WebSphere DataStage to propagate the other columns through the various stages.
So such columns can be extracted from the data source and end up on your data target without explicitly
being operated on in between.

The File Set stage handles a set of sequential files. Sequential files, unlike most other data sources, do not
have inherent column definitions, and so WebSphere DataStage cannot always tell where there are extra
columns that need propagating. You can only use RCP on File Set stages if you have used the Schema
File property (see ″Schema File″) to specify a schema which describes all the columns in the sequential
files referenced by the stage. You need to specify the same schema file for any similar stages in the job
where you want to propagate columns. Stages that will require a schema file are:
v Sequential File
v File Set
v External Source
v External Target

Chapter 6. File set stage 119

v Column Import
v Column Export

120 Parallel Job Developer Guide

Chapter 7. Lookup file set stage
The Lookup File Set stage is a file stage. It allows you to create a lookup file set or reference one for a
lookup. The stage can have a single input link or a single output link. The output link must be a
reference link. The stage can be configured to execute in parallel or sequential mode when used with an
input link.

When creating Lookup file sets, one file will be created for each partition. The individual files are
referenced by a single descriptor file, which by convention has the suffix .fs.

When performing lookups, Lookup File Set stages are used with Lookup stages. For more information
about lookup operations, see ″Lookup Stage.″

© Copyright IBM Corp. 2006 121

When you use a Lookup File Set stage as a source for lookup data, there are special considerations about
column naming. If you have columns of the same name in both the source and lookup data sets, the
source data set column will go to the output data. If you want this column to be replaced by the column
from the lookup data source, you need to drop the source data column before you perform the lookup
(you could, for example, use a Modify stage to do this). See ″Lookup Stage″ for more details about
performing lookups.

122 Parallel Job Developer Guide

When you edit a Lookup File Set stage, the Lookup File Set stage editor appears. This is based on the
generic stage editor described in ″Stage Editors.″

The stage editor has up to three pages, depending on whether you are creating or referencing a file set:
v Stage Page. This is always present and is used to specify general information about the stage.
v Input Page. This is present when you are creating a lookup table. This is where you specify details
about the file set being created and written to.
v Output Page. This is present when you are reading from a lookup file set, i.e., where the stage is
providing a reference link to a Lookup stage. This is where you specify details about the file set being
read from.

Must do’s
WebSphere DataStage has many defaults which means that it can be very easy to include Lookup File Set
stages in a job. This section specifies the minimum steps to take to get a Lookup File Set stage
functioning. WebSphere DataStage provides a versatile user interface, and there are many shortcuts to
achieving a particular end, this section describes the basic method, you will learn where the shortcuts are
when you get familiar with the product.

The steps required depend on whether you are using the Lookup File Set stage to create a lookup file set,
or using it in conjunction with a Lookup stage.

Creating a lookup file set

v In the Input Link Properties Tab:
– Specify the key that the lookup on this file set will ultimately be performed on. You can repeat this
property to specify multiple key columns. You must specify the key when you create the file set,
you cannot specify it when performing the lookup.
– Specify the name of the Lookup File Set.
– Specify a lookup range, or accept the default setting of No.
– Set Allow Duplicates, or accept the default setting of False.
v Ensure column meta data has been specified for the lookup file set.

Looking up a lookup file set

v In the Output Link Properties Tab specify the name of the lookup file set being used in the lookup.
v Ensure column meta data has been specified for the lookup file set.

Stage page
The General tab allows you to specify an optional description of the stage. The Advanced tab allows you
to specify how the stage executes. The NLS Map tab, which appears if you have NLS enabled on your
system, allows you to specify a character set map for the stage.

Advanced tab
This tab only appears when you are using the stage to create a reference file set (i.e., where the stage has
an input link). Use this tab to specify the following:
v Execution Mode. The stage can execute in parallel mode or sequential mode. In parallel mode the
contents of the table are processed by the available nodes as specified in the Configuration file, and by
any node constraints specified on the Advanced tab. In sequential mode the entire contents of the table
are processed by the conductor node.

Chapter 7. Lookup file set stage 123

v Combinability mode. This is Auto by default, which allows WebSphere DataStage to combine the
operators that underlie parallel stages so that they run in the same process if it is sensible for this type
of stage.
v Node map constraint. Select this option to constrain parallel execution to the nodes in a defined node
map. You can define a node map by typing node numbers into the text box or by clicking the browse
button to open the Available Nodes dialog box and selecting nodes from there. You are effectively
defining a new node pool for this stage (in addition to any node pools defined in the Configuration
file).
v Node pool and resource constraints. Select this option to constrain parallel execution to the node pool
or pools and/or resource pools or pools specified in the grid. The grid allows you to make choices
from lists populated from the Configuration file.

NLS Map tab

The NLS Map tab allows you to define a character set map for the Lookup File Set stage. This overrides
the default character set map set for the project or the job. You can specify that the map be supplied as a
job parameter if required. You can also select Allow per-column mapping. This allows character set maps
to be specified for individual columns within the data processed by the External Source stage. An extra
property, NLS Map, appears in the Columns grid in the Columns tab, but note that only ustring data
types allow you to set an NLS map value (see ″Data Types″ .

Input page
The Input page allows you to specify details about how the Lookup File Set stage writes data to a file set.
The Lookup File Set stage can have only one input link.

The General tab allows you to specify an optional description of the input link. The Properties tab allows
you to specify details of exactly what the link does. The Partitioning tab allows you to specify how
incoming data is partitioned before being written to the file set. The Columns tab specifies the column
definitions of the data. The Advanced tab allows you to change the default buffering settings for the
input link.

Details about Lookup File Set stage properties and partitioning are given in the following sections. See
″Stage Editors″ for a general description of the other tabs.

Input link properties tab

The Properties tab allows you to specify properties for the input link. These dictate how incoming data is
written to the file set. Some of the properties are mandatory, although many have default settings.
Properties without default settings appear in the warning color (red by default) and turn black when you
supply a value for them.

The following table gives a quick reference list of the properties and their attributes. A more detailed
description of each property follows.

Category/
Property Values Default Mandatory? Repeats? Dependent of
Lookup Input column N/A Y Y N/A
Keys/Key
Lookup True/False True Y N Key
Keys/Case
Sensitive
Lookup True/False False Y N Key
Keys/Keep

124 Parallel Job Developer Guide

Category/
Property Values Default Mandatory? Repeats? Dependent of
Target/Lookup pathname N/A Y N N/A
File Set
Lookup Yes/No No Y Y N/A
Range/Range
Lookup
Lookup Input column N/A N N Range Lookup
Range/Bounded
Column
Lookup True/False True N N Bounded Column
Range/Case
Sensitive
Lookup True/False False N N Bounded Column
Range/Keep
Lookup Input column N/A N N Range Lookup
Range/Lower
Bound
Lookup True/False True N N Lower Bound
Range/Case
Sensitive
Lookup True/False False N N Lower Bound
Range/Keep
Lookup Input column N/A N N Range Lookup
Range/Upper
Bound
Lookup True/False True N N Upper Bound
Range/Case
Sensitive
Lookup True/False False N N Upper Bound
Range/Keep
Options/Allow True/False False Y N N/A
Duplicates
Options/Diskpool string N/A N N N/A

Lookup keys category

Key

Specifies the name of a lookup key column. The Key property can be repeated if there are multiple key
columns. The property has two dependent properties:
v Case Sensitive
This is a dependent property of Key and specifies whether the parent key is case sensitive or not. Set
to True by default.
v Keep
This specifies whether the key column needs to be propagated to the output stream after the lookup, or
used in a subsequent condition expression. Set to False by default.

Chapter 7. Lookup file set stage 125

Target category
Lookup file set

This property defines the file set that the incoming data will be written to. You can type in a pathname
of, or browse for, a file set descriptor file (by convention ending in .fs).

Lookup range category

Range Lookup

Specifies whether a range lookup is required. A range lookup compares the value of a source column to a
range of values between two lookup columns. Alternatively, you can compare the value of a lookup
column to a range of values between two source columns. This property has the following dependent
properties:
v Bounded Column
Specifies the input column to use for the lookup file set. The lookup table is built with the bounded
column, which will then be compared to a range of columns from the source data set. This property is
mutually exclusive with Lower Bound and Upper Bound. It has two dependent properties:
– Case Sensitive
This is an optional property. Specifies whether the column is case sensitive or not. Set to True by
default.
– Keep
Specifies whether the column needs to be propagated to the output stream after the lookup, or used
in a subsequent condition expression. Set to False by default.
v Lower Bound
Specifies the input column to use for the lower bound of the range in the lookup table. This cannot be
the same as the upper bound column and is mutually exclusive with Bounded Column. It has two
dependent properties:
– Case Sensitive
This is an optional property. Specifies whether the column is case sensitive or not. Set to True by
default.
– Keep
Specifies whether the column needs to be propagated to the output stream after the lookup, or used
in a subsequent condition expression. Set to False by default.
v Upper Bound
Specifies the input column to use for the upper bound of the range in the lookup table. This cannot be
the same as the lower bound column and is mutually exclusive with Bounded Column. It has two
dependent properties:
– Case Sensitive
This is an optional property. Specifies whether the column value is case sensitive or not. Set to True
by default.
– Keep
Specifies whether the column needs to be propagated to the output stream after the lookup, or used
in a subsequent condition expression. Set to False by default.

Options category
Allow duplicates

Set this to cause multiple copies of duplicate records to be saved in the lookup table without a warning
being issued. Two lookup records are duplicates when all lookup key columns have the same value in the
two records. If you do not specify this option, WebSphere DataStage issues a warning message when it
encounters duplicate records and discards all but the first of the matching records.

126 Parallel Job Developer Guide

Diskpool

This is an optional property. Specify the name of the disk pool into which to write the file set. You can
also specify a job parameter.

Partitioning tab
The Partitioning tab allows you to specify details about how the incoming data is partitioned or collected
before it is written to the lookup file set. It also allows you to specify that the data should be sorted
before being written.

By default the stage will write to the file set in entire mode. The complete data set is written to each
partition.

If the Lookup File Set stage is operating in sequential mode, it will first collect the data before writing it
to the file using the default (auto) collection method.

The Partitioning tab allows you to override this default behavior. The exact operation of this tab depends
on:
v Whether the Lookup File Set stage is set to execute in parallel or sequential mode.
v Whether the preceding stage in the job is set to execute in parallel or sequential mode.

If the Lookup File Set stage is set to execute in parallel, then you can set a partitioning method by
selecting from the Partition type list. This will override any current partitioning.

If the Lookup File Set stage is set to execute in sequential mode, but the preceding stage is executing in
parallel, then you can set a collection method from the Collector type list. This will override the default
auto collection method.

The following partitioning methods are available:

v Entire. Each file written to receives the entire data set. This is the default partitioning method for the
Lookup File Set stage.
v Hash. The records are hashed into partitions based on the value of a key column or columns selected
from the Available list.
v Modulus. The records are partitioned using a modulus function on the key column selected from the
Available list. This is commonly used to partition on tag fields.
v Random. The records are partitioned randomly, based on the output of a random number generator.
v Round Robin. The records are partitioned on a round robin basis as they enter the stage.
v Same. Preserves the partitioning already in place.
v DB2. Replicates the DB2 partitioning method of a specific DB2 table. Requires extra properties to be
set. Access these properties by clicking the properties button.
v Range. Divides a data set into approximately equal size partitions based on one or more partitioning
keys. Range partitioning is often a preprocessing step to performing a total sort on a data set. Requires
extra properties to be set. Access these properties by clicking the properties button.

The following collection methods are available:

v (Auto). This is the default method for the Lookup File Set stage. Normally, when you are using Auto
mode, WebSphere DataStage will eagerly read any row from any input partition as it becomes
available.
v Ordered. Reads all records from the first partition, then all records from the second partition, and so
on.

Chapter 7. Lookup file set stage 127

v Round Robin. Reads a record from the first input partition, then from the second partition, and so on.
After reaching the last partition, the operator starts over.
v Sort Merge. Reads records in an order based on one or more columns of the record. This requires you
to select a collecting key column from the Available list.

The Partitioning tab also allows you to specify that data arriving on the input link should be sorted
before being written to the file or files. The sort is always carried out within data partitions. If the stage is
partitioning incoming data, the sort occurs after the partitioning. If the stage is collecting data, the sort
occurs before the collection. The availability of sorting depends on the partitioning or collecting method
chosen (it is not available with the Auto methods).

Select the check boxes as follows:

v Perform Sort. Select this to specify that data coming in on the link should be sorted. Select the column
or columns to sort on from the Available list.
v Stable. Select this if you want to preserve previously sorted data sets. This is the default.
v Unique. Select this to specify that, if multiple records have identical sorting key values, only one
record is retained. If stable sort is also set, the first record is retained.

If NLS is enabled an additional button opens a dialog box allowing you to select a locale specifying the
collate convention for the sort.

You can also specify sort direction, case sensitivity, whether sorted as ASCII or EBCDIC, and whether null
columns will appear first or last for each column. Where you are using a keyed partitioning method, you
can also specify whether the column is used as a key for sorting, for partitioning, or for both. Right-click
the column in the Selected list to invoke the shortcut menu.

Output page
The Output page allows you to specify details about how the Lookup File Set stage references a file set.
The Lookup File Set stage can have only one output link, which is a reference link.

The General tab allows you to specify an optional description of the output link. The Properties tab
allows you to specify details of exactly what the link does. The Columns tab specifies the column
definitions of the data. The Advanced tab allows you to change the default buffering settings for the
output link.

Details about Lookup File Set stage properties are given in the following sections. See ″Stage Editors,″ for
a general description of the other tabs.

Output link properties tab

The Properties tab allows you to specify properties for the output link. These dictate how incoming data
is read from the lookup table. There is only one output link property.

Category/
Property Values Default Mandatory? Repeats? Dependent of
Lookup path name N/A Y N N/A
Source/Lookup
File Set

128 Parallel Job Developer Guide

Lookup source category
Lookup file set

This property defines the file set that the data will be referenced from. You can type in a pathname of, or
browse for, a file set descriptor file (by convention ending in .fs).

Chapter 7. Lookup file set stage 129

130 Parallel Job Developer Guide
Chapter 8. External source stage
The External Source stage is a file stage. It allows you to read data that is output from one or more
source programs. The stage calls the program and passes appropriate arguments. The stage can have a
single output link, and a single rejects link. It can be configured to execute in parallel or sequential mode.
There is also an External Target stage which allows you to write to an external program (see Chapter 9,
“External Target stage,” on page 143).

The External Source stage allows you to perform actions such as interface with databases not currently
supported by the WebSphere DataStage Enterprise Edition.

When reading output from a program, WebSphere DataStage needs to know something about its format.
The information required is how the data is divided into rows and how rows are divided into columns.
You specify this on the Format tab. Settings for individual columns can be overridden on the Columns
tab using the Edit Column Metadata dialog box.

When you edit an External Source stage, the External Source stage editor appears. This is based on the
generic stage editor described in ″Stage Editors.″

The stage editor has two pages:

v Stage Page. This is always present and is used to specify general information about the stage.
v Output Page. This is where you specify details about the program or programs whose output data you
are reading.

There are one or two special points to note about using runtime column propagation (RCP) with External
Source stages. See ″Using RCP With External Source Stages″ for details.

© Copyright IBM Corp. 2006 131

Must do’s
WebSphere DataStage has many defaults which means that it can be very easy to include External Source
stages in a job. This section specifies the minimum steps to take to get a External Source stage
functioning. WebSphere DataStage provides a versatile user interface, and there are many shortcuts to
achieving a particular end, this section describes the basic method, you will learn where the shortcuts are
when you get familiar with the product.

To use the External Source stage:

v In the Output Link Properties Tab:
– Specify whether the stage is providing details of the program (the default) or whether details will be
provided in a file (using the latter method you can provide a list of files and arguments).
– If using the default source method, specify the name of the source program executable. You can also
specify required arguments that WebSphere DataStage will pass when it calls the program. Repeat
this to specify multiple program calls.
– If using the program file source method, specify the name of the file containing the list of program
names and arguments.
– Specify whether to maintain any partitions in the source data (False by default).
– Specify how to treat rejected rows (by default the stage continues and the rows are discarded).
v In the Format Tab specify format details for the source data you are reading from, or accept the
defaults (variable length columns enclosed in double quotes and delimited by commas, rows delimited
with UNIX newlines).
v Ensure that column definitions have been specified (you can use a schema file for this if required).

Stage page
The General tab allows you to specify an optional description of the stage. The Advanced tab allows you
to specify how the stage executes. The NLS Map tab appears if you have NLS enabled on your system, it
allows you to specify a character set map for the stage.

Advanced tab
This tab allows you to specify the following:
v Execution Mode. The stage can execute in parallel mode or sequential mode. In parallel mode the data
input from external programs is processed by the available nodes as specified in the Configuration file,
and by any node constraints specified on the Advanced tab. In Sequential mode all the data from the
source program is processed by the conductor node.
v Combinability mode. This is Auto by default, which allows WebSphere DataStage to combine the
operators that underlie parallel stages so that they run in the same process if it is sensible for this type
of stage.
v Preserve partitioning. You can select Set or Clear. If you select Set, it will request that the next stage
preserves the partitioning as is. Clear is the default.
v Node pool and resource constraints. Select this option to constrain parallel execution to the node pool
or pools and/or resource pool or pools specified in the grid. The grid allows you to make choices from
drop down lists populated from the Configuration file.
v Node map constraint. Select this option to constrain parallel execution to the nodes in a defined node
map. You can define a node map by typing node numbers into the text box or by clicking the browse
button to open the Available Nodes dialog box and selecting nodes from there. You are effectively
defining a new node pool for this stage (in addition to any node pools defined in the Configuration
file).

132 Parallel Job Developer Guide

NLS Map tab
The NLS Map tab allows you to define a character set map for the External Source stage. This overrides
the default character set map set for the project or the job. You can specify that the map be supplied as a
job parameter if required. You can also select Allow per-column mapping. This allows character set maps
to be specified for individual columns within the data processed by the External Source stage. An extra
property, NLS Map, appears in the Columns grid in the Columns tab, but note that only ustring data
types allow you to set an NLS map value (see ″Data Types″ .

Output page
The Output page allows you to specify details about how the External Source stage reads data from an
external program. The External Source stage can have only one output link. It can also have a single
reject link, where rows that do not match the expected schema can be sent. The Output name drop-down
list allows you to choose whether you are looking at details of the main output link (the stream link) or
the reject link.

The General tab allows you to specify an optional description of the output link. The Properties tab
allows you to specify details of exactly what the link does. The Format tab gives information about the
format of the files being read. The Columns tab specifies the column definitions of the data. The
Advanced tab allows you to change the default buffering settings for the output link.

Details about External Source stage properties and formatting are given in the following sections. See
″Stage Editors,″ for a general description of the other tabs.

Output link properties tab

The Properties tab allows you to specify properties for the output link. These dictate how data is read
from the external program or programs. Some of the properties are mandatory, although many have
default settings. Properties without default settings appear in the warning color (red by default) and turn
black when you supply a value for them.

The following table gives a quick reference list of the properties and their attributes. A more detailed
description of each property follows.

Category/ Dependent
Property Values Default Mandatory? Repeats? of
Source/Source string N/A Y if Source Y N/A
Program Method =
Specific
Program(s)
Source/Source pathname N/A Y if Source Y N/A
Programs File Method =
Program
File(s)
Source/Source Specific Specific Program(s) Y N N/A
Method Program(s)/
Program File(s)
Options/Keep True/False False Y N N/A
File Partitions
Options/Reject Continue/Fail/ Continue Y N N/A
Mode Save
Options/Schema pathname N/A N N N/A
File

Chapter 8. External source stage 133

Category/ Dependent
Property Values Default Mandatory? Repeats? of
Options/Source column name sourceNameColumn N N N/A
Name Column

Source category
Source program

Specifies the name of a program providing the source data. WebSphere DataStage calls the specified
program and passes to it any arguments specified. You can repeat this property to specify multiple
program instances with different arguments. You can use a job parameter to supply program name and
arguments.

Source programs file

Specifies a file containing a list of program names and arguments. You can browse for the file or specify a
job parameter. You can repeat this property to specify multiple files.

Source method

This property specifies whether you directly specifying a program (using the Source Program property)
or using a file to specify a program (using the Source Programs File property).

Options category
Keep file partitions

Set this to True to maintain the partitioning of the read data. Defaults to False.

Reject mode

Allows you to specify behavior if a record fails to be read for some reason. Choose from Continue to
continue operation and discard any rejected rows, Fail to cease reading if any rows are rejected, or Save
to send rejected rows down a reject link. Defaults to Continue.

Schema file

This is an optional property. By default the External Source stage will use the column definitions defined
on the Columns tab and Schema tab as a schema for reading the file. You can, however, specify a file
containing a schema instead (note, however, that if you have defined columns on the Columns tab, you
should ensure these match the schema file). Type in a pathname or browse for a schema file.

Source name column

This is an optional property. It adds an extra column of type VarChar to the output of the stage,
containing the pathname of the source the record is read from. You should also add this column
manually to the Columns definitions to ensure that the column is not dropped if you are not using
runtime column propagation, or it is turned off at some point.

Output link Format tab

The Format tab allows you to supply information about the format of the source data you are reading.
The tab has a similar format to the Properties tab.

If you do not alter any of the Format settings, the stage will produce a file of the following format:

134 Parallel Job Developer Guide

v File comprises variable length columns contained within double quotes.
v All columns are delimited by a comma, except for the final column in a row.
v Rows are delimited by a UNIX newline.

You can use the Format As item from the shortcut menu in the Format tab to quickly change to a
fixed-width column format, using DOS newlines as row delimiters, or producing a COBOL format file.

You can use the Defaults button to change your default settings. Use the Format tab to specify your
required settings, then click Defaults → Save current as default. All your sequential files will use your
settings by default from now on. If your requirements change, you can choose Defaults → Reset defaults
from factory settings to go back to the original defaults as described above. Once you have done this,
you then have to click Defaults → Set current from default for the new defaults to take effect.

To change individual properties, select a property type from the main tree then add the properties you
want to set to the tree structure by clicking on them in the Available properties to set window. You can
then set a value for that property in the Property Value box. Pop-up help for each of the available
properties appears if you hover the mouse pointer over it.

Any property that you set on this tab can be overridden at the column level by setting properties for
individual columns on the Edit Column Metadata dialog box (see Columns Tab).

This description uses the terms ″record″ and ″row″ and ″field″ and ″column″ interchangeably.

The following sections list the property types and properties available for each type.

Record level

These properties define details about how data records are formatted in the flat file. Where you can enter
a character, this can usually be an ASCII character or a multi-byte Unicode character (if you have NLS
enabled). The available properties are:
v Fill char. Does not apply to output links.
v Final delimiter string. Specify the string written after the last column of a record in place of the
column delimiter. Enter one or more characters, this precedes the record delimiter if one is used.
Mutually exclusive with Final delimiter, which is the default. For example, if you set Delimiter to
comma and Final delimiter string to `, ` (comma space - you do not need to enter the inverted
commas) all fields are delimited by a comma, except the final field, which is delimited by a comma
followed by an ASCII space character. WebSphere DataStage skips the specified delimiter string when
reading the file.
v Final delimiter. Specify the single character written after the last column of a record in place of the
field delimiter. Type a character or select one of whitespace, end, none, null, tab, or comma. WebSphere
DataStage skips the specified delimiter string when reading the file. See the following diagram for an
illustration.
– whitespace. The last column of each record will not include any trailing white spaces found at the
end of the record.
– end. The last column of each record does not include the field delimiter. This is the default setting.
– none. The last column of each record does not have a delimiter, used for fixed-width fields.
– null. The last column of each record is delimited by the ASCII null character.
– comma. The last column of each record is delimited by the ASCII comma character.

Chapter 8. External source stage 135

 – tab. The last column of each record is delimited by the ASCII tab character.
record delimiter

Field , Field , Field , Last field nl

Final delimiter = end

field delimiter

Field , Field , Field , Last field , nl

Final delimiter = comma
v Intact. The intact property specifies an identifier of a partial schema. A partial schema specifies that
only the column(s) named in the schema can be modified by the stage. All other columns in the row
are passed through unmodified. The file containing the partial schema is specified in the Schema File
property on the Outputs tab. This property has a dependent property:
– Check intact. Select this to force validation of the partial schema as the file or files are imported.
Note that this can degrade performance.
v Record delimiter string. Specify the string at the end of each record. Enter one or more characters.
This is mutually exclusive with Record delimiter, which is the default, and record type and record
prefix.
v Record delimiter. Specify the single character at the end of each record. Type a character or select one
of the following:
– UNIX Newline (the default)
– null
(To specify a DOS newline, use the Record delimiter string property set to ″\R\N″ or choose Format
as → DOS line terminator from the shortcut menu.)
Record delimiter is mutually exclusive with Record delimiter string, Record prefix, and record type.
v Record length. Select Fixed where fixed length fields are being read. WebSphere DataStage calculates
the appropriate length for the record. Alternatively specify the length of fixed records as number of
bytes. This is not used by default (default files are comma-delimited).
v Record Prefix. Specifies that a variable-length record is prefixed by a 1-, 2-, or 4-byte length prefix. It is
set to 1 by default. This is mutually exclusive with Record delimiter, which is the default, and record
delimiter string and record type.
v Record type. Specifies that data consists of variable-length blocked records (varying) or implicit records
(implicit). If you choose the implicit property, data is written as a stream with no explicit record
boundaries. The end of the record is inferred when all of the columns defined by the schema have
been parsed. The varying property allows you to specify one of the following IBM blocked or spanned
formats: V, VB, VS, VBS, or VR.
This property is mutually exclusive with Record length, Record delimiter, Record delimiter string, and
Record prefix and by default is not used.

Field Defaults

Defines default properties for columns read from the file or files. These are applied to all columns, but
can be overridden for individual columns from the Columns tab using the Edit Column Metadata dialog
box. Where you can enter a character, this can usually be an ASCII character or a multi-byte Unicode
character (if you have NLS enabled). The available properties are:
v Actual field length. Specifies the actual number of bytes to skip if the field’s length equals the setting
of the null field length property.

136 Parallel Job Developer Guide

v Delimiter. Specifies the trailing delimiter of all fields in the record. Type an ASCII character or select
one of whitespace, end, none, null, comma, or tab. WebSphere DataStage skips the delimiter when
reading.
– whitespace. Whitespace characters at the end of a column are ignored, i.e., are not treated as part of
the column.
– end. The end of a field is taken as the delimiter, i.e., there is no separate delimiter. This is not the
same as a setting of `None’ which is used for fields with fixed-width columns.
– none. No delimiter (used for fixed-width).
– null. ASCII Null character is used.
– comma. ASCII comma character is used.
– tab. ASCII tab character is used.
v Delimiter string. Specify the string at the end of each field. Enter one or more characters. This is
mutually exclusive with Delimiter, which is the default. For example, specifying `, ` (comma space -
you do not need to enter the inverted commas) specifies each field is delimited by `, ` unless
overridden for individual fields. WebSphere DataStage skips the delimiter string when reading.
v Null field length. The length in bytes of a variable-length field that contains a null. When a
variable-length field is read, a length of null field length in the source field indicates that it contains a
null. This property is mutually exclusive with null field value.
v Null field value. Specifies the value given to a null field if the source is set to null. Can be a number,
string, or C-type literal escape character. For example, you can represent a byte value by \ooo, where
each o is an octal digit 0 - 7 and the first o is < 4, or by \xhh, where each h is a hexadecimal digit 0 - F.
You must use this form to encode non-printable byte values.
This property is mutually exclusive with Null field length and Actual length. For a fixed width data
representation, you can use Pad char (from the general section of Type defaults) to specify a repeated
trailing character if the value you specify is shorter than the fixed width of the field.
v Prefix bytes. You can use this option with variable-length fields. Variable-length fields can be either
delimited by a character or preceded by a 1-, 2-, or 4-byte prefix containing the field length. WebSphere
DataStage reads the length prefix but does not include the prefix as a separate field in the data set it
reads from the file.
This property is mutually exclusive with the Delimiter, Quote, and Final Delimiter properties, which
are used by default.
v Print field. This property is intended for use when debugging jobs. Set it to have WebSphere
DataStage produce a message for every field it reads. The message has the format:
Importing N: D
where:
– N is the field name.
– D is the imported data of the field. Non-printable characters contained in D are prefixed with an
escape character and written as C string literals; if the field contains binary data, it is output in octal
format.
v Quote. Specifies that variable length fields are enclosed in single quotes, double quotes, or another
character or pair of characters. Choose Single or Double, or enter a character. This is set to double
quotes by default.
When reading, WebSphere DataStage ignores the leading quote character and reads all bytes up to but
not including the trailing quote character.
v Vector prefix. For fields that are variable length vectors, specifies that a 1-, 2-, or 4-byte prefix contains
the number of elements in the vector. You can override this default prefix for individual vectors.
Variable-length vectors must use either a prefix on the vector or a link to another field in order to
specify the number of elements in the vector. If the variable length vector has a prefix, you use this
property to indicate the prefix length. WebSphere DataStage reads the length prefix but does not
include it as a separate field in the data set. By default, the prefix length is assumed to be one byte.

Chapter 8. External source stage 137

Type Defaults

These are properties that apply to all columns of a specific data type unless specifically overridden at the
column level. They are divided into a number of subgroups according to data type.

General

These properties apply to several data types (unless overridden at column level):
v Byte order. Specifies how multiple byte data types (except string and raw data types) are ordered.
Choose from:
– little-endian. The high byte is on the right.
– big-endian. The high byte is on the left.
– native-endian. As defined by the native format of the machine. This is the default.
v Data Format. Specifies the data representation format of a field. Applies to fields of all data types
except string, ustring, and raw and to record, subrec or tagged fields containing at least one field that
is neither string nor raw. Choose from:
– binary
– text (the default)
A setting of binary has different meanings when applied to different data types:
– For decimals, binary means packed.
– For other numerical data types, binary means ″not text″.
– For dates, binary is equivalent to specifying the julian property for the date field.
– For time, binary is equivalent to midnight_seconds.
– For timestamp, binary specifies that the first integer contains a Julian day count for the date portion
of the timestamp and the second integer specifies the time portion of the timestamp as the number
of seconds from midnight. A binary timestamp specifies that two 32-but integers are written.
By default data is formatted as text, as follows:
– For the date data type, text specifies that the data read, contains a text-based date in the form
%yyyy-%mm-%dd or in the default date format if you have defined a new one on an NLS system
(see WebSphere DataStage NLS Guide).
– For the decimal data type: a field represents a decimal in a string format with a leading space or ’-’
followed by decimal digits with an embedded decimal point if the scale is not zero. The destination
string format is: [+ | -]ddd.[ddd] and any precision and scale arguments are ignored.
– For numeric fields (int8, int16, int32, uint8, uint16, uint32, sfloat, and dfloat): WebSphere DataStage
assumes that numeric fields are represented as text.
– For the time data type: text specifies that the field represents time in the text-based form
%hh:%nn:%ss or in the default date format if you have defined a new one on an NLS system (see
WebSphere DataStage NLS Guide).
– For the timestamp data type: text specifies a text-based timestamp in the form %yyyy-%mm-%dd
%hh:%nn:%ss or in the default date format if you have defined a new one on an NLS system (see
WebSphere DataStage NLS Guide).
v Field max width. The maximum number of bytes in a column represented as a string. Enter a number.
This is useful where you are storing numbers as text. If you are using a fixed-width character set, you
can calculate the length exactly. If you are using variable-length character set, calculate an adequate
maximum width for your fields. Applies to fields of all data types except date, time, timestamp, and
raw; and record, subrec, or tagged if they contain at least one field of this type.
v Field width. The number of bytes in a field represented as a string. Enter a number. This is useful
where you are storing numbers as text. If you are using a fixed-width charset, you can calculate the
number of bytes exactly. If it’s a variable length encoding, base your calculation on the width and
frequency of your variable-width characters. Applies to fields of all data types except date, time,
timestamp, and raw; and record, subrec, or tagged if they contain at least one field of this type.

138 Parallel Job Developer Guide

 If you specify neither field width nor field max width, numeric fields written as text have the
following number of bytes as their maximum width:
– 8-bit signed or unsigned integers: 4 bytes
– 16-bit signed or unsigned integers: 6 bytes
– 32-bit signed or unsigned integers: 11 bytes
– 64-bit signed or unsigned integers: 21 bytes
– single-precision float: 14 bytes (sign, digit, decimal point, 7 fraction, ″E″, sign, 2 exponent)
– double-precision float: 24 bytes (sign, digit, decimal point, 16 fraction, ″E″, sign, 3 exponent)
v Pad char. This property is ignored for output links.
v Character set. Specifies the character set. Choose from ASCII or EBCDIC. The default is ASCII. Applies
to all data types except raw and ustring and record, subrec, or tagged containing no fields other than
raw or ustring.

String

These properties are applied to columns with a string data type, unless overridden at column level.
v Export EBCDIC as ASCII. Not relevant for output links.
v Import ASCII as EBCDIC. Select this to specify that ASCII characters are read as EBCDIC characters.

Decimal

These properties are applied to columns with a decimal data type unless overridden at column level.
v Allow all zeros. Specifies whether to treat a packed decimal column containing all zeros (which is
normally illegal) as a valid representation of zero. Select Yes or No. The default is No.
v Decimal separator. Specify the ASCII character that acts as the decimal separator (period by default).
v Packed. Select an option to specify what the decimal columns contain, choose from:
– Yes to specify that the decimal fields contain data in packed decimal format (the default). This has
the following sub-properties:
Check. Select Yes to verify that data is packed, or No to not verify.
Signed. Select Yes to use the existing sign when reading decimal fields. Select No to write a positive
sign (0xf) regardless of the fields’ actual sign value.
– No (separate) to specify that they contain unpacked decimal with a separate sign byte. This has the
following sub-property:
Sign Position. Choose leading or trailing as appropriate.
– No (zoned) to specify that they contain an unpacked decimal in either ASCII or EBCDIC text. This
has the following sub-property:
Sign Position. Choose leading or trailing as appropriate.
– No (overpunch) to specify that the field has a leading or end byte that contains a character which
specifies both the numeric value of that byte and whether the number as a whole is negatively or
positively signed. This has the following sub-property:
Sign Position. Choose leading or trailing as appropriate.
v Precision. Specifies the precision of a packed decimal. Enter a number.
v Rounding. Specifies how to round the source field to fit into the destination decimal when reading a
source field to a decimal. Choose from:
– up (ceiling). Truncate source column towards positive infinity. This mode corresponds to the IEEE
754 Round Up mode. For example, 1.4 becomes 2, -1.6 becomes -1.
– down (floor). Truncate source column towards negative infinity. This mode corresponds to the IEEE
754 Round Down mode. For example, 1.6 becomes 1, -1.4 becomes -2.

Chapter 8. External source stage 139

 – nearest value. Round the source column towards the nearest representable value. This mode
corresponds to the COBOL ROUNDED mode. For example, 1.4 becomes 1, 1.5 becomes 2, -1.4
becomes -1, -1.5 becomes -2.
– truncate towards zero. This is the default. Discard fractional digits to the right of the right-most
fractional digit supported by the destination, regardless of sign. For example, if the destination is an
integer, all fractional digits are truncated. If the destination is another decimal with a smaller scale,
truncate to the scale size of the destination decimal. This mode corresponds to the COBOL
INTEGER-PART function. Using this method 1.6 becomes 1, -1.6 becomes -1.
v Scale. Specifies the scale of a source packed decimal.

Numeric

These properties apply to integer and float fields unless overridden at column level.
v C_format. Perform non-default conversion of data from string data to a integer or floating-point. This
property specifies a C-language format string used for reading integer or floating point strings. This is
passed to sscanf(). For example, specifying a C-format of %x and a field width of 8 ensures that a 32-bit
integer is formatted as an 8-byte hexadecimal string.
v In_format. Format string used for conversion of data from string to integer or floating-point data This
is passed to sscanf(). By default, WebSphere DataStage invokes the C sscanf() function to convert a
numeric field formatted as a string to either integer or floating point data. If this function does not
output data in a satisfactory format, you can specify the in_format property to pass formatting
arguments to sscanf().
v Out_format. This property is not relevant for output links.

Date

These properties are applied to columns with a date data type unless overridden at column level. All of
these are incompatible with a Data Format setting of Text.
v Days since. Dates are written as a signed integer containing the number of days since the specified
date. Enter a date in the form %yyyy-%mm-%dd or in the default date format if you have defined a
new one on an NLS system (see WebSphere DataStage NLS Guide).
v Format string. The string format of a date. By default this is %yyyy-%mm-%dd. For details about the
format, see .
v Is Julian. Select this to specify that dates are written as a numeric value containing the Julian day. A
Julian day specifies the date as the number of days from 4713 BCE January 1, 12:00 hours (noon) GMT.

Time

These properties are applied to columns with a time data type unless overridden at column level. All of
these are incompatible with a Data Format setting of Text.
v Format string. Specifies the format of columns representing time as a string. By default this is
%hh-%mm-%ss. For details about the format, see “Time formats” on page 33
v Is midnight seconds. Select this to specify that times are written as a binary 32-bit integer containing
the number of seconds elapsed from the previous midnight.

Timestamp

These properties are applied to columns with a timestamp data type unless overridden at column level.
v Format string. Specifies the format of a column representing a timestamp as a string. The format
combines the format for date strings and time strings. See “Date formats” on page 30 and “Time
formats” on page 33.

140 Parallel Job Developer Guide

Using RCP With External Source Stages
Runtime column propagation (RCP) allows WebSphere DataStage to be flexible about the columns you
define in a job. If RCP is enabled for a project, you can just define the columns you are interested in
using in a job, but ask WebSphere DataStage to propagate the other columns through the various stages.
So such columns can be extracted from the data source and end up on your data target without explicitly
being operated on in between.

External Source stages, unlike most other data sources, do not have inherent column definitions, and so
WebSphere DataStage cannot always tell where there are extra columns that need propagating. You can
only use RCP on External Source stages if you have used the Schema File property (see ″Schema File″ on
page Schema File) to specify a schema which describes all the columns in the sequential files referenced
by the stage. You need to specify the same schema file for any similar stages in the job where you want
to propagate columns. Stages that will require a schema file are:
v Sequential File
v File Set
v External Source
v External Target
v Column Import
v Column Export

Chapter 8. External source stage 141

142 Parallel Job Developer Guide
Chapter 9. External Target stage
The External Target stage is a file stage. It allows you to write data to one or more source programs. The
stage can have a single input link and a single rejects link. It can be configured to execute in parallel or
sequential mode. There is also an External Source stage, which allows you to read from an external
program (see Chapter 8, “External source stage,” on page 131)

The External Target stage allows you to perform actions such as interface with databases not currently
supported by the WebSphere DataStage Parallel Extender.

When writing to a program, WebSphere DataStage needs to know something about how to format the
data. The information required is how the data is divided into rows and how rows are divided into
columns. You specify this on the Format tab. Settings for individual columns can be overridden on the
Columns tab using the Edit Column Metadata dialog box.

When you edit an External Target stage, the External Target stage editor appears. This is based on the
generic stage editor described in ″Stage Editors.″

The stage editor has up to three pages:

v Stage Page. This is always present and is used to specify general information about the stage.
v Input Page. This is where you specify details about the program or programs you are writing data to.
v Output Page. This appears if the stage has a rejects link.

There are one or two special points to note about using runtime column propagation (RCP) with External
Target stages. See ″Using RCP With External Target Stages″ for details.

© Copyright IBM Corp. 2006 143

Must do’s
WebSphere DataStage has many defaults which means that it can be very easy to include External Target
stages in a job. This section specifies the minimum steps to take to get a External Target stage
functioning. WebSphere DataStage provides a versatile user interface, and there are many shortcuts to
achieving a particular end, this section describes the basic method, you will learn where the shortcuts are
when you get familiar with the product.

To use the External Target stage:

v In the Input Link Properties Tab:
– Specify whether the stage is providing details of the program (the default) or whether details will be
provided in a file (using the latter method you can provide a list of files and arguments).
– If using the default target method, specify the name of the target program executable. You can also
specify required arguments that WebSphere DataStage will pass when it calls the program. Repeat
this to specify multiple program calls.
– If using the program file target method, specify the name of the file containing the list of program
names and arguments.
– Specify whether to delete partially written data if the write fails for some reason (True by default).
– Specify how to treat rejected rows (by default the stage continues and the rows are discarded).
v In the Format Tab specify format details for the data you are writing, or accept the defaults (variable
length columns enclosed in double quotes and delimited by commas, rows delimited with UNIX
newlines).
v Ensure that column definitions have been specified (this can be done in an earlier stage or in a schema
file).

Stage page
The General tab allows you to specify an optional description of the stage. The Advanced tab allows you
to specify how the stage executes. The NLS Map tab appears if you have NLS enabled on your system, it
allows you to specify a character set map for the stage.

Advanced tab
This tab allows you to specify the following:
v Execution Mode. The stage can execute in parallel mode or sequential mode. In parallel mode the data
output to external programs is processed by the available nodes as specified in the Configuration file,
and by any node constraints specified on the Advanced tab. In Sequential mode all the data from the
source program is processed by the conductor node.
v Combinability mode. This is Auto by default, which allows WebSphere DataStage to combine the
operators that underlie parallel stages so that they run in the same process if it is sensible for this type
of stage.
v Preserve partitioning. You can select Set or Clear. If you select Set, it will request that the next stage
preserves the partitioning as is. Clear is the default.
v Node pool and resource constraints. Select this option to constrain parallel execution to the node pool
or pools and/or resource pool or pools specified in the grid. The grid allows you to make choices from
drop down lists populated from the Configuration file.
v Node map constraint. Select this option to constrain parallel execution to the nodes in a defined node
map. You can define a node map by typing node numbers into the text box or by clicking the browse
button to open the Available Nodes dialog box and selecting nodes from there. You are effectively
defining a new node pool for this stage (in addition to any node pools defined in the Configuration
file).

144 Parallel Job Developer Guide

NLS Map tab
The NLS Map tab allows you to define a character set map for the External Target stage. This overrides
the default character set map set for the project or the job. You can specify that the map be supplied as a
job parameter if required. You can also select Allow per-column mapping. This allows character set maps
to be specified for individual columns within the data processed by the External Target stage. An extra
property, NLS Map, appears in the Columns grid in the Columns tab, but note that only ustring data
types allow you to set an NLS map value (see ″Data Types″).

Input page
The Input page allows you to specify details about how the External Target stage writes data to an
external program. The External Target stage can have only one input link.

The General tab allows you to specify an optional description of the input link. The Properties tab allows
you to specify details of exactly what the link does. The Partitioning tab allows you to specify how
incoming data is partitioned before being written to the external program. The Format tab gives
information about the format of the data being written. The Columns tab specifies the column definitions
of the data. The Advanced tab allows you to change the default buffering settings for the input link.

Details about External Target stage properties, partitioning, and formatting are given in the following
sections. See″Stage Editors,″ for a general description of the other tabs.

Input link properties tab

The Properties tab allows you to specify properties for the input link. These dictate how incoming data is
written and to what program. Some of the properties are mandatory, although many have default
settings. Properties without default settings appear in the warning color (red by default) and turn black
when you supply a value for them.

The following table gives a quick reference list of the properties and their attributes. A more detailed
description of each property follows.

Category/
Property Values Default Mandatory? Repeats? Dependent of
Target string N/A Y if Source Y N/A
/Destination Method = Specific
Program Program(s)
Target pathname N/A Y if Source Y N/A
/Destination Method =
Programs File Program File(s)
Target /Target Specific Specific Y N N/A
Method Program(s)/ Program(s)
Program File(s)
Options/Reject Continue/Fail/ Continue N N N/A
Mode Save
Options/Schema pathname N/A N N N/A
File

Target category
Destination program

This is an optional property. Specifies the name of a program receiving data. WebSphere DataStage calls
the specified program and passes to it any arguments specified.You can repeat this property to specify

Chapter 9. External Target stage 145

multiple program instances with different arguments. You can use a job parameter to supply program
name and arguments.

Destination programs file

This is an optional property. Specifies a file containing a list of program names and arguments. You can
browse for the file or specify a job parameter. You can repeat this property to specify multiple files.

Target method

This property specifies whether you directly specifying a program (using the Destination Program
property) or using a file to specify a program (using the Destination Programs File property).

Options category
Reject mode

This is an optional property. Allows you to specify behavior if a record fails to be written for some
reason. Choose from Continue to continue operation and discard any rejected rows, Fail to cease reading
if any rows are rejected, or Save to send rejected rows down a reject link. Defaults to Continue.

Schema file

This is an optional property. By default the External Target stage will use the column definitions defined
on the Columns tab as a schema for writing the file. You can, however, specify a file containing a schema
instead (note, however, that if you have defined columns on the Columns tab, you should ensure these
match the schema file). Type in a pathname or browse for a schema file.

Partitioning tab
The Partitioning tab allows you to specify details about how the incoming data is partitioned or collected
before it is written to the target program. It also allows you to specify that the data should be sorted
before being written.

By default the stage will partition data in Auto mode.

If the External Target stage is operating in sequential mode, it will first collect the data before writing it
to the file using the default auto collection method.

The Partitioning tab allows you to override this default behavior. The exact operation of this tab depends
on:
v Whether the External Target stage is set to execute in parallel or sequential mode.
v Whether the preceding stage in the job is set to execute in parallel or sequential mode.

If the External Target stage is set to execute in parallel, then you can set a partitioning method by
selecting from the Partitioning type drop-down list. This will override any current partitioning.

If the External Target stage is set to execute in sequential mode, but the preceding stage is executing in
parallel, then you can set a collection method from the Collector type drop-down list. This will override
the default Auto collection method.

The following partitioning methods are available:

v (Auto). WebSphere DataStage attempts to work out the best partitioning method depending on
execution modes of current and preceding stages and how many nodes are specified in the
Configuration file. This is the default partitioning method for the External Target stage.
v Entire. Each file written to receives the entire data set.

146 Parallel Job Developer Guide

v Hash. The records are hashed into partitions based on the value of a key column or columns selected
from the Available list.
v Modulus. The records are partitioned using a modulus function on the key column selected from the
Available list. This is commonly used to partition on tag columns.
v Random. The records are partitioned randomly, based on the output of a random number generator.
v Round Robin. The records are partitioned on a round robin basis as they enter the stage.
v Same. Preserves the partitioning already in place.
v DB2. Replicates the DB2 partitioning method of a specific DB2 table. Requires extra properties to be
set. Access these properties by clicking the properties button.
v Range. Divides a data set into approximately equal size partitions based on one or more partitioning
keys. Range partitioning is often a preprocessing step to performing a total sort on a data set. Requires
extra properties to be set. Access these properties by clicking the properties button.

The following Collection methods are available:

v (Auto). This is the default method for the External Target stage. Normally, when you are using Auto
mode, WebSphere DataStage will eagerly read any row from any input partition as it becomes
available.
v Ordered. Reads all records from the first partition, then all records from the second partition, and so
on.
v Round Robin. Reads a record from the first input partition, then from the second partition, and so on.
After reaching the last partition, the operator starts over.
v Sort Merge. Reads records in an order based on one or more columns of the record. This requires you
to select a collecting key column from the Available list.

The Partitioning tab also allows you to specify that data arriving on the input link should be sorted
before being written to the target program. The sort is always carried out within data partitions. If the
stage is partitioning incoming data the sort occurs after the partitioning. If the stage is collecting data, the
sort occurs before the collection. The availability of sorting depends on the partitioning or collecting
method chosen (it is not available with the Auto methods).

Select the check boxes as follows:

v Perform Sort. Select this to specify that data coming in on the link should be sorted. Select the column
or columns to sort on from the Available list.
v Stable. Select this if you want to preserve previously sorted data sets. This is the default.
v Unique. Select this to specify that, if multiple records have identical sorting key values, only one
record is retained. If stable sort is also set, the first record is retained.

If NLS is enabled an additional button opens a dialog box allowing you to select a locale specifying the
collate convention for the sort.

You can also specify sort direction, case sensitivity, whether sorted as ASCII or EBCDIC, and whether null
columns will appear first or last for each column. Where you are using a keyed partitioning method, you
can also specify whether the column is used as a key for sorting, for partitioning, or for both. Select the
column in the Selected list and right-click to invoke the shortcut menu.

Format tab
The Format tab allows you to supply information about the format of the data you are writing. The tab
has a similar format to the Properties tab

If you do not alter any of the Format settings, the External Target stage will produce a file of the
following format:

Chapter 9. External Target stage 147

v Data comprises variable length columns contained within double quotes.
v All columns are delimited by a comma, except for the final column in a row.
v Rows are delimited by a UNIX newline.

You can use the Format As item from the shortcut menu in the Format tab to quickly change to a
fixed-width column format, using DOS newlines as row delimiters, or producing a COBOL format file.

To change individual properties, select a property type from the main tree then add the properties you
want to set to the tree structure by clicking on them in the Available properties to set window. You can
then set a value for that property in the Property Value box. Pop up help for each of the available
properties appears if you hover the mouse pointer over it.

This description uses the terms ″record″ and ″row″ and ″field″ and ″column″ interchangeably.

The following sections list the Property types and properties available for each type.

Record level

These properties define details about how data records are formatted in the flat file. Where you can enter
a character, this can usually be an ASCII character or a multi-byte Unicode character (if you have NLS
enabled). The available properties are:

Fill char

Specify an ASCII character or a value in the range 0 to 255. You can also choose Space or Null from a
drop-down list. This character is used to fill any gaps in a written record caused by column positioning
properties. Set to 0 by default (which is the NULL character). For example, to set it to space you could
also type in the space character or enter 32. Note that this value is restricted to one byte, so you cannot
specify a multi-byte Unicode character.

Final delimiter string

Specify a string to be written after the last column of a record in place of the column delimiter. Enter one
or more characters, this precedes the record delimiter if one is used. Mutually exclusive with Final
delimiter, which is the default. For example, if you set Delimiter to comma and Final delimiter string to `,
` (comma space - you do not need to enter the inverted commas) all fields are delimited by a comma,
except the final field, which is delimited by a comma followed by an ASCII space character.

Final delimiter

Specify a single character to be written after the last column of a record in place of the field delimiter.
Type a character or select one of whitespace, end, none, null, tab, or comma. See the following diagram
for an illustration.
v whitespace. The last column of each record will not include any trailing white spaces found at the end
of the record.
v end. The last column of each record does not include the field delimiter. This is the default setting.
v none. The last column of each record does not have a delimiter; used for fixed-width fields.
v null. The last column of each record is delimited by the ASCII null character.
v comma. The last column of each record is delimited by the ASCII comma character.

148 Parallel Job Developer Guide

v tab. The last column of each record is delimited by the ASCII tab character.
record delimiter

Field , Field , Field , Last field nl

Final delimiter = end

field delimiter

Field , Field , Field , Last field , nl

Final delimiter = comma

When writing, a space is now inserted after every field except the last in the record. Previously, a space
was inserted after every field including the last. (If you want to revert to the pre-release 7.5 behavior of
inserting a space after the last field, set the APT_FINAL_DELIM_COMPATIBLE environment variable.

Intact

The intact property specifies an identifier of a partial schema. A partial schema specifies that only the
column(s) named in the schema can be modified by the stage. All other columns in the row are passed
through unmodified. The file containing the partial schema is specified in the Schema File property on
the Properties tab. This property has a dependent property, Check intact, but this is not relevant to input
links.

Record delimiter string

Specify a string to be written at the end of each record. Enter one or more characters. This is mutually
exclusive with Record delimiter, which is the default, record type and record prefix.

Record delimiter

Specify a single character to be written at the end of each record. Type a character or select one of the
following:
v UNIX Newline (the default)
v null

(To implement a DOS newline, use the Record delimiter string property set to ″\R\N″ or chooseFormat
as → DOS line terminator from the shortcut menu.)

Note: Record delimiter is mutually exclusive with Record delimiter string, Record prefix, and Record
type.

Record length

Select Fixed where fixed length fields are being written. WebSphere DataStage calculates the appropriate
length for the record. Alternatively specify the length of fixed records as number of bytes. This is not
used by default (default files are comma-delimited). The record is padded to the specified length with
either zeros or the fill character if one has been specified.

Record Prefix

Chapter 9. External Target stage 149

Specifies that a variable-length record is prefixed by a 1-, 2-, or 4-byte length prefix. It is set to 1 by
default. This is mutually exclusive with Record delimiter, which is the default, and record delimiter string
and record type.

Record type

Specifies that data consists of variable-length blocked records (varying) or implicit records (implicit). If
you choose the implicit property, data is written as a stream with no explicit record boundaries. The end
of the record is inferred when all of the columns defined by the schema have been parsed. The varying
property allows you to specify one of the following IBM blocked or spanned formats: V, VB, VS, VBS, or
VR.

This property is mutually exclusive with Record length, Record delimiter, Record delimiter string, and
Record prefix and by default is not used.

Field defaults

Defines default properties for columns written to the file or files. These are applied to all columns
written, but can be overridden for individual columns from the Columns tab using the Edit Column
Metadata dialog box. Where you can enter a character, this can usually be an ASCII character or a
multi-byte Unicode character (if you have NLS enabled). The available properties are:
v Actual field length. Specifies the number of bytes to fill with the Fill character when a field is
identified as null. When WebSphere DataStage identifies a null field, it will write a field of this length
full of Fill characters. This is mutually exclusive with Null field value.
v Delimiter. Specifies the trailing delimiter of all fields in the record. Type an ASCII character or select
one of whitespace, end, none, null, comma, or tab.
– whitespace. Whitespace characters at the end of a column are ignored, i.e., are not treated as part of
the column.
– end. The end of a field is taken as the delimiter, i.e., there is no separate delimiter. This is not the
same as a setting of `None’ which is used for fields with fixed-width columns.
– none. No delimiter (used for fixed-width).
– null. ASCII Null character is used.
– comma. ASCII comma character is used.
– tab. ASCII tab character is used.
v Delimiter string. Specify a string to be written at the end of each field. Enter one or more characters.
This is mutually exclusive with Delimiter, which is the default. For example, specifying `, ` (comma
space - you do not need to enter the inverted commas) would have each field delimited by `, ` unless
overridden for individual fields.
v Null field length. The length in bytes of a variable-length field that contains a null. When a
variable-length field is written, WebSphere DataStage writes a length value of null field length if the
field contains a null. This property is mutually exclusive with null field value.
v Null field value. Specifies the value written to null field if the source is set to null. Can be a number,
string, or C-type literal escape character. For example, you can represent a byte value by \ooo, where
each o is an octal digit 0 - 7 and the first o is < 4, or by \xhh, where each h is a hexadecimal digit 0 - F.
You must use this form to encode non-printable byte values.
This property is mutually exclusive with Null field length and Actual length. For a fixed width data
representation, you can use Pad char (from the general section of Type defaults) to specify a repeated
trailing character if the value you specify is shorter than the fixed width of the field.
v Prefix bytes. Specifies that each column in the data file is prefixed by 1, 2, or 4 bytes containing, as a
binary value, either the column’s length or the tag value for a tagged field.

150 Parallel Job Developer Guide

 You can use this option with variable-length fields. Variable-length fields can be either delimited by a
character or preceded by a 1-, 2-, or 4-byte prefix containing the field length. WebSphere DataStage
inserts the prefix before each field.
This property is mutually exclusive with the Delimiter, Quote, and Final Delimiter properties, which
are used by default.
v Print field. This property is not relevant for input links.
v Quote. Specifies that variable length fields are enclosed in single quotes, double quotes, or another
character or pair of characters. Choose Single or Double, or enter a character. This is set to double
quotes by default.
When writing, WebSphere DataStage inserts the leading quote character, the data, and a trailing quote
character. Quote characters are not counted as part of a field’s length.
v Vector prefix. For fields that are variable length vectors, specifies a 1-, 2-, or 4-byte prefix containing
the number of elements in the vector. You can override this default prefix for individual vectors.
Variable-length vectors must use either a prefix on the vector or a link to another field in order to
specify the number of elements in the vector. If the variable length vector has a prefix, you use this
property to indicate the prefix length. WebSphere DataStage inserts the element count as a prefix of
each variable-length vector field. By default, the prefix length is assumed to be one byte.

Type defaults

These are properties that apply to all columns of a specific data type unless specifically overridden at the
column level. They are divided into a number of subgroups according to data type.

General

These properties apply to several data types (unless overridden at column level):
v Byte order. Specifies how multiple byte data types (except string and raw data types) are ordered.
Choose from:
– little-endian. The high byte is on the right.
– big-endian. The high byte is on the left.
– native-endian. As defined by the native format of the machine. This is the default.
v Data Format. Specifies the data representation format of a field. Applies to fields of all data types
except string, ustring, and raw and to record, subrec or tagged fields containing at least one field that
is neither string nor raw. Choose from:
– binary
– text (the default)
A setting of binary has different meanings when applied to different data types:
– For decimals, binary means packed.
– For other numerical data types, binary means ″not text″.
– For dates, binary is equivalent to specifying the julian property for the date field.
– For time, binary is equivalent to midnight_seconds.
– For timestamp, binary specifies that the first integer contains a Julian day count for the date portion
of the timestamp and the second integer specifies the time portion of the timestamp as the number
of seconds from midnight. A binary timestamp specifies that two 32-but integers are written.
By default data is formatted as text, as follows:
– For the date data type, text specifies that the data to be written contains a text-based date in the
form %yyyy-%mm-%dd or in the default date format if you have defined a new one on an NLS
system (see WebSphere DataStage NLS Guide).

Chapter 9. External Target stage 151

 – For the decimal data type: a field represents a decimal in a string format with a leading space or ’-’
followed by decimal digits with an embedded decimal point if the scale is not zero. The destination
string format is: [+ | -]ddd.[ddd] and any precision and scale arguments are ignored.
– For numeric fields (int8, int16, int32, uint8, uint16, uint32, sfloat, and dfloat): WebSphere DataStage
assumes that numeric fields are represented as text.
– For the time data type: text specifies that the field represents time in the text-based form
%hh:%nn:%ss or in the default date format if you have defined a new one on an NLS system (see
WebSphere DataStage NLS Guide).
– For the timestamp data type: text specifies a text-based timestamp in the form %yyyy-%mm-%dd
%hh:%nn:%ss or in the default date format if you have defined a new one on an NLS system (see
WebSphere DataStage NLS Guide).
v Field max width. The maximum number of bytes in a column represented as a string. Enter a number.
This is useful where you are storing numbers as text. If you are using a fixed-width character set, you
can calculate the length exactly. If you are using variable-length character set, calculate an adequate
maximum width for your fields. Applies to fields of all data types except date, time, timestamp, and
raw; and record, subrec, or tagged if they contain at least one field of this type.
v Field width. The number of bytes in a field represented as a string. Enter a number. This is useful
where you are storing numbers as text. If you are using a fixed-width charset, you can calculate the
number of bytes exactly. If it’s a variable length encoding, base your calculation on the width and
frequency of your variable-width characters. Applies to fields of all data types except date, time,
timestamp, and raw; and record, subrec, or tagged if they contain at least one field of this type.
If you specify neither field width nor field max width, numeric fields written as text have the
following number of bytes as their maximum width:
– 8-bit signed or unsigned integers: 4 bytes
– 16-bit signed or unsigned integers: 6 bytes
– 32-bit signed or unsigned integers: 11 bytes
– 64-bit signed or unsigned integers: 21 bytes
– single-precision float: 14 bytes (sign, digit, decimal point, 7 fraction, ″E″, sign, 2 exponent)
– double-precision float: 24 bytes (sign, digit, decimal point, 16 fraction, ″E″, sign, 3 exponent)
v Pad char. Specifies the pad character used when strings or numeric values are written to an external
string representation. Enter a character (single-byte for strings, can be multi-byte for ustrings) or choose
null or space. The pad character is used when the external string representation is larger than required
to hold the written field. In this case, the external string is filled with the pad character to its full
length. Space is the default. Applies to string, ustring, and numeric data types and record, subrec, or
tagged types if they contain at least one field of this type.
v Character set. Specifies the character set. Choose from ASCII or EBCDIC. The default is ASCII. Applies
to all data types except raw and ustring and record, subrec, or tagged containing no fields other than
raw or ustring.

String

These properties are applied to columns with a string data type, unless overridden at column level.
v Export EBCDIC as ASCII. Select this to specify that EBCDIC characters are written as ASCII
characters. Applies to fields of the string data type and record, subrec, or tagged fields if they contain
at least one field of this type.
v Import ASCII as EBCDIC. Not relevant for input links.
For ASCII-EBCDIC and EBCDIC-ASCII conversion tables, see WebSphere DataStage Developer’s Help.

Decimal

These properties are applied to columns with a decimal data type unless overridden at column level.

152 Parallel Job Developer Guide

v Allow all zeros. Specifies whether to treat a packed decimal column containing all zeros (which is
normally illegal) as a valid representation of zero. Select Yes or No. The default is No.
v Decimal separator. Specify the ASCII character that acts as the decimal separator (period by default).
v Packed. Select an option to specify what the decimal columns contain, choose from:
– Yes to specify that the decimal columns contain data in packed decimal format (the default). This
has the following sub-properties:
Check. Select Yes to verify that data is packed, or No to not verify.
Signed. Select Yes to use the existing sign when writing decimal columns. Select No to write a
positive sign (0xf) regardless of the columns’ actual sign value.
– No (separate) to specify that they contain unpacked decimal with a separate sign byte. This has the
following sub-property:
Sign Position. Choose leading or trailing as appropriate.
– No (zoned) to specify that they contain an unpacked decimal in either ASCII or EBCDIC text. This
has the following sub-property:
Sign Position. Choose leading or trailing as appropriate.
– No (overpunch) to specify that the field has a leading or end byte that contains a character which
specifies both the numeric value of that byte and whether the number as a whole is negatively or
positively signed. This has the following sub-property:
Sign Position. Choose leading or trailing as appropriate.
v Precision. Specifies the precision where a decimal column is written in text format. Enter a number.
When a decimal is written to a string representation, WebSphere DataStage uses the precision and scale
defined for the source decimal field to determine the length of the destination string. The precision and
scale properties override this default. When they are defined, WebSphere DataStage truncates or pads
the source decimal to fit the size of the destination string. If you have also specified the field width
property, WebSphere DataStage truncates or pads the source decimal to fit the size specified by field
width.
v Rounding. Specifies how to round a decimal column when writing it. Choose from:
– up (ceiling). Truncate source column towards positive infinity. This mode corresponds to the IEEE
754 Round Up mode. For example, 1.4 becomes 2, -1.6 becomes -1.
– down (floor). Truncate source column towards negative infinity. This mode corresponds to the IEEE
754 Round Down mode. For example, 1.6 becomes 1, -1.4 becomes -2.
– nearest value. Round the source column towards the nearest representable value. This mode
corresponds to the COBOL ROUNDED mode. For example, 1.4 becomes 1, 1.5 becomes 2, -1.4
becomes -1, -1.5 becomes -2.
– truncate towards zero. This is the default. Discard fractional digits to the right of the right-most
fractional digit supported by the destination, regardless of sign. For example, if the destination is an
integer, all fractional digits are truncated. If the destination is another decimal with a smaller scale,
truncate to the scale size of the destination decimal. This mode corresponds to the COBOL
INTEGER-PART function. Using this method 1.6 becomes 1, -1.6 becomes -1.
v Scale. Specifies how to round a source decimal when its precision and scale are greater than those of
the destination. By default, when the WebSphere DataStage writes a source decimal to a string
representation, it uses the precision and scale defined for the source decimal field to determine the
length of the destination string. You can override the default by means of the precision and scale
properties. When you do, WebSphere DataStage truncates or pads the source decimal to fit the size of
the destination string. If you have also specified the field width property, WebSphere DataStage
truncates or pads the source decimal to fit the size specified by field width.

Numeric

These properties apply to integer and float fields unless overridden at column level.

Chapter 9. External Target stage 153

v C_format. Perform non-default conversion of data from integer or floating-point data to a string. This
property specifies a C-language format string used for writing integer or floating point strings. This is
passed to sprintf(). For example, specifying a C-format of %x and a field width of 8 ensures that
integers are written as 8-byte hexadecimal strings.
v In_format. This property is not relevant for input links..
v Out_format. Format string used for conversion of data from integer or floating-point data to a string.
This is passed to sprintf(). By default, WebSphere DataStage invokes the C sprintf() function to convert a
numeric field formatted as either integer or floating point data to a string. If this function does not
output data in a satisfactory format, you can specify the out_format property to pass formatting
arguments to sprintf().

Date

These properties are applied to columns with a date data type unless overridden at column level. All of
these are incompatible with a Data Format setting of Text.
v Days since. Dates are written as a signed integer containing the number of days since the specified
date. Enter a date in the form %yyyy-%mm-%dd or in the default date format if you have defined a
new one on an NLS system (see WebSphere DataStage NLS Guide).
v Format string. The string format of a date. By default this is %yyyy-%mm-%dd. For details about the
format, see .
v Is Julian. Select this to specify that dates are written as a numeric value containing the Julian day. A
Julian day specifies the date as the number of days from 4713 BCE January 1, 12:00 hours (noon) GMT.

Time

These properties are applied to columns with a time data type unless overridden at column level. All of
these are incompatible with a Data Format setting of Text.
v Format string. Specifies the format of columns representing time as a string. For details about the
format, see “Time formats” on page 33
v Is midnight seconds. Select this to specify that times are written as a binary 32-bit integer containing
the number of seconds elapsed from the previous midnight.

Timestamp

These properties are applied to columns with a timestamp data type unless overridden at column level.
v Format string. Specifies the format of a column representing a timestamp as a string. Defaults to
%yyyy-%mm-%dd %hh:%nn:%ss. The format combines the format for date strings and time strings. See
“Date formats” on page 30 and “Time formats” on page 33.

Output page
The Output page appears if the stage has a Reject link.

The General tab allows you to specify an optional description of the output link.

You cannot change the properties of a Reject link. The Properties tab for a reject link is blank.

Similarly, you cannot edit the column definitions for a reject link. The link uses the column definitions for
the link rejecting the data records.

154 Parallel Job Developer Guide

Using RCP with External Target stages
Runtime column propagation (RCP) allows WebSphere DataStage to be flexible about the columns you
define in a job. If RCP is enabled for a project, you can just define the columns you are interested in
using in a job, but ask WebSphere DataStage to propagate the other columns through the various stages.
So such columns can be extracted from the data source and end up on your data target without explicitly
being operated on in between.

External Target stages, unlike most other data targets, do not have inherent column definitions, and so
WebSphere DataStage cannot always tell where there are extra columns that need propagating. You can
only use RCP on External Target stages if you have used the Schema File property (see ″Schema File″) to
specify a schema which describes all the columns in the sequential files referenced by the stage. You need
to specify the same schema file for any similar stages in the job where you want to propagate columns.
Stages that will require a schema file are:
v Sequential File
v File Set
v External Source
v External Target
v Column Import
v Column Export

Chapter 9. External Target stage 155

156 Parallel Job Developer Guide
Chapter 10. Complex Flat File stage
The Complex Flat File (CFF) stage is a file stage. You can use the stage to read a file or write to a file, but
you cannot use the same stage to do both.

As a source, the CFF stage can have multiple output links and a single reject link. You can read data from
one or more complex flat files, including MVS data sets with QSAM and VSAM files. You can also read
data from files that contain multiple record types. The source data can contain one or more of the
following clauses:
v GROUP
v REDEFINES
v OCCURS
v OCCURS DEPENDING ON
CFF source stages run in parallel mode when they are used to read multiple files, but you can configure
the stage to run sequentially if it is reading only one file with a single reader.

As a target, the CFF stage can have a single input link and a single reject link. You can write data to one
or more complex flat files. You cannot write to MVS data sets or to files that contain multiple record
types.

Figure 1. This job has a Complex Flat File source stage with a single reject link, and a Complex Flat File target stage
with a single reject link.

Editing a Complex Flat File stage as a source

To edit a CFF stage as a source, you must provide details about the file that the stage will read, create
record definitions for the data, define the column metadata, specify record ID constraints, and select
output columns.

To edit a CFF stage as a source:

1. Open the CFF stage editor.
2. On the Stage page, specify information about the stage data:
a. On the File Options tab, provide details about the file that the stage will read.
© Copyright IBM Corp. 2006 157
 b. On the Record Options tab, describe the format of the data in the file.
c. If the stage is reading a file that contains multiple record types, on the Records tab, create record
definitions for the data.
d. On the Records tab, create or load column definitions for the data.
e. If the stage is reading a file that contains multiple record types, on the Records ID tab, define the
record ID constraint for each record.
f. Optional: On the Advanced tab, change the processing settings.
3. On the Output page, specify how to read data from the source file:
a. On the Selection tab, select one or more columns for each output link.
b. Optional: On the Constraint tab, define a constraint to filter the rows on each output link.
c. Optional: On the Advanced tab, change the buffering settings.
4. Click OK to save your changes and to close the CFF stage editor.

Creating record definitions

If you are reading data from a file that contains multiple record types, you must create a separate record
definition for each type.

To create record definitions:

1. Click the Records tab on the Stage page.
2. Clear the Single record check box.
3. Right-click the default record definition RECORD_1 and select Rename Current Record.
4. Type a new name for the default record definition.
5. Add another record by clicking one of the buttons at the bottom of the records list. Each button offers
a different insertion point. A new record is created with the default name of NEWRECORD.
6. Double-click NEWRECORD to rename it.
7. Repeat steps 3 and 4 for each new record that you need to create.
8. Right-click the master record in the list and select Toggle Master Record. Only one master record is
permitted.

Column definitions
You must define columns to specify what data the CFF stage will read or write.

If the stage will read data from a file that contains multiple record types, you must first create record
definitions on the Records tab. If the source file contains only one record type, or if the stage will write
data to a target file, then the columns belong to the default record called RECORD_1.

You can load column definitions from a table in the repository, or you can type column definitions into
the columns grid. You can also define columns by dragging a table definition from the Repository
window to the CFF stage icon on the Designer canvas. If you drag a table to a CFF source stage that has
multiple record types, the columns are added to the first record in the stage. You can then propagate the
columns to one or more output links by right-clicking the stage icon and selecting Propagate Columns
from the pop-up menu.

The columns that you define must reflect the actual layout of the file format. If you do not want to
display all of the columns, you can create fillers to replace the unwanted columns by selecting the Create
fillers check box in the Select Columns From Table window. For more information about fillers, see
“Filler creation and expansion” on page 159.

After you define columns, the CFF stage projects the columns to the Selection tab on the Output page if
you are using the stage as a source, or to the Columns tab on the Input page if you are using the stage as
a target.

158 Parallel Job Developer Guide

Loading columns
The fastest way to define column metadata is to load columns from a table definition in the repository.

If you load more than one table definition, the list of columns from the subsequent tables is added to the
end of the current list. If the first column of the subsequent list has a level number higher than the last
column of the current list, the CFF stage inserts a 02 FILLER group item before the subsequent list is
loaded. However, if the first column that is being loaded already has a level number of 02, then no 02
FILLER group item is inserted.

To load columns:
1. Click the Records tab on the Stage page.
2. Click Load to open the Table Definitions window. This window displays all of the repository objects
that are in the current project.
3. Select a table definition in the repository tree and click OK.
4. Select the columns to load in the Select Columns From Table window and click OK.
5. If flattening is an option for any arrays in the column structure, specify how to handle array data in
the Complex File Load Option window. See “Complex file load options” on page 160 for details.

Typing columns
You can also define column metadata by typing column definitions in the columns grid.

To type columns:
1. Click the Records tab on the Stage page.
2. In the Level number field of the grid, specify the COBOL level number where the data is defined. If
you do not specify a level number, a default value of 05 is used.
3. In the Column name field, type the name of the column.
4. In the Native type field, select the native data type.
5. In the Length field, specify the data precision.
6. In the Scale field, specify the data scale factor.
7. Optional: In the Description field, type a description of the column.

You can edit column properties by selecting a property in the properties tree and making changes in the
Value field. Use the Available properties to add field to add optional attributes to the properties tree.

If you need to specify COBOL attributes, open the Edit Column Meta Data window by right-clicking
anywhere in the columns grid and selecting Edit row from the pop-up menu.

Filler creation and expansion

When you load columns into a CFF stage, you can create fillers to save storage space and processing
time.

Mainframe table definitions frequently contain hundreds of columns. If you do not want to display all of
these columns in the CFF stage, you can create fillers. When you load columns into the stage, select the
Create fillers check box in the Select Columns From Table window. This check box is selected by default
and is available only when you load columns from a simple or complex flat file.

The sequences of unselected columns are collapsed into FILLER items with a storage length that is equal
to the sum of the storage length of each individual column that is being replaced. The native data type is
set to CHARACTER, and the name is set to FILLER_XX_YY, where XX is the start offset and YY is the
end offset. Fillers for elements of a group array or an OCCURS DEPENDING ON (ODO) column have
the name of FILLER_NN, where NN is the element number. The NN begins at 1 for the first unselected
group element and continues sequentially. Any fillers that follow an ODO column are also numbered
sequentially.

Chapter 10. Complex Flat File stage 159

You can expand fillers on the Records tab if you want to reselect any columns. Right-click a filler either in
the columns grid or the columns tree and select Expand filler from the pop-up menu. In the Expand
Filler window, you can select some or all of the columns from the given filler. You do not need to reload
the table definition and reselect the columns.

See Appendix C, “Fillers,” on page 605 for examples of how fillers are created for different COBOL
structures.

Complex file load options

If you define columns that contain arrays, you must specify how the CFF stage should process the array
data.

The Complex File Load Option window opens when you load or type column definitions that contain
arrays on the Records tab. This window displays the names of the column definitions and their structure.
Array sizes are shown in parentheses. Select one of the following options to specify how the stage should
process arrays:
v Flatten selective arrays. Specifies that arrays can be selected for flattening on an individual basis. This
option is the default. Right-click an array in the columns list and select Flatten from the pop-up menu.
Columns that cannot be flattened are not available for selection. The array icon changes for the arrays
that will be flattened.
v Flatten all arrays. Flattens all arrays and creates a column for each element of the arrays.
v As is. Passes arrays with no changes.

If you choose to pass an array as is, the columns with arrays are loaded as is.

If you choose to flatten an array, all elements of the array will appear as separate columns in the table
definition. The data is presented as one row at run time. Each array element is given a numeric suffix to
make its name unique.

Consider the following complex flat file structure (in COBOL file definition format):
05 ID PIC X(10)
05 NAME PIC X(30)
05 CHILD PIC X(30) OCCURS 5 TIMES

Flattening the array results in the following column definitions:

05 ID PIC X(10)
05 NAME PIC X(30)
05 CHILD PIC X(30)
05 CHILD_2 PIC X(30)
05 CHILD_3 PIC X(30)
05 CHILD_4 PIC X(30)
05 CHILD_5 PIC X(30)

A parallel array is flattened in the same way.

Array columns that have redefined fields or OCCURS DEPENDING ON clauses cannot be flattened.
Even if you choose to flatten all arrays in the Complex File Load Option window, these columns are
passed as is.

Defining record ID constraints

If you are using the CFF stage to read data from a file that contains multiple record types, you must
specify a record ID constraint to identify the format of each record.

Columns that are identified in the record ID clause must be in the same physical storage location across
records. The constraint must be a simple equality expression, where a column equals a value.

160 Parallel Job Developer Guide

To define a record ID constraint:
1. Click the Records ID tab on the Stage page.
2. Select a record from the Records list.
3. Select the record ID column from the Column list. This list displays all columns from the selected
record, except the first OCCURS DEPENDING ON (ODO) column and any columns that follow it.
4. Select the = operator from the Op list.
5. Type the identifying value for the record ID column in the Value field. Character values must be
enclosed in single quotation marks.

Selecting output columns

By selecting output columns, you specify which columns from the source file the CFF stage should pass
to the output links.

You can select columns from multiple record types to output from the stage. If you do not select columns
to output on each link, the CFF stage automatically propagates all of the stage columns except group
columns to each empty output link when you click OK to exit the stage.

To select output columns:

1. Click the Selection tab on the Output page.
2. If you have multiple output links, select the link that you want from the Output name list.
3. Select columns for the output link by using one of the following methods:

Option Description
To select individual columns Press Ctrl and click the columns in the Available
columns tree, then click > to move them to the Selected
columns list.
To select all columns from a single record definition Click the record name or any of its columns in the
Available columns tree and click >> to move them to the
Selected columns list. By default, group columns are not
included, unless you first select the Enable all group
column selection check box.

If you select columns out of order, they are reordered in the Selected columns list to match the
structure of the input columns.

Array columns
If you select an array column for output, the CFF stage passes data to the output link data in different
ways depending on the type of array you select.

When you load array columns into a CFF stage, you must specify how to process the array data. You can
pass the data as is, flatten all arrays on input to the stage, or flatten selected arrays on input. You choose
one of these options from the Complex File Load Option window, which opens when you load column
definitions on the Records tab.

If you choose to flatten arrays, the flattening is done at the time that the column metadata is loaded into
the stage. All of the array elements appear as separate columns in the table. Each array column has a
numeric suffix to make its name unique. You can select any or all of these columns for output.

If you choose to pass arrays as is, the array structure is preserved. The data is presented as a single row
at run time for each incoming row. If the array is normalized, the incoming single row is resolved into
multiple output rows.

The following examples show how the CFF stage passes data to the output link from different types of
array columns, including:

Chapter 10. Complex Flat File stage 161

v “Simple normalized array columns”
v “Nested normalized array columns”
v “Parallel normalized array columns”
v “Nested parallel denormalized array columns” on page 163

Simple normalized array columns

A simple array is a single, one-dimensional array. This example shows the result when you select all
columns as output columns. For each record that is read from the input file, five rows are written to the
output link. The sixth row out the link causes the second record to be read from the file, starting the
process over again.

Input record:
05 ID PIC X(10)
05 NAME PIC X(30)
05 CHILD PIC X(30) OCCURS 5 TIMES.

Output rows:
Row 1: ID NAME CHILD(1)
Row 2: ID NAME CHILD(2)
Row 3: ID NAME CHILD(3)
Row 4: ID NAME CHILD(4)
Row 5: ID NAME CHILD(5)

Nested normalized array columns

This example shows the result when you select a nested array column as output. If you select FIELD-A,
FIELD-C and FIELD-D as output columns, the CFF stage multiplies the OCCURS values at each level. In
this case, 6 rows are written to the output link.

Input record:
05 FIELD-A PIC X(4)
05 FIELD-B OCCURS 2 TIMES.
10 FIELD-C PIC X(4)
10 FIELD-D PIC X(4) OCCURS 3 TIMES.

Output rows:
Row 1: FIELD-A FIELD-C(1) FIELD-D(1,1)
Row 2: FIELD-A FIELD-C(1) FIELD-D(1,2)
Row 3: FIELD-A FIELD-C(1) FIELD-D(1,3)
Row 4: FIELD-A FIELD-C(2) FIELD-D(2,1)
Row 5: FIELD-A FIELD-C(2) FIELD-D(2,2)
Row 6: FIELD-A FIELD-C(2) FIELD-D(2,3)

Parallel normalized array columns

Parallel arrays are array columns that have the same level number. The first example shows the result
when you select all parallel array columns as output columns. The CFF stage determines the number of
output rows by using the largest subscript. As a result, the smallest array is padded with default values
and the element columns are repeated. In this case, if you select all of the input fields as output columns,
four rows are written to the output link.

Input record:

162 Parallel Job Developer Guide

05 FIELD-A PIC X(4)
05 FIELD-B PIC X(4) OCCURS 2 TIMES.
05 FIELD-C PIC X(4)
05 FIELD-D PIC X(4) OCCURS 3 TIMES.
05 FIELD-E PIC X(4) OCCURS 4 TIMES.

Output rows:
Row 1: FIELD-A FIELD-B(1) FIELD-C FIELD-D(1) FIELD-E(1)
Row 2: FIELD-A FIELD-B(2) FIELD-C FIELD-D(2) FIELD-E(2)
Row 3: FIELD-A FIELD-C FIELD-D(3) FIELD-E(3)
Row 4: FIELD-A FIELD-C FIELD-E(4)

In the next example, only a subset of the parallel array columns are selected (FIELD-B and FIELD-E).
FIELD-D is passed as is. The number of output rows is determined by the maximum size of the
denormalized columns. In this case, four rows are written to the output link.

Output rows:
Row 1: FIELD-A FIELD-B(1) FIELD-C FIELD-D(1) FIELD-D(2) FIELD-D(3) FIELD-E(1)
Row 2: FIELD-A FIELD-B(2) FIELD-C FIELD-D(1) FIELD-D(2) FIELD-D(3) FIELD-E(2)
Row 3: FIELD-A FIELD-C FIELD-D(1) FIELD-D(2) FIELD-D(3) FIELD-E(3)
Row 4: FIELD-A FIELD-C FIELD-D(1) FIELD-D(2) FIELD-D(3) FIELD-E(4)

Nested parallel denormalized array columns

This complex example shows the result when you select both parallel array fields and nested array fields
as output. If you select FIELD-A, FIELD-C, and FIELD-E as output columns in this example, the CFF
stage determines the number of output rows by using the largest OCCURS value at each level and
multiplying them. In this case, 3 is the largest OCCURS value at the outer (05) level, and 5 is the largest
OCCURS value at the inner (10) level. Therefore, 15 rows are written to the output link. Some of the
subscripts repeat. In particular, subscripts that are smaller than the largest OCCURS value at each level
start over, including the second subscript of FIELD-C and the first subscript of FIELD-E.
05 FIELD-A PIC X(10)
05 FIELD-B OCCURS 3 TIMES.
10 FIELD-C PIC X(2) OCCURS 4 TIMES.
05 FIELD-D OCCURS 2 TIMES.
10 FIELD-E PIC 9(3) OCCURS 5 TIMES.

Output rows:
Row 1: FIELD-A FIELD-C(1,1) FIELD-E(1,1)
Row 2: FIELD-A FIELD-C(1,2) FIELD-E(1,2)
Row 3: FIELD-A FIELD-C(1,3) FIELD-E(1,3)
Row 4: FIELD-A FIELD-C(1,4) FIELD-E(1,4)
Row 5: FIELD-A FIELD-E(1,5)
Row 6: FIELD-A FIELD-C(2,1) FIELD-E(2,1)
Row 7: FIELD-A FIELD-C(2,2) FIELD-E(2,2)
Row 8: FIELD-A FIELD-C(2,3) FIELD-E(2,3)
Row 9: FIELD-A FIELD-C(2,4) FIELD-E(2,4)
Row 10: FIELD-A FIELD-E(2,5)
Row 11: FIELD-A FIELD-C(3,1)
Row 12: FIELD-A FIELD-C(3,2)
Row 13: FIELD-A FIELD-C(3,3)
Row 14: FIELD-A FIELD-C(3,4)
Row 15: FIELD-A

Group columns
If you select a group column for output, the CFF stage passes data to the output link data in different
ways depending on your selection.

Group columns contain elements or subgroups. When you select groups or their elements for output, the
CFF stage handles them in the following manner:

Chapter 10. Complex Flat File stage 163

v If you select a group column with any of its elements, the group column and the selected element
columns are passed as group and element columns.
v If you select only elements of the group and not the group column itself, the selected element columns
are treated as individual columns. Even if the selected element columns are within multiple or nested
groups, all element columns are treated as top-level columns in the selection list on the Selection tab.
v You cannot select a group column without any of its elements.

Defining output link constraints

By defining a constraint, you can filter the data on each output link from the CFF stage.

You can set the output link constraint to match the record ID constraint for each selected output record
by clicking Default on the Constraint tab on the Output page. The Default button is available only when
the constraint grid is empty. For more information about record ID constraints, see “Defining record ID
constraints” on page 160.

To define an output link constraint:

1. Click the Constraint tab on the Output page.
2. In the ( field of the grid, select an opening parenthesis if needed. You can use parentheses to specify
the order in evaluating a complex constraint expression.
3. In the Column field, select a column or job parameter. (Group columns cannot be used in constraint
expressions and are not displayed.)
4. In the Op field, select an operator or a logical function.
5. In the Column/Value field, select a column or job parameter, or double-click in the cell to type a
value. Enclose character values in single quotation marks.
6. In the ) field, select a closing parenthesis if needed.
7. If you are building a complex expression, in the Logical field, select AND or OR to continue the
expression in the next row.
8. Click Verify. If errors are found, you must either correct the expression, click Clear All to start over,
or cancel. You cannot save an incorrect constraint.

The order of operators in expressions is determined by SQL standards. After you verify a constraint, any
redundant parentheses might be removed.

Editing a Complex Flat File stage as a target

To edit a CFF stage as a target, you must provide details about the file that the stage will write, define
the record format of the data, and define the column metadata.

To edit a CFF stage as a target:

1. Open the CFF stage editor.
2. On the Stage page, specify information about the stage data:
a. On the File Options tab, provide details about the file that the stage will write.
b. On the Record Options tab, describe the format of the data in the file.
c. On the Records tab, create or load column definitions for the data. See “Column definitions” on
page 158 for information about how to define columns.
d. Optional: On the Advanced tab, change the processing settings.
3. Optional: On the Input page, specify how to write data to the target file:
a. On the Advanced tab, change the buffering settings.
b. On the Partitioning tab, change the partitioning settings.
4. Click OK to save your changes and to close the CFF stage editor.

164 Parallel Job Developer Guide

Reject links
The CFF stage can have a single reject link, whether you use the stage as a source or a target.

For CFF source stages, reject links are supported only if the source file contains a single record type
without any OCCURS DEPENDING ON (ODO) columns. For CFF target stages, reject links are
supported only if the target file does not contain ODO columns.

You cannot change the selection properties of a reject link. The Selection tab for a reject link is blank.

You cannot edit the column definitions for a reject link. For writing files, the reject link uses the input
link column definitions. For reading files, the reject link uses a single column named ″rejected″ that
contains raw data for the columns that were rejected after reading because they did not match the
schema.

Chapter 10. Complex Flat File stage 165

166 Parallel Job Developer Guide
Chapter 11. Transformer stage
The Transformer stage is a processing stage. It appears under the processing category in the tool palette.
Transformer stages allow you to create transformations to apply to your data. These transformations can
be simple or complex and can be applied to individual columns in your data. Transformations are
specified using a set of functions. Details of available functions are given in Appendix B.

Transformer stages can have a single input and any number of outputs. It can also have a reject link that
takes any rows which have not been written to any of the outputs links by reason of a write failure or
expression evaluation failure.

Unlike most of the other stages in a Parallel job, the Transformer stage has its own user interface. It does
not use the generic interface as described in Chapter 3, “Stage editors,” on page 37.

When you edit a Transformer stage, the Transformer Editor appears. An example Transformer stage is
shown below, this is the same Transformer as illustrated in the job above. The left pane represents input
data and the right pane, output data. The two links carrying data and the link carrying the data that has
failed to meet a criteria are all visible in the editor, the reject link is not.

Must do’s
This section specifies the minimum steps to take to get a Transformer stage functioning. WebSphere
DataStage provides a versatile user interface, and there are many shortcuts to achieving a particular end,
this section describes the basic method, you will learn where the shortcuts are when you get familiar
with the product.
v In the left pane:

© Copyright IBM Corp. 2006 167

 – Ensure that you have column meta data defined.
v In the right pane:
– Ensure that you have column meta data defined for each of the output links. The easiest way to do
this is to drag columns across from the input link.
– Define the derivation for each of your output columns. You can leave this as a straight mapping
from an input column, or explicitly define an expression to transform the data before it is output.
– Optionally specify a constraint for each output link. This is an expression which input rows must
satisfy before they are output on a link. Rows that are not output on any of the links can be output
on the otherwise link.
– Optionally specify one or more stage variables. This provides a method of defining expressions
which can be reused in your output columns derivations (stage variables are only visible within the
stage).

Transformer editor components

The Transformer Editor has the following components.

Toolbar
The Transformer toolbar contains the following buttons (from left to right):
v Stage properties
v Constraints
v Show all
v Show/hide stage variables
v Cut
v Copy
v Paste
v Find/replace
v Load column definition
v Save column definition
v Column auto-match
v Input link execution order
v Output link execution order

Link area
The top area displays links to and from the Transformer stage, showing their columns and the
relationships between them.

The link area is where all column definitions and stage variables are defined.

The link area is divided into two panes; you can drag the splitter bar between them to resize the panes
relative to one another. There is also a horizontal scroll bar, allowing you to scroll the view left or right.

The left pane shows the input link, the right pane shows output links. Output columns that have no
derivation defined are shown in red.

Within the Transformer Editor, a single link may be selected at any one time. When selected, the link’s
title bar is highlighted, and arrowheads indicate any selected columns within that link.

168 Parallel Job Developer Guide

Metadata area
The bottom area shows the column metadata for input and output links. Again this area is divided into
two panes: the left showing input link meta data and the right showing output link meta data.

The meta data for each link is shown in a grid contained within a tabbed page. Click the tab to bring the
required link to the front. That link is also selected in the link area.

If you select a link in the link area, its meta data tab is brought to the front automatically.

You can edit the grids to change the column meta data on any of the links. You can also add and delete
metadata.

As with column meta data grids on other stage editors, edit row in the context menu allows editing of
the full metadata definitions (see ″Columns Tab″ ).

Shortcut menus
The Transformer Editor shortcut menus are displayed by right-clicking the links in the links area.

There are slightly different menus, depending on whether you right-click an input link, an output link, or
a stage variable. The input link menu offers you operations on input columns, the output link menu
offers you operations on output columns and their derivations, and the stage variable menu offers you
operations on stage variables.

The shortcut menu enables you to:

v Open the Stage Properties dialog box in order to specify stage or link properties.
v Open the Constraints dialog box to specify a constraint (only available for output links).
v Open the Column Auto Match dialog box.
v Display the Find/Replace dialog box.
v Display the Select dialog box.
v Edit, validate, or clear a derivation, or stage variable.
v Edit several derivations in one operation.
v Append a new column or stage variable to the selected link.
v Select all columns on a link.
v Insert or delete columns or stage variables.
v Cut, copy, and paste a column or a key expression or a derivation or stage variable.

If you display the menu from the links area background, you can:
v Open the Stage Properties dialog box in order to specify stage or link properties.
v Open the Constraints dialog box in order to specify a constraint for the selected output link.
v Open the Link Execution Order dialog box in order to specify the order in which links should be
processed.
v Toggle between viewing link relations for all links, or for the selected link only.
v Toggle between displaying stage variables and hiding them.

Right-clicking in the meta data area of the Transformer Editor opens the standard grid editing shortcut
menus.

Chapter 11. Transformer stage 169

Transformer stage basic concepts
When you first edit a Transformer stage, it is likely that you will have already defined what data is input
to the stage on the input link. You will use the Transformer Editor to define the data that will be output
by the stage and how it will be transformed. (You can define input data using the Transformer Editor if
required.)

This section explains some of the basic concepts of using a Transformer stage.

Input link
The input data source is joined to the Transformer stage via the input link.

Output links
You can have any number of output links from your Transformer stage.

You may want to pass some data straight through the Transformer stage unaltered, but it’s likely that
you’ll want to transform data from some input columns before outputting it from the Transformer stage.

You can specify such an operation by entering a transform expression. The source of an output link
column is defined in that column’s Derivation cell within the Transformer Editor. You can use the
Expression Editor to enter expressions in this cell. You can also simply drag an input column to an
output column’s Derivation cell, to pass the data straight through the Transformer stage.

In addition to specifying derivation details for individual output columns, you can also specify
constraints that operate on entire output links. A constraint is an expression that specifies criteria that
data must meet before it can be passed to the output link. You can also specify a constraint otherwise
link, which is an output link that carries all the data not output on other links, that is, columns that have
not met the criteria.

Each output link is processed in turn. If the constraint expression evaluates to TRUE for an input row, the
data row is output on that link. Conversely, if a constraint expression evaluates to FALSE for an input
row, the data row is not output on that link.

Constraint expressions on different links are independent. If you have more than one output link, an
input row may result in a data row being output from some, none, or all of the output links.

For example, if you consider the data that comes from a paint shop, it could include information about
any number of different colors. If you want to separate the colors into different files, you would set up
different constraints. You could output the information about green and blue paint on LinkA, red and
yellow paint on LinkB, and black paint on LinkC.

When an input row contains information about yellow paint, the LinkA constraint expression evaluates to
FALSE and the row is not output on LinkA. However, the input data does satisfy the constraint criterion
for LinkB and the rows are output on LinkB.

If the input data contains information about white paint, this does not satisfy any constraint and the data
row is not output on Links A, B or C, but will be output on the otherwise link. The otherwise link is used
to route data to a table or file that is a ″catch-all″ for rows that are not output on any other link. The
table or file containing these rows is represented by another stage in the job design.

You can also specify another output link which takes rows that have not be written to any other links
because of write failure or expression evaluation failure. This is specified outside the stage by adding a
link and converting it to a reject link using the shortcut menu. This link is not shown in the Transformer
meta data grid, and derives its meta data from the input link. Its column values are those in the input
row that failed to be written.

170 Parallel Job Developer Guide

If you have enabled Runtime Column Propagation for an output link (see ″Output Page″ you do not have
to specify meta data for that link.

Editing Transformer stages

The Transformer Editor enables you to perform the following operations on a Transformer stage:
v Create new columns on a link
v Delete columns from within a link
v Move columns within a link
v Edit column meta data
v Define output column derivations
v Define link constraints and handle otherwise links
v Specify the order in which links are processed
v Define local stage variables

Using drag and drop

Many of the Transformer stage edits can be made simpler by using the Transformer Editor’s drag and
drop functionality. You can drag columns from any link to any other link. Common uses are:
v Copying input columns to output links
v Moving columns within a link
v Copying derivations in output links

To use drag and drop:

1. Click the source cell to select it.
2. Click the selected cell again and, without releasing the mouse button, drag the mouse pointer to the
desired location within the target link. An insert point appears on the target link to indicate where the
new cell will go.
3. Release the mouse button to drop the selected cell.

You can drag and drop multiple columns, key expressions, or derivations. Use the standard Explorer keys
when selecting the source column cells, then proceed as for a single cell.

You can drag and drop the full column set by dragging the link title.

You can add a column to the end of an existing derivation by holding down the Ctrl key as you drag the
column.

Find and replace facilities

If you are working on a complex job where several links, each containing several columns, go in and out
of the Transformer stage, you can use the find/replace column facility to help locate a particular column
or expression and change it.

The find/replace facility enables you to:

v Find and replace a column name
v Find and replace expression text
v Find the next empty expression
v Find the next expression that contains an error

Chapter 11. Transformer stage 171

To use the find/replace facilities, do one of the following:
v Click the find/replace button on the toolbar
v Choose find/replace from the link shortcut menu
v Type Ctrl-F

The Find and Replace dialog box appears. It has three tabs:
v Expression Text. Allows you to locate the occurrence of a particular string within an expression, and
replace it if required. You can search up or down, and choose to match case, match whole words, or
neither. You can also choose to replace all occurrences of the string within an expression.
v Columns Names. Allows you to find a particular column and rename it if required. You can search up
or down, and choose to match case, match the whole word, or neither.
v Expression Types. Allows you to find the next empty expression or the next expression that contains
an error. You can also press Ctrl-M to find the next empty expression or Ctrl-N to find the next
erroneous expression.

Note: The find and replace results are shown in the color specified in Tools lou8 Options.

Press F3 to repeat the last search you made without opening the Find and Replace dialog box.

Select facilities
If you are working on a complex job where several links, each containing several columns, go in and out
of the Transformer stage, you can use the select column facility to select multiple columns. This facility is
also available in the Mapping tabs of certain Parallel job stages.

The select facility enables you to:

v Select all columns/stage variables whose expressions contains text that matches the text specified.
v Select all column/stage variables whose name contains the text specified (and, optionally, matches a
specified type).
v Select all columns/stage variable with a certain data type.
v Select all columns with missing or invalid expressions.

To use the select facilities, choose Select from the link shortcut menu. The Select dialog box appears. It
has three tabs:
v Expression Text. This Expression Text tab allows you to select all columns/stage variables whose
expressions contain text that matches the text specified. The text specified is a simple text match, taking
into account the Match case setting.
v Column Names. The Column Names tab allows you to select all column/stage variables whose Name
contains the text specified. There is an additional Data Type drop down list, that will limit the columns
selected to those with that data type. You can use the Data Type drop down list on its own to select all
columns of a certain data type. For example, all string columns can be selected by leaving the text field
blank, and selecting String as the data type. The data types in the list are generic data types, where
each of the column SQL data types belong to one of these generic types.
v Expression Types. The Expression Types tab allows you to select all columns with either empty
expressions or invalid expressions.

Creating and deleting columns

You can create columns on links to the Transformer stage using any of the following methods:
v Select the link, then click the load column definition button in the toolbar to open the standard load
columns dialog box.

172 Parallel Job Developer Guide

v Use drag and drop or copy and paste functionality to create a new column by copying from an
existing column on another link.
v Use the shortcut menus to create a new column definition.
v Edit the grids in the link’s meta data tab to insert a new column.

When copying columns, a new column is created with the same meta data as the column it was copied
from.

To delete a column from within the Transformer Editor, select the column you want to delete and click
the cut button or choose Delete Column from the shortcut menu.

Moving columns within a link

You can move columns within a link using either drag and drop or cut and paste. Select the required
column, then drag it to its new location, or cut it and paste it in its new location.

Editing column meta data

You can edit column meta data from within the grid in the bottom of the Transformer Editor. Select the
tab for the link meta data that you want to edit, then use the standard WebSphere DataStage edit grid
controls.

The meta data shown does not include column derivations since these are edited in the links area.

Defining output column derivations

You can define the derivation of output columns from within the Transformer Editor in five ways:
v If you require a new output column to be directly derived from an input column, with no
transformations performed, then you can use drag and drop or copy and paste to copy an input
column to an output link. The output columns will have the same names as the input columns from
which they were derived.
v If the output column already exists, you can drag or copy an input column to the output column’s
Derivation field. This specifies that the column is directly derived from an input column, with no
transformations performed.
v You can use the column auto-match facility to automatically set that output columns are derived from
their matching input columns.
v You may need one output link column derivation to be the same as another output link column
derivation. In this case you can use drag and drop or copy and paste to copy the derivation cell from
one column to another.
v In many cases you will need to transform data before deriving an output column from it. For these
purposes you can use the Expression Editor. To display the Expression Editor, double-click on the
required output link column Derivation cell. (You can also invoke the Expression Editor using the
shortcut menu or the shortcut keys.)

Note: To access a vector element in a column derivation, you need to use an expression containing the
vector function - see ″Vector Function″ .

If a derivation is displayed in red (or the color defined in Tools → Options), it means that the Transformer
Editor considers it incorrect.

Once an output link column has a derivation defined that contains any input link columns, then a
relationship line is drawn between the input column and the output column, as shown in the following

Chapter 11. Transformer stage 173

example. This is a simple example; there can be multiple relationship lines either in or out of columns.
You can choose whether to view the relationships for all links, or just the relationships for the selected
links, using the button in the toolbar.

Column auto-match facility

This time-saving feature allows you to automatically set columns on an output link to be derived from
matching columns on an input link. Using this feature you can fill in all the output link derivations to
route data from corresponding input columns, then go back and edit individual output link columns
where you want a different derivation.

To use this facility:

1. Do one of the following:
v Click the Auto-match button in the Transformer Editor toolbar.
v Choose Auto-match from the input link header or output link header shortcut menu.
The Column Auto-Match dialog box appears.
2. Choose the output link that you want to match columns with the input link from the drop down list.
3. Click Location match or Name match from the Match type area.
If you choose Location match, this will set output column derivations to the input link columns in the
equivalent positions. It starts with the first input link column going to the first output link column,
and works its way down until there are no more input columns left.
4. Click OK to proceed with the auto-matching.

Note: Auto-matching does not take into account any data type incompatibility between matched
columns; the derivations are set regardless.

Editing multiple derivations

You can make edits across several output column or stage variable derivations by choosing Derivation
Substitution... from the shortcut menu. This opens the Expression Substitution dialog box.

The Expression Substitution dialog box allows you to make the same change to the expressions of all the
currently selected columns within a link. For example, if you wanted to add a call to the trim() function
around all the string output column expressions in a link, you could do this in two steps. First, use the
Select dialog to select all the string output columns. Then use the Expression Substitution dialog to apply
a trim() call around each of the existing expression values in those selected columns.

You are offered a choice between Whole expression substitution and Part of expression substitution.

Whole expression
With this option the whole existing expression for each column is replaced by the replacement value
specified. This replacement value can be a completely new value, but will usually be a value based on
the original expression value. When specifying the replacement value, the existing value of the column’s
expression can be included in this new value by including ″$1″. This can be included any number of
times.

For example, when adding a trim() call around each expression of the currently selected column set,
having selected the required columns, you would:
1. Select the Whole expression option.
2. Enter a replacement value of:
trim($1)
3. Click OK

174 Parallel Job Developer Guide

Where a column’s original expression was:
DSLink3.col1

This will be replaced by:

trim(DSLink3.col1)

This is applied to the expressions in each of the selected columns.

If you need to include the actual text $1 in your expression, enter it as ″$$1″.

Part of expression
With this option, only part of each selected expression is replaced rather than the whole expression. The
part of the expression to be replaced is specified by a Regular Expression match.

It is possible that more that one part of an expression string could match the Regular Expression
specified. If Replace all occurrences is checked, then each occurrence of a match will be updated with the
replacement value specified. If it is not checked, then just the first occurrence is replaced.

When replacing part of an expression, the replacement value specified can include that part of the
original expression being replaced. In order to do this, the Regular Expression specified must have round
brackets around its value. ″$1″ in the replacement value will then represent that matched text. If the
Regular Expression is not surrounded by round brackets, then ″$1″ will simply be the text ″$1″.

For complex Regular Expression usage, subsets of the Regular Expression text can be included in round
brackets rather than the whole text. In this case, the entire matched part of the original expression is still
replaced, but ″$1″, ″$2″ etc can be used to refer to each matched bracketed part of the Regular Expression
specified.

The following is an example of the Part of expression replacement.

Suppose a selected set of columns have derivations that use input columns from `DSLink3’. For example,
two of these derivations could be:
DSLink3.OrderCount + 1
If (DSLink3.Total > 0) Then DSLink3.Total Else -1

You may want to protect the usage of these input columns from null values, and use a zero value instead
of the null. To do this:
1. Select the columns you want to substitute expressions for.
2. Select the Part of expression option.
3. Specify a Regular Expression value of:
(DSLink3\.[a-z,A-Z,0-9]*)
4. Specify a replacement value of
NullToZero($1)
5. Click OK, to apply this to all the selected column derivations.

From the examples above:

DSLink3.OrderCount + 1

would become
NullToZero(DSLink3.OrderCount) + 1

and
If (DSLink3.Total > 0) Then DSLink3.Total Else -1

Chapter 11. Transformer stage 175

would become:
If (NullToZero(DSLink3.Total) > 0) Then DSLink3.Total Else -1

If the Replace all occurrences option is selected, the second expression will become:
If (NullToZero(DSLink3.Total) > 0)
Then NullToZero(DSLink3.Total)
Else -1

The replacement value can be any form of expression string. For example in the case above, the
replacement value could have been:
(If (StageVar1 > 50000) Then $1 Else ($1 + 100))

In the first case above, the expression

DSLink3.OrderCount + 1

would become:
(If (StageVar1 > 50000) Then DSLink3.OrderCount
Else (DSLink3.OrderCount + 100)) + 1

Handling null values in input columns

If you use input columns in an output column expression, be aware that a null value in that input
column will cause the row to be dropped or, if a reject link has been defined, rejected.

This applies where:

v An input column is used in an output column derivation expression (for example, an expression like
″DSLink4.col1 + 1″).
v An input column is used in an output column constraint.
v An input column is used in a stage variable derivation.

It does not apply where an output column is mapped directly from an input column, with a straight
assignment expression.

If you need to be able to handle nulls in these situations, you should use the null handling functions
described in Appendix B. For example, you could enter an output column derivation expression
including the expression:
1 + NullToZero(InLink.Col1)

This would check the input column to see if it contains a null, and if it did, replace it with 0 (which is
added to 1). Otherwise the value the column contains is added to 1.

Defining constraints and handling otherwise links

You can define limits for output data by specifying a constraint. Constraints are expressions and you can
specify a constraint for each output link from a Transformer stage. You can also specify that a particular
link is to act as an otherwise link and catch those rows that have failed to satisfy the constraints on all
other output links.

To define a constraint or specify an otherwise link, do one of the following:

v Select an output link and click the constraints button.
v Double-click the output link’s constraint entry field.
v Choose Constraints from the background or header shortcut menus.

176 Parallel Job Developer Guide

A dialog box appears which allows you either to define constraints for any of the Transformer output
links or to define a link as an otherwise link.

Define a constraint by entering an expression in the Constraint field for that link. Once you have done
this, any constraints will appear below the link’s title bar in the Transformer Editor. This constraint
expression will then be checked against the row data at runtime. If the data does not satisfy the
constraint, the row will not be written to that link. It is also possible to define a link which can be used
to catch these rows which have been not satisfied the constraints on any previous links.

A constraint otherwise link can be defined by:

v Clicking on the Otherwise/Log field so a tick appears and leaving the Constraint fields blank. This will
catch any rows that have failed to meet constraints on all the previous output links.
v Set the constraint to OTHERWISE. This will be set whenever a row is rejected on a link because the
row fails to match a constraint. OTHERWISE is cleared by any output link that accepts the row.
v The otherwise link must occur after the output links in link order so it will catch rows that have failed
to meet the constraints of all the output links. If it is not last rows may be sent down the otherwise
link which satisfy a constraint on a later link and is sent down that link as well.
v Clicking on the Otherwise/Log field so a tick appears and defining a Constraint. This will result in the
number of rows written to that link (i.e. rows which satisfy the constraint) to be recorded in the job log
as a warning message.

Note: You can also specify a reject link which will catch rows that have not been written on any
output links due to a write error or null expression error. Define this outside Transformer stage
by adding a link and using the shortcut menu to convert it to a reject link.

Specifying link order

You can specify the order in which output links process a row.

The initial order of the links is the order in which they are added to the stage.

To reorder the links:

1. Do one of the following:
v Click the output link execution order button on the Transformer Editor toolbar.
v Choose output link reorder from the background shortcut menu.
The Transformer Stage Properties dialog box appears with the Link Ordering tab of the Stage page
uppermost:.
2. Use the arrow buttons to rearrange the list of links in the execution order required.
3. When you are happy with the order, click OK.

Defining local stage variables

You can declare and use your own variables within a Transformer stage. Such variables are accessible
only from the Transformer stage in which they are declared. They can be used as follows:
v They can be assigned values by expressions.
v They can be used in expressions which define an output column derivation.
v Expressions evaluating a variable can include other variables or the variable being evaluated itself.

Any stage variables you declare are shown in a table in the right pane of the links area. The table looks
similar to an output link. You can display or hide the table by clicking the Stage Variable button in the
Transformer toolbar or choosing Stage Variable from the background shortcut menu.

Chapter 11. Transformer stage 177

Note: Stage variables are not shown in the output link meta data area at the bottom of the right pane.

The table lists the stage variables together with the expressions used to derive their values. Link lines join
the stage variables with input columns used in the expressions. Links from the right side of the table link
the variables to the output columns that use them.

To declare a stage variable:

1. Do one of the following:
v Select Insert New Stage Variable from the stage variable shortcut menu. A new variable is added
to the stage variables table in the links pane. The variable is given the default name StageVar and
default data type VarChar (255). You can edit these properties using the Transformer Stage
Properties dialog box, as described in the next step.
v Click the Stage Properties button on the Transformer toolbar.
v Select Stage Properties from the background shortcut menu.
v Select Stage Variable Properties from the stage variable shortcut menu.
The Transformer Stage Properties dialog box appears.
2. Using the grid on the Variables page, enter the variable name, initial value, SQL type, extended
information (if variable contains Unicode data), precision, scale, and an optional description. Variable
names must begin with an alphabetic character (a-z, A-Z) and can only contain alphanumeric
characters (a-z, A-Z, 0-9).
3. Click OK. The new variable appears in the stage variable table in the links pane.

You perform most of the same operations on a stage variable as you can on an output column (see
Defining Output Column Derivations). A shortcut menu offers the same commands. You cannot, however,
paste a stage variable as a new column, or a column as a new stage variable.

The WebSphere DataStage expression editor

The WebSphere DataStage Expression Editor helps you to enter correct expressions when you edit
Transformer stages. The Expression Editor can:
v Facilitate the entry of expression elements
v Complete the names of frequently used variables
v Validate the expression

The Expression Editor can be opened from:

v Output link Derivation cells
v Stage variable Derivation cells
v Constraint dialog box

Expression format
The format of an expression is as follows:
KEY:

something_like_this is a token
something_in_italics is a terminal, i.e., doesn’t break down any further
| is a choice between tokens
[ is an optional part of the construction
"XXX" is a literal token (i.e., use XXX not
including the quotes)
=================================================
expression ::= function_call |
variable_name |
other_name |

178 Parallel Job Developer Guide

 constant |
unary_expression |
binary_expression |
if_then_else_expression |
substring_expression |
"(" expression ")"

function_call ::= function_name "(" [argument_list] ")"

argument_list ::= expression | expression "," argument_list
function_name ::= name of a built-in function |
name of a user-defined_function
variable_name ::= job_parameter name |
stage_variable_name |
link_variable name
other_name ::= name of a built-in macro, system variable, etc.
constant ::= numeric_constant | string_constant
numeric_constant ::= ["+" | "-"] digits ["." [digits]] ["E" | "e" ["+" | "-"] digits]
string_constant ::= "’" [characters] "’" |
""" [characters] """ |
"\" [characters] "\"
unary_expression ::= unary_operator expression
unary_operator ::= "+" | "-"
binary_expression ::= expression binary_operator expression
binary_operator ::= arithmetic_operator |
concatenation_operator |
matches_operator |
relational_operator |
logical_operator
arithmetic_operator ::= "+" | "-" | "*" | "/" | "^"
concatenation_operator ::= ":"
relational_operator ::= " =" |"EQ" |
"<>" | "#" | "NE" |
">" | "GT" |
">=" | "=>" | "GE" |
"<" | "LT" |
"<=" | "=<" | "LE"
logical_operator ::= "AND" | "OR"
if_then_else_expression ::= "IF" expression "THEN" expression "ELSE" expression
substring_expression ::= expression "[" [expression ["," expression] "]"
field_expression ::= expression "[" expression ","
expression ","
expression "]"
/* That is, always 3 args

Note: keywords like ″AND″ or ″IF″ or ″EQ″ may be in any case

Entering expressions
Whenever the insertion point is in an expression box, you can use the Expression Editor to suggest the
next element in your expression. Do this by right-clicking the box, or by clicking the Suggest button to
the right of the box. This opens the Suggest Operand or Suggest Operator menu. Which menu appears
depends on context, i.e., whether you should be entering an operand or an operator as the next
expression element. The Functions available from this menu are described in Appendix B. The DS macros
are described in WebSphere DataStage Parallel Job Advanced Developer Guide You can also specify custom
routines for use in the expression editor (see in WebSphere DataStage Designer Client Guide).

Completing variable names

The Expression Editor stores variable names. When you enter a variable name you have used before, you
can type the first few characters, then press F5. The Expression Editor completes the variable name for
you.

Chapter 11. Transformer stage 179

If you enter the name of the input link followed by a period, for example, DailySales., the Expression
Editor displays a list of the column names of the link. If you continue typing, the list selection changes to
match what you type. You can also select a column name using the mouse. Enter a selected column name
into the expression by pressing Tab or Enter. Press Esc to dismiss the list without selecting a column
name.

Validating the expression

When you have entered an expression in the Transformer Editor, press Enter to validate it. The
Expression Editor checks that the syntax is correct and that any variable names used are acceptable to the
compiler.

If there is an error, a message appears and the element causing the error is highlighted in the expression
box. You can either correct the expression or close the Transformer Editor or Transform dialog box.

For any expression, selecting Validate from its shortcut menu will also validate it and show any errors in
a message box.

Exiting the expression editor

You can exit the Expression Editor in the following ways:
v Press Esc (which discards changes).
v Press Return (which accepts changes).
v Click outside the Expression Editor box (which accepts changes).

Configuring the expression editor

You can resize the Expression Editor window by dragging. The next time you open the expression editor
in the same context (for example, editing output columns) on the same client, it will have the same size.

The Expression Editor is configured by editing the Designer options. This allows you to specify how
`helpful’ the expression editor is. For more information, see WebSphere DataStage Designer Client Guide.

System variables
WebSphere DataStage provides a set of variables containing useful system information that you can
access from an output derivation or constraint.
Name Description
@FALSE
The value is replaced with 0.
@TRUE
The value is replaced with 1.
@INROWNUM
Input row counter.
@OUTROWNUM
Output row counter (per link).
@NUMPARTITIONS
The total number of partitions for the stage.
@PARTITIONNUM
The partition number for the particular instance.

180 Parallel Job Developer Guide

Guide to using transformer expressions and stage variables
In order to write efficient Transformer stage derivations, it is useful to understand what items get
evaluated and when. The evaluation sequence is as follows:
Evaluate each stage variable initial value
For each input row to process:
Evaluate each stage variable derivation value, unless
the derivation is empty
For each output link:
Evaluate each column derivation value
Write the output record
Next output link
Next input row

The stage variables and the columns within a link are evaluated in the order in which they are displayed
on the parallel job canvas. Similarly, the output links are also evaluated in the order in which they are
displayed.

From this sequence, it can be seen that there are certain constructs that would be inefficient to include in
output column derivations, as they would be evaluated once for every output column that uses them.
Such constructs are:
v Where the same part of an expression is used in multiple column derivations.
For example, suppose multiple columns in output links want to use the same substring of an input
column, then the following test may appear in a number of output columns derivations:
IF (DSLINK1.col1[1,3] = "001") THEN ...
In this case, the evaluation of the substring of DSLINK1.col[1,3] is repeated for each column that uses
it.
This can be made more efficient by moving the substring calculation into a stage variable. By doing
this, the substring is evaluated just once for every input row. In this case, the stage variable definition
for StageVar1 would be:
DSLINK1.col1[1,3]
and each column derivation would start with:
IF (StageVar1 = "001") THEN ...
In fact, this example could be improved further by also moving the string comparison into the stage
variable. The stage variable would be:
IF (DSLink1.col1[1,3] = "001") THEN 1 ELSE 0
and each column derivation would start with:
IF (StageVar1) THEN
This reduces both the number of substring functions evaluated and string comparisons made in the
Transformer.
v Where an expression includes calculated constant values.
For example, a column definition may include a function call that returns a constant value, such as:
Str(" ",20)
This returns a string of 20 spaces. In this case, the function would be evaluated every time the column
derivation is evaluated. It would be more efficient to calculate the constant value just once for the
whole Transformer.
This can be achieved using stage variables. This function could be moved into a stage variable
derivation; but in this case, the function would still be evaluated once for every input row. The
solution here is to move the function evaluation into the initial value of a stage variable.
A stage variable can be assigned an initial value from the Stage Properties dialog box Variables tab. In
this case, the variable would have its initial value set to:
Str(" ", 20)

Chapter 11. Transformer stage 181

 You would then leave the derivation of the stage variable on the main Transformer page empty. Any
expression that previously used this function would be changed to use the stage variable instead.
The initial value of the stage variable is evaluated just once, before any input rows are processed. Then,
because the derivation expression of the stage variable is empty, it is not re-evaluated for each input
row. Therefore, its value for the whole Transformer processing is unchanged from the initial value.
In addition to a function value returning a constant value, another example would be part of an
expression such as:
"abc" : "def"
As with the function-call example, this concatenation is repeated every time the column derivation is
evaluated. Since the subpart of the expression is actually constant, this constant part of the expression
could again be moved into a stage variable, using the initial value setting to perform the concatenation
just once.
v Where an expression requiring a type conversion is used as a constant, or it is used in multiple places.
For example, an expression may include something like this:
DSLink1.col1+"1"
In this case, the ″1″ is a string constant, and so, in order to be able to add it to DSLink1.col1, it must be
converted from a string to an integer each time the expression is evaluated. The solution in this case is
just to change the constant from a string to an integer:
DSLink1.col1+1
In this example, if DSLINK1.col1 were a string field, then, again, a conversion would be required every
time the expression is evaluated. If this just appeared once in one output column expression, this
would be fine. However, if an input column is used in more than one expression, where it requires the
same type conversion in each expression, then it would be more efficient to use a stage variable to
perform the conversion once. In this case, you would create, for example, an integer stage variable,
specify its derivation to be DSLINK1.col1, and then use the stage variable in place of DSLink1.col1,
where that conversion would have been required.
Note that, when using stage variables to evaluate parts of expressions, the data type of the stage
variable should be set correctly for that context. Otherwise, needless conversions are required wherever
that variable is used.

Transformer stage properties

The Transformer stage has a Properties dialog box which allows you to specify details about how the
stage operates.

The Transform Stage Properties dialog box has three pages:

v Stage Page. This is used to specify general information about the stage.
v Input Page. This is where you specify details about the data input to the Transformer stage.
v Output Page. This is where you specify details about the output links from the Transformer stage.

Stage page
The Stage page has up to eight tabs:
v General. Allows you to enter an optional description of the stage.
v Variables. Allows you to set up stage variables for use in the stage.
v Surrogate Key. Allows you to generate surrogate keys that can be used in complex lookup and update
operations.
v Advanced. Allows you to specify how the stage executes.
v Link Ordering. Allows you to specify the order in which the output links will be processed.
v Triggers. Allows you to run certain routines at certain points in the stage’s execution.
v NLS Locale. Allows you to select a locale other than the project default to determine collating rules.
182 Parallel Job Developer Guide
v Build. Allows you to override the default compiler and linker flags for this stag.

The Variables tab is described in ″Defining Local Stage Variables″. The Link Ordering tab is described in
″Specifying Link Order″.

General tab
In addition to the Description field, the General page also has an option which lets you control how
many rejected row warnings will appear in the job log when you run the job. Whenever a row is rejected
because it contains a null value, a warning is written to the job log. Potentially there could be a lot of
messages, so this option allows you to set limits. By default, up to 50 messages per partition are allowed,
but you can increase or decrease this, or set it to -1 to allow unlimited messages.

Surrogate Key tab

Use this tab to specify information about the key source if you generate surrogate keys. You can use
surrogate keys in complex lookup and update operations. The key source can be a flat file or a database
sequence.

You must create a derivation for the surrogate key column that uses the NextSurrogateKey function.

To generate surrogate keys by using a flat file:

1. In the Source type field, select Flat File.
2. In the Source name field, type the name and fully qualified path of the flat file, or click the arrow
button to browse for the file or to insert a job parameter. The file must be accessible from all nodes
that run the Transformer stage.
3. In the Initial value field, type a number or insert a job parameter. The first time the job runs, this
value is used to initialize the key state. Every subsequent time the job runs, the initial value is the
start value for generating surrogate keys. If the specified value is taken, the stage uses the next
available value.
4. In the New surrogate keys retrieved from state file area, specify the block size to use for surrogate
key retrieval:
v Select In blocks of to set the block size manually, and type a number in the key values field.
v Select System selected block size to have the system determine the optimal block size based on
your job configuration. System-selected block sizes usually result in larger key ranges, which
require less frequent state access and have better performance. However, the key sequence might
have temporary gaps until the next time the job runs.

To generate surrogate keys by using a database sequence:

1. In the Source type field, select DBSequence.
2. In the Source name field, type the name of the database sequence, or click the arrow button to
browse for the sequence or to insert a job parameter.
3. In the Database type field, select the type of the database.
4. In the User name field, type the user name for the database connection. This field is required for a
remote database. If you leave this field blank and you have a local database, the stage uses the
workstation login user name.
5. In the Password field, type the password for the database connection, This field is required for a
remote database. If you leave this field blank and you have a local database, the stage uses the
workstation login password.
6. In the Server name field, type the name of the server.
7. If the database type is DB2, complete some additional steps:

Chapter 11. Transformer stage 183

 a. In the Database name field, type the name of the database. If you leave this field blank, the stage
uses the name that is specified by the environment variable APT_DBNAME, or by the variable
DB2DBDFT if APT_DBNAME is not set.
b. In the Client instance name field, type the name of the DB2 client instance. This field is required
for a remote database.
c. In the Client alias DB name field, type the name of the client alias database on the remote server.
This field is needed only if the alias database name is not the same as the server database name.

Advanced tab
The Advanced tab is the same as the Advanced tab of the generic stage editor as described in ″Advanced
Tab″. This tab allows you to specify the following:
v Execution Mode. The stage can execute in parallel mode or sequential mode. In parallel mode the data
is processed by the available nodes as specified in the Configuration file, and by any node constraints
specified on the Advanced tab. In sequential mode the data is processed by the conductor node.
v Combinability mode. This is Auto by default, which allows WebSphere DataStage to combine the
operators that underlie parallel stages so that they run in the same process if it is sensible for this type
of stage.
v Preserve partitioning. This is set to Propagate by default, this sets or clears the partitioning in
accordance with what the previous stage has set. You can also select Set or Clear. If you select Set, the
stage will request that the next stage preserves the partitioning as is.
v Node pool and resource constraints. Select this option to constrain parallel execution to the node pool
or pools and/or resource pool or pools specified in the grid. The grid allows you to make choices from
drop down lists populated from the Configuration file.
v Node map constraint. Select this option to constrain parallel execution to the nodes in a defined node
map. You can define a node map by typing node numbers into the text box or by clicking the browse
button to open the Available Nodes dialog box and selecting nodes from there. You are effectively
defining a new node pool for this stage (in addition to any node pools defined in the Configuration
file).

Triggers tab
The Triggers tab allows you to choose routines to be executed at specific execution points as the
transformer stage runs in a job. The execution point is per-instance, i.e., if a job has two transformer stage
instances running in parallel, the routine will be called twice, once for each instance.

The available execution points are Before-stage and After-stage. At this release, the only available built-in
routine is SetCustomSummaryInfo. You can also define custom routines to be executed; to do this you
define a C function, make it available in UNIX shared library, and then define a Parallel routine which
calls it (see WebSphere DataStage Designer Client Guide for details on defining a Parallel Routine). Note that
the function should not return a value.

SetCustomSummaryInfo is used to collect reporting information. This information is included in any

XML reports generated, and can be retrieved using a number of methods:
v DSMakeJobReport API function (see WebSphere DataStage Parallel Job Advanced Developer Guide).
v The DSJob -Report command line command (seeWebSphere DataStage Parallel Job Advanced Developer
Guide).
v DSJobReport used as an after-job subroutine (see WebSphere DataStage Designer Client Guide).

Each item of information collected by SetCustomSummaryInfo is stored as a variable name, a description,

and a value. These appear as arguments in the Triggers tab grid (variable name in Argument 1,
description in Argument 2, value in Argument 3). You can supply values for them via the expression
editor. You can use job parameters and stage variables but you cannot access data that is available only
while the stage is running, such as columns.

184 Parallel Job Developer Guide

NLS Locale tab
This appears if you have NLS enabled on your system. It lets you view the current default collate
convention, and select a different one for this stage if required. You can also use a job parameter to
specify the locale, or browse for a file that defines custom collate rules. The collate convention defines the
order in which characters are collated. The transformer stage uses this when it is evaluating expressions.
For example, it would affect the evaluation of an expression such as ″if ustring1 > ustring2″. Select a
locale from the list, or click the arrow button next to the list to use a job parameter or browse for a collate
file.

Build tab
This tab allows you to override the compiler and linker flags that have been set for the job or project. The
flags you specify here will take effect for this stage and this stage alone. The flags available are platform
and compiler-dependent.

Input page
The Input page allows you to specify details about data coming into the Transformer stage. The
Transformer stage can have only one input link.

The General tab allows you to specify an optional description of the input link. The Partitioning tab
allows you to specify how incoming data is partitioned. This is the same as the Partitioning tab in the
generic stage editor described in ″Partitioning Tab″. The Advanced tab allows you to change the default
buffering settings for the input link.

Partitioning tab
The Partitioning tab allows you to specify details about how the incoming data is partitioned or collected
when input to the Transformer stage. It also allows you to specify that the data should be sorted on
input.

By default the Transformer stage will attempt to preserve partitioning of incoming data, or use its own
partitioning method according to what the previous stage in the job dictates.

If the Transformer stage is operating in sequential mode, it will first collect the data before writing it to
the file using the default collection method.

The Partitioning tab allows you to override this default behavior. The exact operation of this tab depends
on:
v Whether the stage is set to execute in parallel or sequential mode.
v Whether the preceding stage in the job is set to execute in parallel or sequential mode.

If the Transformer stage is set to execute in parallel, then you can set a partitioning method by selecting
from the Partitioning type drop-down list. This will override any current partitioning.

If the Transformer stage is set to execute in sequential mode, but the preceding stage is executing in
parallel, then you can set a collection method from the Collector type drop-down list. This will override
the default collection method.

The following partitioning methods are available:

v (Auto). WebSphere DataStage attempts to work out the best partitioning method depending on
execution modes of current and preceding stages and how many nodes are specified in the
Configuration file. This is the default method for the Transformer stage.
v Entire. Each file written to receives the entire data set.

Chapter 11. Transformer stage 185

v Hash. The records are hashed into partitions based on the value of a key column or columns selected
from the Available list.
v Modulus. The records are partitioned using a modulus function on the key column selected from the
Available list. This is commonly used to partition on tag fields.
v Random. The records are partitioned randomly, based on the output of a random number generator.
v Round Robin. The records are partitioned on a round robin basis as they enter the stage.
v Same. Preserves the partitioning already in place.
v DB2. Replicates the DB2 partitioning method of a specific DB2 table. Requires extra properties to be
set. Access these properties by clicking the properties button.
v Range. Divides a data set into approximately equal size partitions based on one or more partitioning
keys. Range partitioning is often a preprocessing step to performing a total sort on a data set. Requires
extra properties to be set. Access these properties by clicking the properties button.

The following Collection methods are available:

v (Auto). This is the default method for the Transformer stage. Normally, when you are using Auto
mode, WebSphere DataStage will eagerly read any row from any input partition as it becomes
available.
v Ordered. Reads all records from the first partition, then all records from the second partition, and so
on.
v Round Robin. Reads a record from the first input partition, then from the second partition, and so on.
After reaching the last partition, the operator starts over.
v Sort Merge. Reads records in an order based on one or more columns of the record. This requires you
to select a collecting key column from the Available list.

The Partitioning tab also allows you to specify that data arriving on the input link should be sorted. The
sort is always carried out within data partitions. If the stage is partitioning incoming data the sort occurs
after the partitioning. If the stage is collecting data, the sort occurs before the collection. The availability
of sorting depends on the partitioning method chosen.

Select the check boxes as follows:

v Perform Sort. Select this to specify that data coming in on the link should be sorted. Select the column
or columns to sort on from the Available list.
v Stable. Select this if you want to preserve previously sorted data sets. This is the default.
v Unique. Select this to specify that, if multiple records have identical sorting key values, only one
record is retained. If stable sort is also set, the first record is retained.

If NLS is enabled an additional button opens a dialog box allowing you to select a locale specifying the
collate convention for the sort.

You can also specify sort direction, case sensitivity, whether sorted as ASCII or EBCDIC, and whether null
columns will appear first or last for each column. Where you are using a keyed partitioning method, you
can also specify whether the column is used as a key for sorting, for partitioning, or for both. Select the
column in the Selected list and right-click to invoke the shortcut menu.

Output page
The Output Page has a General tab which allows you to enter an optional description for each of the
output links on the Transformer stage. It also allows you to switch Runtime column propagation on for
this link, in which case data will automatically be propagated from the input link without you having to
specify meta data for this output link (see ″Runtime Column Propagation″ ). The Advanced tab allows
you to change the default buffering settings for the output links.

186 Parallel Job Developer Guide

Chapter 12. BASIC Transformer stages
The BASIC Transformer stage is a processing stage. It appears under the processing category in the tool
palette in the Transformer shortcut container.

The BASIC Transformer stage is similar in appearance and function to the Transformer stage described in
Chapter 11, “Transformer stage,” on page 167. It gives access to BASIC transforms and functions (BASIC
is the language supported by the WebSphere DataStage server engine and available in server jobs). For a
description of the BASIC functions available see WebSphere DataStage Server Job Developer Guide.

You can only use BASIC transformer stages on SMP systems (not on MPP or cluster systems).

Note: If you encounter a problem when running a job containing a BASIC transformer, you could try
increasing the value of the DSIPC_OPEN_TIMEOUT environment variable in the Parallel 
Operator specific category of the environment variable dialog box in the DataStage Administrator
(see WebSphere DataStage Administrator Client Guide).

BASIC Transformer stages can have a single input and any number of outputs.

Must do’s
This section specifies the minimum steps to take to get a BASIC Transformer stage functioning.
WebSphere DataStage provides a versatile user interface, and there are many shortcuts to achieving a
particular end, this section describes the basic method, you will learn where the shortcuts are when you
get familiar with the product.
v In the left pane:
– Ensure that you have column metadata defined.
v In the right pane:
– Ensure that you have column metadata defined for each of the output links. The easiest way to do
this is to drag columns across from the input link.
– Define the derivation for each of your output columns. You can leave this as a straight mapping
from an input column, or explicitly define an expression to transform the data before it is output.
– Optionally specify a constraint for each output link. This is an expression which input rows must
satisfy before they are output on a link. Rows that are not output on any of the links can be output
on the otherwise link.
– Optionally specify one or more stage variables. This provides a method of defining expressions
which can be reused in your output columns derivations (stage variables are only visible within the
stage).

BASIC Transformer editor components

The BASIC Transformer Editor has the following components.

Toolbar
The Transformer toolbar contains the following buttons (from left to right):
v Stage properties
v Constraints
v Show all

© Copyright IBM Corp. 2006 187

v Show/hide stage variables
v Cut
v Copy
v Paste
v Find/replace
v Load column definition
v Save column definition
v Column auto-match
v Input link execution order
v Output link execution order

Link area
The top area displays links to and from the BASIC Transformer stage, showing their columns and the
relationships between them.

The link area is where all column definitions and stage variables are defined.

The link area is divided into two panes; you can drag the splitter bar between them to resize the panes
relative to one another. There is also a horizontal scroll bar, allowing you to scroll the view left or right.

The left pane shows the input link, the right pane shows output links. Output columns that have no
derivation defined are shown in red.

Within the Transformer Editor, a single link may be selected at any one time. When selected, the link’s
title bar is highlighted, and arrowheads indicate any selected columns.

Metadata area
The bottom area shows the column metadata for input and output links. Again this area is divided into
two panes: the left showing input link meta data and the right showing output link meta data.

The meta data for each link is shown in a grid contained within a tabbed page. Click the tab to bring the
required link to the front. That link is also selected in the link area.

If you select a link in the link area, its metadata tab is brought to the front automatically.

You can edit the grids to change the column meta data on any of the links. You can also add and delete
metadata.

Shortcut menus
The BASIC Transformer Editor shortcut menus are displayed by right-clicking the links in the links area.

There are slightly different menus, depending on whether you right-click an input link, an output link, or
a stage variable. The input link menu offers you operations on input columns, the output link menu
offers you operations on output columns and their derivations, and the stage variable menu offers you
operations on stage variables.

The shortcut menu enables you to:

v Open the Stage Properties dialog box in order to specify stage or link properties.
v Open the Constraints dialog box to specify a constraint (only available for output links).

188 Parallel Job Developer Guide

v Open the Column Auto Match dialog box.
v Display the Find/Replace dialog box.
v Display the Select dialog box.
v Edit, validate, or clear a derivation or stage variable.
v Edit several derivations in one operation.
v Append a new column or stage variable to the selected link.
v Select all columns on a link.
v Insert or delete columns or stage variables.
v Cut, copy, and paste a column or a key expression or a derivation or stage variable.

Ifyou display the menu from the links area background, you can:
v Open the Stage Properties dialog box in order to specify stage or link properties.
v Open the Constraints dialog box in order to specify a constraint for the selected output link.
v Open the Link Execution Order dialog box in order to specify the order in which links should be
processed.
v Toggle between viewing link relations for all links, or for the selected link only.
v Toggle between displaying stage variables and hiding them.

Right-clicking in the meta data area of the Transformer Editor opens the standard grid editing shortcut
menus.

BASIC Transformer stage basic concepts

When you first edit a Transformer stage, it is likely that you will have already defined what data is input
to the stage on the input links. You will use the Transformer Editor to define the data that will be output
by the stage and how it will be transformed. (You can define input data using the Transformer Editor if
required.)

This section explains some of the basic concepts of using a Transformer stage.

Input link
The input data source is joined to the BASIC Transformer stage via the input link.

Output links
You can have any number of output links from your Transformer stage.

You may want to pass some data straight through the BASIC Transformer stage unaltered, but it’s likely
that you’ll want to transform data from some input columns before outputting it from the BASIC
Transformer stage.

You can specify such an operation by entering an expression or by selecting a transform to apply to the
data. WebSphere DataStage has many built-in transforms, or you can define your own custom transforms
that are stored in the Repository and can be reused as required.

The source of an output link column is defined in that column’s Derivation cell within the Transformer
Editor. You can use the Expression Editor to enter expressions or transforms in this cell. You can also
simply drag an input column to an output column’s Derivation cell, to pass the data straight through the
BASIC Transformer stage.

In addition to specifying derivation details for individual output columns, you can also specify
constraints that operate on entire output links. A constraint is a BASIC expression that specifies criteria

Chapter 12. BASIC Transformer stages 189

that data must meet before it can be passed to the output link. You can also specify a reject link, which is
an output link that carries all the data not output on other links, that is, columns that have not met the
criteria.

Each output link is processed in turn. If the constraint expression evaluates to TRUE for an input row, the
data row is output on that link. Conversely, if a constraint expression evaluates to FALSE for an input
row, the data row is not output on that link.

Constraint expressions on different links are independent. If you have more than one output link, an
input row may result in a data row being output from some, none, or all of the output links.

For example, if you consider the data that comes from a paint shop, it could include information about
any number of different colors. If you want to separate the colors into different files, you would set up
different constraints. You could output the information about green and blue paint on LinkA, red and
yellow paint on LinkB, and black paint on LinkC.

When an input row contains information about yellow paint, the LinkA constraint expression evaluates to
FALSE and the row is not output on LinkA. However, the input data does satisfy the constraint criterion
for LinkB and the rows are output on LinkB.

If the input data contains information about white paint, this does not satisfy any constraint and the data
row is not output on Links A, B or C, but will be output on the reject link. The reject link is used to route
data to a table or file that is a ″catch-all″ for rows that are not output on any other link. The table or file
containing these rejects is represented by another stage in the job design.

Before-stage and after-stage routines

You can specify routines to be executed before or after the stage has processed the data. For example, you
might use a before-stage routine to prepare the data before processing starts. You might use an after-stage
routine to send an electronic message when the stage has finished.

Editing BASIC transformer stages

The Transformer Editor enables you to perform the following operations on a BASIC Transformer stage:
v Create new columns on a link
v Delete columns from within a link
v Move columns within a link
v Edit column meta data
v Define output column derivations
v Specify before- and after-stage subroutines
v Define link constraints and handle rejects
v Specify the order in which links are processed
v Define local stage variables

Using drag and drop

Many of the BASIC Transformer stage edits can be made simpler by using the Transformer Editor’s drag
and drop functionality. You can drag columns from any link to any other link. Common uses are:
v Copying input columns to output links
v Moving columns within a link
v Copying derivations in output links

190 Parallel Job Developer Guide

To use drag and drop:
1. Click the source cell to select it.
2. Click the selected cell again and, without releasing the mouse button, drag the mouse pointer to the
desired location within the target link. An insert point appears on the target link to indicate where the
new cell will go.
3. Release the mouse button to drop the selected cell.

You can drag and drop multiple columns or derivations. Use the standard Explorer keys when selecting
the source column cells, then proceed as for a single cell.

You can drag and drop the full column set by dragging the link title.

You can add a column to the end of an existing derivation by holding down the Ctrl key as you drag the
column.

Find and replace facilities

If you are working on a complex job where several links, each containing several columns, go in and out
of the BASIC Transformer stage, you can use the find/replace column facility to help locate a particular
column or expression and change it.

The find/replace facility enables you to:

v Find and replace a column name
v Find and replace expression text
v Find the next empty expression
v Find the next expression that contains an error

To use the find/replace facilities, do one of the following:

v Click the find/replace button on the toolbar
v Choose find/replace from the link shortcut menu
v Type Ctrl-F

The Find and Replace dialog box appears. It has three tabs:
v Expression Text. Allows you to locate the occurrence of a particular string within an expression, and
replace it if required. You can search up or down, and choose to match case, match whole words, or
neither. You can also choose to replace all occurrences of the string within an expression.
v Columns Names. Allows you to find a particular column and rename it if required. You can search up
or down, and choose to match case, match the whole word, or neither.
v Expression Types. Allows you to find the next empty expression or the next expression that contains
an error. You can also press Ctrl-M to find the next empty expression or Ctrl-N to find the next
erroneous expression.

Note: The find and replace results are shown in the color specified in Tools → Options.

Press F3 to repeat the last search you made without opening the Find and Replace dialog box.

Select facilities
If you are working on a complex job where several links, each containing several columns, go in and out
of the Transformer stage, you can use the select column facility to select multiple columns. This facility is
also available in the Mapping tabs of certain Parallel job stages.

Chapter 12. BASIC Transformer stages 191

The select facility enables you to:
v Select all columns/stage variables whose expressions contains text that matches the text specified.
v Select all column/stage variables whose name contains the text specified (and, optionally, matches a
specified type).
v Select all columns/stage variable with a certain data type.
v Select all columns with missing or invalid expressions.

To use the select facilities, choose Select from the link shortcut menu. The Select dialog box appears. It
has three tabs:
v Expression Text. This Expression Text tab allows you to select all columns/stage variables whose
expressions contain text that matches the text specified. The text specified is a simple text match, taking
into account the Match case setting.
v Column Names. The Column Names tab allows you to select all column/stage variables whose Name
contains the text specified. There is an additional Data Type drop down list, that will limit the columns
selected to those with that data type. You can use the Data Type drop down list on its own to select all
columns of a certain data type. For example, all string columns can be selected by leaving the text field
blank, and selecting String as the data type. The data types in the list are generic data types, where
each of the column SQL data types belong to one of these generic types.
v Expression Types. The Expression Types tab allows you to select all columns with either empty
expressions or invalid expressions.

Creating and deleting columns

You can create columns on links to the BASIC Transformer stage using any of the following methods:
v Select the link, then click the load column definition button in the toolbar to open the standard load
columns dialog box.
v Use drag and drop or copy and paste functionality to create a new column by copying from an
existing column on another link.
v Use the shortcut menus to create a new column definition.
v Edit the grids in the link’s meta data tab to insert a new column.

When copying columns, a new column is created with the same meta data as the column it was copied
from.

To delete a column from within the Transformer Editor, select the column you want to delete and click
the cut button or choose Delete Column from the shortcut menu.

Moving columns within a link

You can move columns within a link using either drag and drop or cut and paste. Select the required
column, then drag it to its new location, or cut it and paste it in its new location.

Editing column meta data

You can edit column meta data from within the grid in the bottom of the Transformer Editor. Select the
tab for the link meta data that you want to edit, then use the standard WebSphere DataStage edit grid
controls.

The meta data shown does not include column derivations since these are edited in the links area.

192 Parallel Job Developer Guide

Defining output column derivations
You can define the derivation of output columns from within the Transformer Editor in five ways:
v If you require a new output column to be directly derived from an input column, with no
transformations performed, then you can use drag and drop or copy and paste to copy an input
column to an output link. The output columns will have the same names as the input columns from
which they were derived.
v If the output column already exists, you can drag or copy an input column to the output column’s
Derivation field. This specifies that the column is directly derived from an input column, with no
transformations performed.
v You can use the column auto-match facility to automatically set that output columns are derived from
their matching input columns.
v You may need one output link column derivation to be the same as another output link column
derivation. In this case you can use drag and drop or copy and paste to copy the derivation cell from
one column to another.
v In many cases you will need to transform data before deriving an output column from it. For these
purposes you can use the Expression Editor. To display the Expression Editor, double-click on the
required output link column Derivation cell. (You can also invoke the Expression Editor using the
shortcut menu or the shortcut keys.)

If a derivation is displayed in red (or the color defined in Tools → Options), it means that the Transformer
Editor considers it incorrect. (In some cases this may simply mean that the derivation does not meet the
strict usage pattern rules of the WebSphere DataStage engine, but will actually function correctly.)

Once an output link column has a derivation defined that contains any input link columns, then a
relationship line is drawn between the input column and the output column, as shown in the following
example. This is a simple example; there can be multiple relationship lines either in or out of columns.
You can choose whether to view the relationships for all links, or just the relationships for the selected
links, using the button in the toolbar.

Column auto-match facility

This time-saving feature allows you to automatically set columns on an output link to be derived from
matching columns on an input link. Using this feature you can fill in all the output link derivations to
route data from corresponding input columns, then go back and edit individual output link columns
where you want a different derivation.

To use this facility:

1. Do one of the following:
v Click the Auto-match button in the Transformer Editor toolbar.
v Choose Auto-match from the input link header or output link header shortcut menu.
TheColumn Auto-Match dialog box appears.
2. Choose the input link and output link that you want to match columns for from the drop down lists.
3. Click Location match or Name match from the Match type area.
If you choose Location match, this will set output column derivations to the input link columns in the
equivalent positions. It starts with the first input link column going to the first output link column,
and works its way down until there are no more input columns left.
4. Click OK to proceed with the auto-matching.

Note: Auto-matching does not take into account any data type incompatibility between matched
columns; the derivations are set regardless.

Chapter 12. BASIC Transformer stages 193

Editing multiple derivations
You can make edits across several output column or stage variable derivations by choosing Derivation
Substitution... from the shortcut menu. This opens the Expression Substitution dialog box.

The Expression Substitution dialog box allows you to make the same change to the expressions of all the
currently selected columns within a link. For example, if you wanted to add a call to the trim() function
around all the string output column expressions in a link, you could do this in two steps. First, use the
Select dialog to select all the string output columns. Then use the Expression Substitution dialog to apply
a trim() call around each of the existing expression values in those selected columns.

You are offered a choice between Whole expression substitution and Part of expression substitution.

Whole expression
With this option the whole existing expression for each column is replaced by the replacement value
specified. This replacement value can be a completely new value, but will usually be a value based on
the original expression value. When specifying the replacement value, the existing value of the column’s
expression can be included in this new value by including ″$1″. This can be included any number of
times.

For example, when adding a trim() call around each expression of the currently selected column set,
having selected the required columns, you would:
1. Select the Whole expression option.
2. Enter a replacement value of:
trim($1)
3. Click OK

Where a column’s original expression was:

DSLink3.col1

This will be replaced by:

trim(DSLink3.col1)

This is applied to the expressions in each of the selected columns.

If you need to include the actual text $1 in your expression, enter it as ″$$1″.

Part of expression
With this option, only part of each selected expression is replaced rather than the whole expression. The
part of the expression to be replaced is specified by a Regular Expression match.

It is possible that more that one part of an expression string could match the Regular Expression
specified. If Replace all occurrences is checked, then each occurrence of a match will be updated with the
replacement value specified. If it is not checked, then just the first occurrence is replaced.

When replacing part of an expression, the replacement value specified can include that part of the
original expression being replaced. In order to do this, the Regular Expression specified must have round
brackets around its value. ″$1″ in the replacement value will then represent that matched text. If the
Regular Expression is not surrounded by round brackets, then ″$1″ will simply be the text ″$1″.

194 Parallel Job Developer Guide

For complex Regular Expression usage, subsets of the Regular Expression text can be included in round
brackets rather than the whole text. In this case, the entire matched part of the original expression is still
replaced, but ″$1″, ″$2″ etc can be used to refer to each matched bracketed part of the Regular Expression
specified.

The following is an example of the Part of expression replacement.

Suppose a selected set of columns have derivations that use input columns from `DSLink3’. For example,
two of these derivations could be:
DSLink3.OrderCount + 1
If (DSLink3.Total > 0) Then DSLink3.Total Else -1

You may want to protect the usage of these input columns from null values, and use a zero value instead
of the null. To do this:
1. Select the columns you want to substitute expressions for.
2. Select the Part of expression option.
3. Specify a Regular Expression value of:
(DSLink3\.[a-z,A-Z,0-9]*)
4. Specify a replacement value of
NullToZero($1)
5. Click OK, to apply this to all the selected column derivations.

From the examples above:

DSLink3.OrderCount + 1

would become
NullToZero(DSLink3.OrderCount) + 1

and
If (DSLink3.Total > 0) Then DSLink3.Total Else -1

would become:
If (NullToZero(DSLink3.Total) > 0) Then DSLink3.Total Else -1

If the Replace all occurrences option is selected, the second expression will become:
If (NullToZero(DSLink3.Total) > 0)
Then NullToZero(DSLink3.Total)
Else -1

The replacement value can be any form of expression string. For example in the case above, the
replacement value could have been:
(If (StageVar1 > 50000) Then $1 Else ($1 + 100))

In the first case above, the expression

DSLink3.OrderCount + 1

would become:
(If (StageVar1 > 50000) Then DSLink3.OrderCount
Else (DSLink3.OrderCount + 100)) + 1

Specifying before-stage and after-stage subroutines

You can specify BASIC routines to be executed before or after the stage has processed the data.

Chapter 12. BASIC Transformer stages 195

To specify a routine, click the stage properties button in the toolbar to open the Stage Properties dialog
box.

The General tab contains the following fields:

v Before-stage subroutine and Input Value. Contain the name (and value) of a subroutine that is
executed before the stage starts to process any data.
v After-stage subroutine and Input Value. Contain the name (and value) of a subroutine that is executed
after the stage has processed the data.

Choose a routine from the drop-down list box. This list box contains all the built routines defined as a
Before/After Subroutine under the Routines branch in the Repository. Enter an appropriate value for the
routine’s input argument in the Input Value field.

If you choose a routine that is defined in the Repository, but which was edited but not compiled, a
warning message reminds you to compile the routine when you close the Transformer stage dialog box.

If you installed or imported a job, the Before-stage subroutine or After-stage subroutine field may
reference a routine that does not exist on your system. In this case, a warning message appears when you
close the dialog box. You must install or import the ″missing″ routine or choose an alternative one to use.

A return code of 0 from the routine indicates success, any other code indicates failure and causes a fatal
error when the job is run.

Defining constraints and handling reject links

You can define limits for output data by specifying a constraint. Constraints are expressions and you can
specify a constraint for each output link from a Transformer stage. You can also specify that a particular
link is to act as a reject link. Reject links output rows that have not been written on any other output
links from the Transformer stage because they have failed or constraints or because a write failure has
occurred.

To define a constraint or specify an otherwise link, do one of the following:

v Select an output link and click the constraints button.
v Double-click the output link’s constraint entry field.
v Choose Constraints from the background or header shortcut menus.

A dialog box appears which allows you either to define constraints for any of the Transformer output
links or to define a link as an reject link.

Define a constraint by entering a expression in the Constraint field for that link. Once you have done
this, any constraints will appear below the link’s title bar in the Transformer Editor. This constraint
expression will then be checked against the row data at runtime. If the data does not satisfy the
constraint, the row will not be written to that link. It is also possible to define a link which can be used
to catch these rows which have been rejected from a previous link.

A reject link can be defined by choosing Yes in the Reject Row field and setting the Constraint field as
follows:
v To catch rows which are rejected from a specific output link, set the Constraint field to
linkname.REJECTED. This will be set whenever a row is rejected on the linkname link, whether because
the row fails to match a constraint on that output link, or because a write operation on the target fails
for that row. Note that such an otherwise link should occur after the output link from which it is
defined to catch rejects.
v To catch rows which caused a write failures on an output link, set the Constraint field to
linkname.REJECTEDCODE. The value of linkname.REJECTEDCODE will be non-zero if the row was

196 Parallel Job Developer Guide

 rejected due to a write failure or 0 (DSE.NOERROR) if the row was rejected due to the link constraint
not being met. When editing the Constraint field, you can set return values for
linkname.REJECTEDCODE by selecting from the Expression Editor Link Variables > Constants... menu
options. These give a range of errors, but note that most write errors return DSE.WRITERROR.
In order to set a reject constraint which differentiates between a write failure and a constraint not being
met, a combination of the linkname.REJECTEDCODE and linkname.REJECTED flags can be used. For
example:
– To catch rows which have failed to be written to an output link, set the Constraint field to
linkname.REJECTEDCODE
– To catch rows which do not meet a constraint on an output link, set the Constraint field to
linkname.REJECTEDCODE = DSE.NOERROR AND linkname.REJECTED
– To catch rows which have been rejected due a a constraint or write error, set the Constraint field to
linkname.REJECTED
v As a ″catch all″, the Constraint field can be left blank. This indicates that this otherwise link will catch
all rows which have not been successfully written to any of the output links processed up to this point.
Therefore, the otherwise link should be the last link in the defined processing order.
v Any other Constraint can be defined. This will result in the number of rows written to that link (i.e.
rows which satisfy the constraint) to be recorded in the job log as ″rejected rows″.

Note: Due to the nature of the ″catch all″ case above, you should only use one reject link whose
Constraint field is blank. To use multiple reject links, you should define them to use the
linkname.REJECTED flag detailed in the first case above.

Specifying link order

You can specify the order in which output links process a row. The initial order of the links is the order
in which they are added to the stage. To reorder the links:
1. Do one of the following:
v Click the output link execution order button on the Transformer Editor toolbar.
v Choose output link reorder from the background shortcut menu.
v Click the stage properties button in the Transformer toolbar or choose stage properties from the
background shortcut menu and click on the stage page Link Ordering tab.
The Link Ordering tab appears:
2. Use the arrow buttons to rearrange the list of links in the execution order required.
3. When you are happy with the order, click OK.

Note: Although the link ordering facilities mean that you can use a previous output column to derive
a subsequent output column, we do not encourage this practice, and you will receive a warning
if you do so.

Defining local stage variables

You can declare and use your own variables within a BASIC Transformer stage. Such variables are
accessible only from the BASIC Transformer stage in which they are declared. They can be used as
follows:
v They can be assigned values by expressions.
v They can be used in expressions which define an output column derivation.
v Expressions evaluating a variable can include other variables or the variable being evaluated itself.

Chapter 12. BASIC Transformer stages 197

Any stage variables you declare are shown in a table in the right pane of the links area. The table looks
similar to an output link. You can display or hide the table by clicking the Stage Variable button in the
Transformer toolbar or choosing Stage Variable from the background shortcut menu.

Note: Stage variables are not shown in the output link meta data area at the bottom of the right pane.

The table lists the stage variables together with the expressions used to derive their values. Link lines join
the stage variables with input columns used in the expressions. Links from the right side of the table link
the variables to the output columns that use them.

To declare a stage variable:

1. Do one of the following:
v Click the stage properties button in the Transformer toolbar.
v Choose stage properties from the background shortcut menu.
The Transformer Stage Properties dialog box appears.
2. Click the Variables tab on the General page. The Variables tab contains a grid showing currently
declared variables, their initial values, and an optional description. Use the standard grid controls to
add new variables. Variable names must begin with an alphabetic character (a-z, A-Z) and can only
contain alphanumeric characters (a-z, A-Z, 0-9). Ensure that the variable does not use the name of any
BASIC keywords.

Variables entered in the Stage Properties dialog box appear in the Stage Variable table in the links pane.

You perform most of the same operations on a stage variable as you can on an output column (see
Defining Output Column Derivations). A shortcut menu offers the same commands. You cannot, however,
paste a stage variable as a new column, or a column as a new stage variable.

The WebSphere DataStage expression editor

The WebSphere DataStage Expression Editor helps you to enter correct expressions when you edit BASIC
Transformer stages. The Expression Editor can:
v Facilitate the entry of expression elements
v Complete the names of frequently used variables
v Validate variable names and the complete expression

The Expression Editor can be opened from:

v Output link Derivation cells
v Stage variable Derivation cells
v Constraint dialog box
v Transform dialog box in the Designer

Expression format
The format of an expression is as follows:
KEY:

something_like_this is a token
something_in_italics is a terminal, i.e., doesn’t break down any
further
| is a choice between tokens
[ is an optional part of the construction
"XXX" is a literal token (i.e., use XXX not
including the quotes)
=================================================

198 Parallel Job Developer Guide

expression ::= function_call |
variable_name |
other_name |
constant |
unary_expression |
binary_expression |
if_then_else_expression |
substring_expression |
"(" expression ")"

function_call ::= function_name "(" [argument_list] ")"

argument_list ::= expression | expression "," argument_list
function_name ::= name of a built-in function |
name of a user-defined_function
variable_name ::= job_parameter name |
stage_variable_name |
link_variable name
other_name ::= name of a built-in macro, system variable, etc.
constant ::= numeric_constant | string_constant
numeric_constant ::= ["+" | "-"] digits ["." [digits]] ["E" | "e" ["+" | "-"] digits]
string_constant ::= "’" [characters] "’" |
""" [characters] """ |
"\" [characters] "\"
unary_expression ::= unary_operator expression
unary_operator ::= "+" | "-"
binary_expression ::= expression binary_operator expression
binary_operator ::= arithmetic_operator |
concatenation_operator |
matches_operator |
relational_operator |
logical_operator
arithmetic_operator ::= "+" | "-" | "*" | "/" | "^"
concatenation_operator ::= ":"
matches_operator ::= "MATCHES"
relational_operator ::= " =" |"EQ" |
"<>" | "#" | "NE" |
">" | "GT" |
">=" | "=>" | "GE" |
"<" | "LT" |
"<=" | "=<" | "LE"
logical_operator ::= "AND" | "OR"
if_then_else_expression ::= "IF" expression "THEN" expression "ELSE" expression
substring_expression ::= expression "[" [expression ["," expression] "]"
field_expression ::= expression "[" expression ","
expression ","
expression "]"
/* That is, always 3 args

Note: keywords like ″AND″ or ″IF″ or ″EQ″ may be in any case

Entering expressions
Whenever the insertion point is in an expression box, you can use the Expression Editor to suggest the
next element in your expression. Do this by right-clicking the box, or by clicking the Suggest button to
the right of the box. This opens the Suggest Operand or Suggest Operator menu. Which menu appears
depends on context, i.e., whether you should be entering an operand or an operator as the next
expression element.

You will be offered a different selection on the Suggest Operand menu depending on whether you are
defining key expressions, derivations and constraints, or a custom transform. The Suggest Operator
menu is always the same.

Chapter 12. BASIC Transformer stages 199

Completing variable names
The Expression Editor stores variable names. When you enter a variable name you have used before, you
can type the first few characters, then press F5. The Expression Editor completes the variable name for
you.

If you enter the name of an input link followed by a period, for example, DailySales., the Expression
Editor displays a list of the column names of that link. If you continue typing, the list selection changes
to match what you type. You can also select a column name using the mouse. Enter a selected column
name into the expression by pressing Tab or Enter. Press Esc to dismiss the list without selecting a
column name.

Validating the expression

When you have entered an expression in the Transformer Editor, press Enter to validate it. The
Expression Editor checks that the syntax is correct and that any variable names used are acceptable to the
compiler. When using the Expression Editor to define a custom transform, click OK to validate the
expression.

If there is an error, a message appears and the element causing the error is highlighted in the expression
box. You can either correct the expression or close the Transformer Editor or Transform dialog box.

Within the Transformer Editor, the invalid expressions are shown in red. (In some cases this may simply
mean that the expression does not meet the strict usage pattern rules of the WebSphere DataStage engine,
but will actually function correctly.)

Exiting the expression editor

You can exit the Expression Editor in the following ways:
v Press Esc (which discards changes).
v Press Return (which accepts changes).
v Click outside the Expression Editor box (which accepts changes).

Configuring the expression editor

You can resize the Expression Editor window by dragging. The next time you open the expression editor
in the same context (for example, editing output columns) on the same client, it will have the same size.

The Expression Editor is configured by editing the Designer options. This allows you to specify how
`helpful’ the expression editor is. For more information, see WebSphere DataStage Designer Client Guide.

BASIC Transformer stage properties

The Transformer stage has a Properties dialog box which allows you to specify details about how the
stage operates.

The Transform Stage dialog box has three pages:

v Stage page. This is used to specify general information about the stage.
v Input page. This is where you specify details about the data input to the Transformer stage.
v Output page. This is where you specify details about the output links from the Transformer stage.

Stage page
The Stage page has four tabs:
200 Parallel Job Developer Guide
v General. Allows you to enter an optional description of the stage and specify a before-stage and/or
after-stage subroutine.
v Variables. Allows you to set up stage variables for use in the stage.
v Link Ordering. Allows you to specify the order in which the output links will be processed.
v Advanced. Allows you to specify how the stage executes.

The General tab is described in ″Before-Stage and After-Stage Routines″ . The Variables tab is described in
″Defining Local Stage Variables″. The Link Ordering tab is described in ″Specifying Link Order″.

Advanced tab
The Advanced tab is the same as the Advanced tab of the generic stage editor as described in ″Advanced
Tab″. This tab allows you to specify the following:
v Execution Mode. The stage can execute in parallel mode or sequential mode. In parallel mode the data
is processed by the available nodes as specified in the Configuration file, and by any node constraints
specified on the Advanced tab. In sequential mode the data is processed by the conductor node.
v Combinability mode. This is Auto by default, which allows WebSphere DataStage to combine the
operators that underlie parallel stages so that they run in the same process if it is sensible for this type
of stage.
v Preserve partitioning. This is set to Propagate by default, this sets or clears the partitioning in
accordance with what the previous stage has set. You can also select Set or Clear. If you select Set, the
stage will request that the next stage preserves the partitioning as is.
v Node pool and resource constraints. Select this option to constrain parallel execution to the node pool
or pools and/or resource pool or pools specified in the grid. The grid allows you to make choices from
drop down lists populated from the Configuration file.
v Node map constraint. Select this option to constrain parallel execution to the nodes in a defined node
map. You can define a node map by typing node numbers into the text box or by clicking the browse
button to open the Available Nodes dialog box and selecting nodes from there. You are effectively
defining a new node pool for this stage (in addition to any node pools defined in the Configuration
file).

Input page
The Input page allows you to specify details about data coming into the Transformer stage. The
Transformer stage can have only one input link.

The General tab allows you to specify an optional description of the input link.

The Partitioning tab allows you to specify how incoming data is partitioned. This is the same as the
Partitioning tab in the generic stage editor described in ″Partitioning Tab″.

Partitioning tab
The Partitioning tab allows you to specify details about how the incoming data is partitioned or collected
when input to the BASIC Transformer stage. It also allows you to specify that the data should be sorted
on input.

By default the BASIC Transformer stage will attempt to preserve partitioning of incoming data, or use its
own partitioning method according to what the previous stage in the job dictates.

If the BASIC Transformer stage is operating in sequential mode, it will first collect the data before writing
it to the file using the default collection method.

The Partitioning tab allows you to override this default behavior. The exact operation of this tab depends
on:

Chapter 12. BASIC Transformer stages 201

v Whether the stage is set to execute in parallel or sequential mode.
v Whether the preceding stage in the job is set to execute in parallel or sequential mode.

If the BASIC Transformer stage is set to execute in parallel, then you can set a partitioning method by
selecting from the Partitioning type drop-down list. This will override any current partitioning.

If the BASIC Transformer stage is set to execute in sequential mode, but the preceding stage is executing
in parallel, then you can set a collection method from the Collector type drop-down list. This will
override the default collection method.

The following partitioning methods are available:

v (Auto). WebSphere DataStage attempts to work out the best partitioning method depending on
execution modes of current and preceding stages and how many nodes are specified in the
Configuration file. This is the default method for the Transformer stage.
v Entire. Each file written to receives the entire data set.
v Hash. The records are hashed into partitions based on the value of a key column or columns selected
from the Available list.
v Modulus. The records are partitioned using a modulus function on the key column selected from the
Available list. This is commonly used to partition on tag fields.
v Random. The records are partitioned randomly, based on the output of a random number generator.
v Round Robin. The records are partitioned on a round robin basis as they enter the stage.
v Same. Preserves the partitioning already in place.
v DB2. Replicates the DB2 partitioning method of a specific DB2 table. Requires extra properties to be
set. Access these properties by clicking the properties button.
v Range. Divides a data set into approximately equal size partitions based on one or more partitioning
keys. Range partitioning is often a preprocessing step to performing a total sort on a data set. Requires
extra properties to be set. Access these properties by clicking the properties button.

The following Collection methods are available:

v (Auto). This is the default method for the Transformer stage. Normally, when you are using Auto
mode, WebSphere DataStage will eagerly read any row from any input partition as it becomes
available.
v Ordered. Reads all records from the first partition, then all records from the second partition, and so
on.
v Round Robin. Reads a record from the first input partition, then from the second partition, and so on.
After reaching the last partition, the operator starts over.
v Sort Merge. Reads records in an order based on one or more columns of the record. This requires you
to select a collecting key column from the Available list.

The Partitioning tab also allows you to specify that data arriving on the input link should be sorted. The
sort is always carried out within data partitions. If the stage is partitioning incoming data the sort occurs
after the partitioning. If the stage is collecting data, the sort occurs before the collection. The availability
of sorting depends on the partitioning method chosen.

Select the check boxes as follows:

v Perform Sort. Select this to specify that data coming in on the link should be sorted. Select the column
or columns to sort on from the Available list.
v Stable. Select this if you want to preserve previously sorted data sets. This is the default.
v Unique. Select this to specify that, if multiple records have identical sorting key values, only one
record is retained. If stable sort is also set, the first record is retained.

202 Parallel Job Developer Guide

If NLS is enabled an additional button opens a dialog box allowing you to select a locale specifying the
collate convention for the sort.

You can also specify sort direction, case sensitivity, whether sorted as ASCII or EBCDIC, and whether null
columns will appear first or last for each column. Where you are using a keyed partitioning method, you
can also specify whether the column is used as a key for sorting, for partitioning, or for both. Select the
column in the Selected list and right-click to invoke the shortcut menu.

Output page
The Output Page has a General tab which allows you to enter an optional description for each of the
output links on the BASIC Transformer stage. The Advanced tab allows you to change the default
buffering settings for the output links.

Chapter 12. BASIC Transformer stages 203

204 Parallel Job Developer Guide
Chapter 13. Aggregator stage
The Aggregator stage is a processing stage. It classifies data rows from a single input link into groups
and computes totals or other aggregate functions for each group. The summed totals for each group are
output from the stage via an output link.

When you edit an Aggregator stage, the Aggregator stage editor appears. This is based on the generic
stage editor described in Chapter 3, “Stage editors,” on page 37, ″Stage Editors.″

The stage editor has three pages:

v Stage Page. This is always present and is used to specify general information about the stage.
v Input Page. This is where you specify details about the data being grouped and/or aggregated.
v Output Page. This is where you specify details about the groups being output from the stage.

The aggregator stage gives you access to grouping and summary operations. One of the easiest ways to
expose patterns in a collection of records is to group records with similar characteristics, then compute
statistics on all records in the group. You can then use these statistics to compare properties of the
different groups. For example, records containing cash register transactions might be grouped by the day
of the week to see which day had the largest number of transactions, the largest amount of revenue, etc.

Records can be grouped by one or more characteristics, where record characteristics correspond to
column values. In other words, a group is a set of records with the same value for one or more columns.
For example, transaction records might be grouped by both day of the week and by month. These
groupings might show that the busiest day of the week varies by season.

In addition to revealing patterns in your data, grouping can also reduce the volume of data by
summarizing the records in each group, making it easier to manage. If you group a large volume of data
on the basis of one or more characteristics of the data, the resulting data set is generally much smaller
than the original and is therefore easier to analyze using standard workstation or PC-based tools.

At a practical level, you should be aware that, in a parallel environment, the way that you partition data
before grouping and summarizing it can affect the results. For example, if you partitioned using the
round robin method, records with identical values in the column you are grouping on would end up in
different partitions. If you then performed a sum operation within these partitions you would not be
operating on all the relevant columns. In such circumstances you may want to key partition the data on
one or more of the grouping keys to ensure that your groups are entire.

© Copyright IBM Corp. 2006 205

It is important that you bear these facts in mind and take any steps you need to prepare your data set
before presenting it to the Aggregator stage. In practice this could mean you use Sort stages or additional
Aggregate stages in the job.

Example
The example data is from a freight carrier who charges customers based on distance, equipment, packing,
and license requirements. They need a report of distance traveled and charges grouped by date and
license type.

The following table shows a sample of the data:

Ship Date District Distance Equipment Packing License Charge

...
2000-06-02 1 1540 D M BUN 1300
2000-07-12 1 1320 D C SUM 4800
2000-08-02 1 1760 D C CUM 1300
2000-06-22 2 1540 D C CUN 13500
2000-07-30 2 1320 D M SUM 6000
...

The stage will output the following columns:

Column name SQL Type

DistanceSum Decimal
DistanceMean Decimal
ChargeSum Decimal
ChargeMean Decimal
license Char
shipdate Date

The stage first hash partitions the incoming data on the license column, then sorts it on license and date:

206 Parallel Job Developer Guide

The properties are then used to specify the grouping and the aggregating of the data:

The following is a sample of the output data:

Ship Date License Distance Sum Distance Mean Charge Sum Charge Mean
...
2000-06-02 BUN 1126053.00 1563.93 20427400.00 28371.39

Chapter 13. Aggregator stage 207

Ship Date License Distance Sum Distance Mean Charge Sum Charge Mean
2000-06-12 BUN 2031526.00 2074.08 22426324.00 29843.55
2000-06-22 BUN 1997321.00 1958.45 19556450.00 19813.26
2000-06-30 BUN 1815733.00 1735.77 17023668.00 18453.02
...

If you wanted to go on and work out the sum of the distance and charge sums by license, you could
insert another Aggregator stage with the following properties:

Must do’s
WebSphere DataStage has many defaults which means that it can be very easy to include Aggregator
stages in a job. This section specifies the minimum steps to take to get an Aggregator stage functioning.
WebSphere DataStage provides a versatile user interface, and there are many shortcuts to achieving a
particular end, this section describes the basic method, you will learn where the shortcuts are when you
get familiar with the product.

To use an aggregator stage:

v In the Stage page Properties Tab, under the Grouping Keys category:
– Specify the key column that the data will be grouped on. You can repeat the key property to specify
composite keys.
Under the Aggregations category:
– Choose an aggregation type. Calculation is the default, and allows you to summarize a column or
columns. Count rows allows you to count the number of rows within each group. Re-calculation
allows you to apply aggregate functions to a column that has already been summarized.
Other properties depend on the aggregate type chosen:
– If you have chosen the Calculation aggregation type, specify the column to be summarized in
Column for Calculation. You can repeat this property to specify multiple columns. Choose one or
more dependent properties to specify the type of aggregation to perform, and the name of the
output column that will hold the result.
– If you have chosen the Count Rows aggregation type, specify the output column that will hold the
count.

208 Parallel Job Developer Guide

 – If you have chosen the Re-calculation aggregation type, specify the column to be re-calculated. You
can repeat this property to specify multiple columns. Choose one or more dependent properties to
specify the type of aggregation to perform, and the name of the output column that will hold the
result.
v In the Output page Mapping Tab, check that the mapping is as you expect (WebSphere DataStage
maps data onto the output columns according to what you specify in the Properties tab).

Stage page
The General tab allows you to specify an optional description of the stage. The Properties tab lets you
specify what the stage does. The Advanced tab allows you to specify how the stage executes. The NLS
Locale tab appears if your have NLS enabled on your system. It allows you to select a locale other than
the project default to determine collating rules.

Properties tab
The Properties tab allows you to specify properties which determine what the stage actually does. Some
of the properties are mandatory, although many have default settings. Properties without default settings
appear in the warning color (red by default) and turn black when you supply a value for them.

The following table gives a quick reference list of the properties and their attributes. A more detailed
description of each property follows.

Category/
Property Values Default Mandatory? Repeats? Dependent of
Grouping Input column N/A Y Y N/A
Keys/Group
Grouping True/ False True N N Group
Keys/Case
Sensitive
Aggregations/ Calculation/ Calculation Y N N/A
Aggregation Type Recalculation/
Count rows
Aggregations/ Input column N/A Y (if Aggregation Y N/A
Column for Type =
Calculation Calculation)
Aggregations/ Output column N/A Y (if Aggregation Y N/A
Count Output Type = Count
Column Rows)
Aggregations/ Input column N/A Y (if Aggregation Y N/A
Summary Type =
Column for Recalculation)
Recalculation
Aggregations/ precision, scale 8,2 N N N/A
Default To
Decimal Output
Aggregations/ Output column N/A N N Column for
Corrected Sum of Calculation &
Squares Summary
Column for
Recalculation

Chapter 13. Aggregator stage 209

Category/
Property Values Default Mandatory? Repeats? Dependent of
Aggregations/ Output column N/A N N Column for
Maximum Value Calculation &
Summary
Column for
Recalculation
Aggregations/ Output column N/A N N Column for
Mean Value Calculation &
Summary
Column for
Recalculation
Aggregations/ Output column N/A N N Column for
Minimum Value Calculation &
Summary
Column for
Recalculation
Aggregations/ Output column N/A N Y Column for
Missing Value Calculation
Aggregations/ Output column N/A N N Column for
Missing Values Calculation &
Count Summary
Column for
Recalculation
Aggregations/ Output column N/A N N Column for
Non-missing Calculation &
Values Count Summary
Column for
Recalculation
Aggregations/ Output column N/A N N Column for
Percent Calculation &
Coefficient of Summary
Variation Column for
Recalculation
Aggregations/ Output column N/A N N Column for
Range Calculation &
Summary
Column for
Recalculation
Aggregations/ Output column N/A N N Column for
Standard Calculation &
Deviation Summary
Column for
Recalculation
Aggregations/ Output column N/A N N Column for
Standard Error Calculation &
Summary
Column for
Recalculation
Aggregations/ Output column N/A N N Column for
Sum of Weights Calculation &
Summary
Column for
Recalculation

210 Parallel Job Developer Guide

Category/
Property Values Default Mandatory? Repeats? Dependent of
Aggregations/ Output column N/A N N Column for
Sum Calculation &
Summary
Column for
Recalculation
Aggregations/ Output column N/A N N Column for
Summary Calculation &
Summary
Column for
Recalculation
Aggregations/ Output column N/A N N Column for
Uncorrected Sum Calculation &
of Squares Summary
Column for
Recalculation
Aggregations/ Output column N/A N N Column for
Variance Calculation &
Summary
Column for
Recalculation
Aggregations/ Default/ Nrecs Default N N Variance
Variance divisor
Aggregations/ Input column N/A N N Column for
Calculation and Calculation or
Recalculation Count Output
Dependent Column
Properties
Aggregations/ precision, scale 8,2 N N Calculation or
Decimal Output Recalculation
method
Options/Group hash/sort hash Y Y N/A
Options/Allow True/ False False Y N N/A
Null Outputs

Grouping keys category

Group

Specifies the input columns you are using as group keys. Repeat the property to select multiple columns
as group keys. You can use the Column Selection dialog box to select several group keys at once if
required). This property has a dependent property:
v Case Sensitive
Use this to specify whether each group key is case sensitive or not, this is set to True by default, that
is, the values ″CASE″ and ″case″ in would end up in different groups.

Aggregations category
Aggregation type

This property allows you to specify the type of aggregation operation your stage is performing. Choose
from Calculate (the default), Recalculate, and Count Rows.

Chapter 13. Aggregator stage 211

Column for calculation

The Calculate aggregate type allows you to summarize the contents of a particular column or columns in
your input data set by applying one or more aggregate functions to it. Select the column to be
aggregated, then select dependent properties to specify the operation to perform on it, and the output
column to carry the result. You can use the Column Selection dialog box to select several columns for
calculation at once if required).

Count output column

The Count Rows aggregate type performs a count of the number of records within each group. Specify
the column on which the count is output.

Summary column for recalculation

This aggregate type allows you to apply aggregate functions to a column that has already been
summarized. This is like calculate but performs the specified aggregate operation on a set of data that has
already been summarized. In practice this means you should have performed a calculate (or recalculate)
operation in a previous Aggregator stage with the Summary property set to produce a subrecord
containing the summary data that is then included with the data set. Select the column to be aggregated,
then select dependent properties to specify the operation to perform on it, and the output column to
carry the result. You can use the Column Selection dialog box to select several columns for recalculation
at once if required).

Weighting column

Configures the stage to increment the count for the group by the contents of the weight column for each
record in the group, instead of by 1. Not available for Summary Column for Recalculation. Setting this
option affects only the following options:
v Percent Coefficient of Variation
v Mean Value
v Sum
v Sum of Weights
v Uncorrected Sum of Squares

Default to decimal output

The output type of a calculation or recalculation column is double. Setting this property causes it to
default to decimal. You can also set a default precision and scale. (You can also specify that individual
columns have decimal output while others retain the default type of double.)

Options category
Method

The aggregate stage has two modes of operation: hash and sort. Your choice of mode depends primarily
on the number of groupings in the input data set, taking into account the amount of memory available.
You typically use hash mode for a relatively small number of groups; generally, fewer than about 1000
groups per megabyte of memory to be used.

When using hash mode, you should hash partition the input data set by one or more of the grouping key
columns so that all the records in the same group are in the same partition (this happens automatically if
auto is set in the Partitioning tab). However, hash partitioning is not mandatory, you can use any
partitioning method you choose if keeping groups together in a single partition is not important. For

212 Parallel Job Developer Guide

example, if you’re summing records in each partition and later you’ll add the sums across all partitions,
you don’t need all records in a group to be in the same partition to do this. Note, though, that there will
be multiple output records for each group.

If the number of groups is large, which can happen if you specify many grouping keys, or if some
grouping keys can take on many values, you would normally use sort mode. However, sort mode
requires the input data set to have been partition sorted with all of the grouping keys specified as
hashing and sorting keys (this happens automatically if auto is set in the Partitioning tab). Sorting
requires a pregrouping operation: after sorting, all records in a given group in the same partition are
consecutive.

The method property is set to hash by default.

You may want to try both modes with your particular data and application to determine which gives the
better performance. You may find that when calculating statistics on large numbers of groups, sort mode
performs better than hash mode, assuming the input data set can be efficiently sorted before it is passed
to group.

Allow null outputs

Set this to True to indicate that null is a valid output value when calculating minimum value, maximum
value, mean value, standard deviation, standard error, sum, sum of weights, and variance. If False, the
null value will have 0 substituted when all input values for the calculation column are null. It is False by
default.

Calculation and recalculation dependent properties

The following properties are dependents of both Column for Calculation and Summary Column for
Recalculation. These specify the various aggregate functions and the output columns to carry the results.
v Corrected Sum of Squares
Produces a corrected sum of squares for data in the aggregate column and outputs it to the specified
output column.
v Maximum Value
Gives the maximum value in the aggregate column and outputs it to the specified output column.
v Mean Value
Gives the mean value in the aggregate column and outputs it to the specified output column.
v Minimum Value
Gives the minimum value in the aggregate column and outputs it to the specified output column.
v Missing Value
This specifies what constitutes a ″missing″ value, for example -1 or NULL. Enter the value as a floating
point number. Not available for Summary Column to Recalculate.
v Missing Values Count
Counts the number of aggregate columns with missing values in them and outputs the count to the
specified output column. Not available for recalculate.
v Non-missing Values Count
Counts the number of aggregate columns with values in them and outputs the count to the specified
output column.
v Percent Coefficient of Variation
Calculates the percent coefficient of variation for the aggregate column and outputs it to the specified
output column.
v Range
Calculates the range of values in the aggregate column and outputs it to the specified output column.

Chapter 13. Aggregator stage 213

v Standard Deviation
Calculates the standard deviation of values in the aggregate column and outputs it to the specified
output column.
v Standard Error
Calculates the standard error of values in the aggregate column and outputs it to the specified output
column.
v Sum of Weights
Calculates the sum of values in the weight column specified by the Weight column property and
outputs it to the specified output column.
v Sum
Sums the values in the aggregate column and outputs the sum to the specified output column.
v Summary
Specifies a subrecord to write the results of the calculate or recalculate operation to.
v Uncorrected Sum of Squares
Produces an uncorrected sum of squares for data in the aggregate column and outputs it to the
specified output column.
v Variance
Calculates the variance for the aggregate column and outputs the sum to the specified output column.
This has a dependent property:
– Variance divisor
Specifies the variance divisor. By default, uses a value of the number of records in the group minus
the number of records with missing values minus 1 to calculate the variance. This corresponds to a
vardiv setting of Default. If you specify NRecs, WebSphere DataStage uses the number of records in
the group minus the number of records with missing values instead.

Each of these properties has a dependent property as follows:

v Decimal Output. By default all calculation or recalculation columns have an output type of double.
This property allows you to specify that the column has an output type of decimal. You can also
specify a precision and scale for they type (by default 8,2).

Advanced tab
This tab allows you to specify the following:
v Execution Mode. The stage can execute in parallel mode or sequential mode. In parallel mode the
input data set is processed by the available nodes as specified in the Configuration file, and by any
node constraints specified on the Advanced tab. In Sequential mode the entire data set is processed by
the conductor node.
v Combinability mode. This is Auto by default, which allows WebSphere DataStage to combine the
operators that underlie parallel stages so that they run in the same process if it is sensible for this type
of stage.
v Preserve partitioning. This is Set by default. You can select Set or Clear. If you select Set the stage
will request that the next stage in the job attempt to maintain the partitioning.
v Node pool and resource constraints. Select this option to constrain parallel execution to the node pool
or pools and/or resource pool or pools specified in the grid. The grid allows you to make choices from
drop down lists populated from the Configuration file.
v Node map constraint. Select this option to constrain parallel execution to the nodes in a defined node
map. You can define a node map by typing node numbers into the text box or by clicking the browse
button to open the Available Nodes dialog box and selecting nodes from there. You are effectively
defining a new node pool for this stage (in addition to any node pools defined in the Configuration
file).

214 Parallel Job Developer Guide

NLS Locale tab
This appears if you have NLS enabled on your system. It lets you view the current default collate
convention, and select a different one for this stage if required. You can also use a job parameter to
specify the locale, or browse for a file that defines custom collate rules. The collate convention defines the
order in which characters are collated. The Aggregator stage uses this when it is grouping by key to
determine the order of the key fields. Select a locale from the list, or click the arrow button next to the list
to use a job parameter or browse for a collate file.

Input page
The Input page allows you to specify details about the incoming data set.

The General tab allows you to specify an optional description of the input link. The Partitioning tab
allows you to specify how incoming data is partitioned before being grouped and/or summarized. The
Columns tab specifies the column definitions of incoming data. The Advanced tab allows you to change
the default buffering settings for the input link.

Details about Aggregator stage partitioning are given in the following section. See ″Stage Editors,″ for a
general description of the other tabs.

Partitioning tab
The Partitioning tab allows you to specify details about how the incoming data is partitioned or collected
before it is grouped and/or summarized. It also allows you to specify that the data should be sorted
before being operated on.

By default the stage partitions in Auto mode. This attempts to work out the best partitioning method
depending on execution modes of current and preceding stages and how many nodes are specified in the
Configuration file.

If the Aggregator stage is operating in sequential mode, it will first collect the data before writing it to
the file using the default Auto collection method.

The Partitioning tab allows you to override this default behavior. The exact operation of this tab depends
on:
v Whether the Aggregator stage is set to execute in parallel or sequential mode.
v Whether the preceding stage in the job is set to execute in parallel or sequential mode.

If the Aggregator stage is set to execute in parallel, then you can set a partitioning method by selecting
from the Partition type drop-down list. This will override any current partitioning.

If the Aggregator stage is set to execute in sequential mode, but the preceding stage is executing in
parallel, then you can set a collection method from the Collector type drop-down list. This will override
the default collection method.

The following partitioning methods are available:

v (Auto). WebSphere DataStage attempts to work out the best partitioning method depending on
execution modes of current and preceding stages and how many nodes are specified in the
Configuration file. This is the default partitioning method for the Aggregator stage.
v Entire. Each file written to receives the entire data set.
v Hash. The records are hashed into partitions based on the value of a key column or columns selected
from the Available list.

Chapter 13. Aggregator stage 215

v Modulus. The records are partitioned using a modulus function on the key column selected from the
Available list. This is commonly used to partition on tag fields.
v Random. The records are partitioned randomly, based on the output of a random number generator.
v Round Robin. The records are partitioned on a round robin basis as they enter the stage.
v Same. Preserves the partitioning already in place.
v DB2. Replicates the DB2 partitioning method of a specific DB2 table. Requires extra properties to be
set. Access these properties by clicking the properties button.
v Range. Divides a data set into approximately equal size partitions based on one or more partitioning
keys. Range partitioning is often a preprocessing step to performing a total sort on a data set. Requires
extra properties to be set. Access these properties by clicking the properties button.

The following Collection methods are available:

v (Auto). This is the default collection method for Aggregator stages. Normally, when you are using Auto
mode, WebSphere DataStage will eagerly read any row from any input partition as it becomes
available.
v Ordered. Reads all records from the first partition, then all records from the second partition, and so
on.
v Round Robin. Reads a record from the first input partition, then from the second partition, and so on.
After reaching the last partition, the operator starts over.
v Sort Merge. Reads records in an order based on one or more columns of the record. This requires you
to select a collecting key column from the Available list.

The Partitioning tab also allows you to specify that data arriving on the input link should be sorted
before being written to the file or files. The sort is always carried out within data partitions. If the stage is
partitioning incoming data the sort occurs after the partitioning. If the stage is collecting data, the sort
occurs before the collection. The availability of sorting depends on the partitioning or collecting method
chosen (it is not available for the default auto modes).

Select the check boxes as follows:

v Perform Sort. Select this to specify that data coming in on the link should be sorted. Select the column
or columns to sort on from the Available list.
v Stable. Select this if you want to preserve previously sorted data sets. This is the default.
v Unique. Select this to specify that, if multiple records have identical sorting key values, only one
record is retained. If stable sort is also set, the first record is retained.

If NLS is enabled an additional button opens a dialog box allowing you to select a locale specifying the
collate convention for the sort.

You can also specify sort direction, case sensitivity, whether sorted as ASCII or EBCDIC, and whether null
columns will appear first or last for each column. Where you are using a keyed partitioning method, you
can also specify whether the column is used as a key for sorting, for partitioning, or for both. Select the
column in the Selected list and right-click to invoke the shortcut menu.

Output page
The Output page allows you to specify details about data output from the Aggregator stage. The
Aggregator stage can have only one output link.

The General tab allows you to specify an optional description of the output link. The Columns tab
specifies the column definitions of incoming data. The Mapping tab allows you to specify the relationship
between the processed data being produced by the Aggregator stage and the Output columns. The
Advanced tab allows you to change the default buffering settings for the output link.

216 Parallel Job Developer Guide

Details about Aggregator stage mapping is given in the following section. See ″Stage Editors,″ for a
general description of the other tabs.

Mapping tab
For the Aggregator stage the Mapping tab allows you to specify how the output columns are derived, i.e.,
what input columns map onto them or how they are generated.

The left pane shows the input columns and/or the generated columns. These are read only and cannot be
modified on this tab.

The right pane shows the output columns for each link. This has a Derivations field where you can
specify how the column is derived.You can fill it in by dragging columns over from the left pane, or by
using the Auto-match facility.

Chapter 13. Aggregator stage 217

218 Parallel Job Developer Guide
Chapter 14. Join stage
The Join stage is a processing stage. It performs join operations on two or more data sets input to the
stage and then outputs the resulting data set. The Join stage is one of three stages that join tables based
on the values of key columns. The other two are:
v Chapter 16, “Lookup Stage,” on page 235

The three stages differ mainly in the memory they use, the treatment of rows with unmatched keys, and
their requirements for data being input (for example, whether it is sorted). See ″Join Versus Lookup″ for
help in deciding which stage to use.

In the Join stage, the input data sets are notionally identified as the ″right″ set and the ″left″ set, and
″intermediate″ sets. You can specify which is which. It has any number of input links and a single output

link.

The stage can perform one of four join operations:

v Inner transfers records from input data sets whose key columns contain equal values to the output
data set. Records whose key columns do not contain equal values are dropped.
v Left outer transfers all values from the left data set but transfers values from the right data set and
intermediate data sets only where key columns match. The stage drops the key column from the right
and intermediate data sets.
v Right outer transfers all values from the right data set and transfers values from the left data set and
intermediate data sets only where key columns match. The stage drops the key column from the left
and intermediate data sets.

© Copyright IBM Corp. 2006 219

v Full outer transfers records in which the contents of the key columns are equal from the left and right
input data sets to the output data set. It also transfers records whose key columns contain unequal
values from both input data sets to the output data set. (Full outer joins do not support more than two
input links.)

The data sets input to the Join stage must be key partitioned and sorted. This ensures that rows with the
same key column values are located in the same partition and will be processed by the same node. It also
minimizes memory requirements because fewer rows need to be in memory at any one time. Choosing
the auto partitioning method will ensure that partitioning and sorting is done. If sorting and partitioning
are carried out on separate stages before the Join stage, WebSphere DataStage in auto mode will detect
this and not repartition (alternatively you could explicitly specify the Same partitioning method).

The Join stage editor has three pages:

v Stage Page. This is always present and is used to specify general information about the stage.
v Input Page. This is where you specify details about the data sets being joined.
v Output Page. This is where you specify details about the joined data being output from the stage.

Join versus lookup

WebSphere DataStage does not know how large your data is, so cannot make an informed choice
whether to combine data using a join stage or a lookup stage. Here’s how to decide which to use:

There are two data sets being combined. One is the primary or driving dataset, sometimes called the left
of the join. The other data set(s) are the reference datasets, or the right of the join.

In all cases we are concerned with the size of the reference datasets. If these take up a large amount of
memory relative to the physical RAM memory size of the computer you are running on, then a lookup
stage may thrash because the reference datasets may not fit in RAM along with everything else that has
to be in RAM. This results in very slow performance since each lookup operation can, and typically does,
cause a page fault and an I/O operation.

So, if the reference datasets are big enough to cause trouble, use a join. A join does a high-speed sort on
the driving and reference datasets. This can involve I/O if the data is big enough, but the I/O is all
highly optimized and sequential. Once the sort is over the join processing is very fast and never involves
paging or other I/O.

Example joins
The following examples show what happens to two data sets when each type of join operation is applied
to them. Here are the two data sets:

Left Input Data Set Right Input Data Set

Status Price Price ID
sold 125 113 NI6325
sold 213 125 BR9658
offered 378 285 CZ2538
Pending 575 628 RU5713
Pending 649 668 SA5680
Offered 777 777 JA1081
Offered 908 908 DE1911
Pending 908 908 FR2081

220 Parallel Job Developer Guide

Price is the key column which is going to be joined on, and bold type indicates where the data sets share
the same value for Price. The data sets are already sorted on that key.

Inner join
Here is the data set that is output if you perform an inner join on the Price key column:

Output Data Set

Status Price ID
sold 125 NI6325
Offered 777 JA1081
Offered 908 DE1911
Offered 908 FR2081
Pending 908 DE1911
Pending 908 FR2081

Left outer join

Here is the data set that is output if you perform a left outer join on the Price key column:

Output Data Set

Status Price ID
sold 125 NI6325
sold 213
offered 378
Pending 575
Pending 649
Offered 777 JA1081
Offered 908 DE1911
Offered 908 FR2081
Pending 908 DE1911
Pending 908 FR2081

Right outer join

Here is the data set that is output if you perform a right outer join on the Price key column

Output Data Set

Status Price ID
113 NI6325
sold 125 BR9658
285 CZ2538
628 RU5713
668 SA5680
Offered 777 JA1081

Chapter 14. Join stage 221

Output Data Set
Status Price ID
Offered 908 DE1911
Offered 908 FR2081
Pending 908 DE1911
Pending 908 FR2081

Full outer join

Here is the data set that is output if you perform a full outer join on the Price key column:

Output Data Set

Status Price Price ID
113 NI6325
sold 125 125 BR9658
sold 213
285 CZ2538
offered 378
Pending 575
628 RU5713
Pending 649
668 SA5680
Status Price Price ID
Offered 777 777 JA1081
Offered 908 908 DE1911
Offered 908 908 FR2081
Pending 908 908 DE1911
Pending 908 908 FR2081

Must do’s
WebSphere DataStage has many defaults which means that Joins can be simple to set up. This section
specifies the minimum steps to take to get a Join stage functioning. WebSphere DataStage provides a
versatile user interface, and there are many shortcuts to achieving a particular end, this section describes
the basic method, you will learn where the shortcuts are when you get familiar with the product.
v In the Stage page Properties Tab specify the key column or columns that the join will be performed
on.
v In the Stage page Properties Tab specify the join type or accept the default of Inner.
v In the Stage page Link Ordering Tab, check that your links are correctly identified as ″left″, ″right″,
and ″intermediate″ and reorder if required.
v Ensure required column meta data has been specified (this may be done in another stage).
v In the Output Page Mapping Tab, specify how the columns from the input links map onto output
columns.

222 Parallel Job Developer Guide

Stage page
The General tab allows you to specify an optional description of the stage. The Properties tab lets you
specify what the stage does. The Advanced tab allows you to specify how the stage executes. The Link
Ordering tab allows you to specify which of the input links is the right link and which is the left link and
which are intermediate. The NLS Locale tab appears if your have NLS enabled on your system. It allows
you to select a locale other than the project default to determine collating rules.

Properties tab
The Properties tab allows you to specify properties which determine what the stage actually does. Some
of the properties are mandatory, although many have default settings. Properties without default settings
appear in the warning color (red by default) and turn black when you supply a value for them.

The following table gives a quick reference list of the properties and their attributes. A more detailed
description of each property follows.

Category/
Property Values Default Mandatory? Repeats? Dependent of
Join Keys/“Key” Input Column N/A Y Y N/A
Join Keys/Case True/False True N N Key
Sensitive
Options/“Options Full Outer/ Inner Y N N/A
category” Inner/Left
Outer/ Right
Outer

Join keys category

Key

Choose the input column you want to join on. You are offered a choice of input columns common to all
links. For a join to work you must join on a column that appears in all input data sets, i.e. have the same
name and compatible data types. If, for example, you select a column called ″name″ from the left link, the
stage will expect there to be an equivalent column called ″name″ on the right link.

You can join on multiple key columns. To do so, repeat the Key property. You can use the Column
Selection dialog box to select several key columns at once if required).

Key has a dependent property:

Case Sensitive
v Case Sensitive
Use this to specify whether each group key is case sensitive or not, this is set to True by default, that
is, the values ″CASE″ and ″case″ in would not be judged equivalent.

Options category
Join type

Specify the type of join operation you want to perform. Choose one of:
v Full Outer
v Inner
v Left Outer
v Right Outer

Chapter 14. Join stage 223

The default is Inner.

Advanced tab
This tab allows you to specify the following:
v Execution Mode. The stage can execute in parallel mode or sequential mode. In parallel mode the
input data is processed by the available nodes as specified in the Configuration file, and by any node
constraints specified on the Advanced tab. In Sequential mode the entire data set is processed by the
conductor node.
v Combinability mode. This is Auto by default, which allows WebSphere DataStage to combine the
operators that underlie parallel stages so that they run in the same process if it is sensible for this type
of stage.
v Preserve partitioning. This is Propagate by default. It adopts the setting which results from ORing the
settings of the input stages, i.e., if either of the input stages uses Set then this stage will use Set. You
can explicitly select Set or Clear. Select Set to request that the next stage in the job attempts to
maintain the partitioning.
v Node pool and resource constraints. Select this option to constrain parallel execution to the node pool
or pools and/or resource pool or pools specified in the grid. The grid allows you to make choices from
drop down lists populated from the Configuration file.
v Node map constraint. Select this option to constrain parallel execution to the nodes in a defined node
map. You can define a node map by typing node numbers into the text box or by clicking the browse
button to open the Available Nodes dialog box and selecting nodes from there. You are effectively
defining a new node pool for this stage (in addition to any node pools defined in the Configuration
file).

Link ordering tab

This tab allows you to specify which input link is regarded as the left link and which link is regarded as
the right link, and which links are regarded as intermediate. By default the first link you add is regarded
as the left link, and the last one as the right link, with all other links labelled as Intermediate N. You can
use this tab to override the default order.

In the example DSLink4 is the left link, click on it to select it then click on the down arrow to convert it
into the right link.

NLS Locale tab

This appears if you have NLS enabled on your system. It lets you view the current default collate
convention, and select a different one for this stage if required. You can also use a job parameter to
specify the locale, or browse for a file that defines custom collate rules. The collate convention defines the
order in which characters are collated. The Join stage uses this when it is determining the order of the
key fields. Select a locale from the list, or click the arrow button next to the list to use a job parameter or
browse for a collate file.

Input page
The Input page allows you to specify details about the incoming data sets. Choose an input link from the
Input name drop down list to specify which link you want to work on.

The General tab allows you to specify an optional description of the input link. The Partitioning tab
allows you to specify how incoming data is partitioned before being joined. The Columns tab specifies
the column definitions of incoming data. The Advanced tab allows you to change the default buffering
settings for the input link.

224 Parallel Job Developer Guide

Details about Join stage partitioning are given in the following section. See ″Stage Editors,″ for a general
description of the other tabs.

Partitioning on input links

The Partitioning tab allows you to specify details about how the data on each of the incoming links is
partitioned or collected before it is joined. It also allows you to specify that the data should be sorted
before being operated on.

By default the stage partitions in Auto mode. This attempts to work out the best partitioning method
depending on execution modes of current and preceding stages and how many nodes are specified in the
Configuration file. Auto mode ensures that data being input to the Join stage is key partitioned and
sorted.

If the Join stage is operating in sequential mode, it will first collect the data before writing it to the file
using the default Auto collection method.

The Partitioning tab allows you to override this default behavior. The exact operation of this tab depends
on:
v Whether the Join stage is set to execute in parallel or sequential mode.
v Whether the preceding stage in the job is set to execute in parallel or sequential mode.

If the Join stage is set to execute in parallel, then you can set a partitioning method by selecting from the
Partition type drop-down list. This will override any current partitioning.

If the Join stage is set to execute in sequential mode, but the preceding stage is executing in parallel, then
you can set a collection method from the Collector type drop-down list. This will override the default
collection method.

The following partitioning methods are available:

v (Auto). WebSphere DataStage attempts to work out the best partitioning method depending on
execution modes of current and preceding stages and how many nodes are specified in the
Configuration file. This is the default collection method for the Join stage.
v Entire. Each file written to receives the entire data set.
v Hash. The records are hashed into partitions based on the value of a key column or columns selected
from the Available list.
v Modulus. The records are partitioned using a modulus function on the key column selected from the
Available list. This is commonly used to partition on tag fields.
v Random. The records are partitioned randomly, based on the output of a random number generator.
v Round Robin. The records are partitioned on a round robin basis as they enter the stage.
v Same. Preserves the partitioning already in place.
v DB2. Replicates the DB2 partitioning method of a specific DB2 table. Requires extra properties to be
set. Access these properties by clicking the properties button.
v Range. Divides a data set into approximately equal size partitions based on one or more partitioning
keys. Range partitioning is often a preprocessing step to performing a total sort on a data set. Requires
extra properties to be set. Access these properties by clicking the properties button.

The following Collection methods are available:

v (Auto). This is the default collection method for the Join stage. Normally, when you are using Auto
mode, WebSphere DataStage will eagerly read any row from any input partition as it becomes
available. In the case of a Join stage, Auto will also ensure that the collected data is sorted.

Chapter 14. Join stage 225

v Ordered. Reads all records from the first partition, then all records from the second partition, and so
on.
v Round Robin. Reads a record from the first input partition, then from the second partition, and so on.
After reaching the last partition, the operator starts over.
v Sort Merge. Reads records in an order based on one or more columns of the record. This requires you
to select a collecting key column from the Available list.

The Partitioning tab also allows you to explicitly specify that data arriving on the input link should be
sorted before being joined (you might use this if you have selected a partitioning method other than auto
or same). The sort is always carried out within data partitions. If the stage is partitioning incoming data
the sort occurs after the partitioning. If the stage is collecting data, the sort occurs before the collection.
The availability of sorting depends on the partitioning or collecting method chosen (it is not available
with the default auto methods).

Select the check boxes as follows:

v Perform Sort. Select this to specify that data coming in on the link should be sorted. Select the column
or columns to sort on from the Available list.
v Stable. Select this if you want to preserve previously sorted data sets. This is the default.
v Unique. Select this to specify that, if multiple records have identical sorting key values, only one
record is retained. If stable sort is also set, the first record is retained.

If NLS is enabled an additional button opens a dialog box allowing you to select a locale specifying the
collate convention for the sort.

You can also specify sort direction, case sensitivity, whether sorted as ASCII or EBCDIC, and whether null
columns will appear first or last for each column. Where you are using a keyed partitioning method, you
can also specify whether the column is used as a key for sorting, for partitioning, or for both. Select the
column in the Selected list and right-click to invoke the shortcut menu.

Output page
The Output page allows you to specify details about data output from the Join stage. The Join stage can
have only one output link.

The General tab allows you to specify an optional description of the output link. The Columns tab
specifies the column definitions of the data. The Mapping tab allows you to specify the relationship
between the columns being input to the Join stage and the Output columns. The Advanced tab allows
you to change the default buffering settings for the output link.

Details about Join stage mapping is given in the following section. See ″Stage Editors,″ for a general
description of the other tabs.

Mapping tab
For Join stages the Mapping tab allows you to specify how the output columns are derived, i.e., what
input columns map onto them.

The left pane shows the input columns from the links whose tables have been joined. These are read only
and cannot be modified on this tab.

The right pane shows the output columns for the output link. This has a Derivations field where you can
specify how the column is derived. You can fill it in by dragging input columns over, or by using the
Auto-match facility.

226 Parallel Job Developer Guide

Chapter 15. Merge Stage
The Merge stage is a processing stage. It can have any number of input links, a single output link, and
the same number of reject links as there are update input links.

The Merge stage is one of three stages that join tables based on the values of key columns. The other two
are:
v Chapter 14, “Join stage,” on page 219
v Chapter 16, “Lookup Stage,” on page 235

The three stages differ mainly in the memory they use, the treatment of rows with unmatched keys, and
their requirements for data being input (for example, whether it is sorted).

The Merge stage combines a master data set with one or more update data sets. The columns from the
records in the master and update data sets are merged so that the output record contains all the columns
from the master record plus any additional columns from each update record that are required. A master
record and an update record are merged only if both of them have the same values for the merge key
column(s) that you specify. Merge key columns are one or more columns that exist in both the master
and update records.

The data sets input to the Merge stage must be key partitioned and sorted. This ensures that rows with
the same key column values are located in the same partition and will be processed by the same node. It
also minimizes memory requirements because fewer rows need to be in memory at any one time.
Choosing the auto partitioning method will ensure that partitioning and sorting is done. If sorting and

© Copyright IBM Corp. 2006 227

partitioning are carried out on separate stages before the Merge stage, WebSphere DataStage in auto
partition mode will detect this and not repartition (alternatively you could explicitly specify the Same
partitioning method).

As part of preprocessing your data for the Merge stage, you should also remove duplicate records from
the master data set. If you have more than one update data set, you must remove duplicate records from
the update data sets as well. See Chapter 19, “Remove Duplicates Stage,” on page 277 for information
about the Remove Duplicates stage.

Unlike Join stages and Lookup stages, the Merge stage allows you to specify several reject links. You can
route update link rows that fail to match a master row down a reject link that is specific for that link. You
must have the same number of reject links as you have update links. The Link Ordering tab on the Stage
page lets you specify which update links send rejected rows to which reject links. You can also specify
whether to drop unmatched master rows, or output them on the output data link.

The stage editor has three pages:

v Stage Page. This is always present and is used to specify general information about the stage.
v Input Page. This is where you specify details about the data sets being merged.
v Output Page. This is where you specify details about the merged data being output from the stage and
about the reject links.

Example merge
This example shows what happens to a master data set and two update data sets when they are merged.
The key field is Horse, and all the data sets are sorted in descending order. Here is the master data set:

Horse Freezemark Mchip Reg_Soc Level

William DAM7 N/A FPS Adv
Robin DG36 N/A FPS Nov
Kayser N/A N/A AHS N/A
Heathcliff A1B1 N/A N/A Adv
Fairfax N/A N/A FPS N/A
Chaz N/A a296100da AHS Inter

Here is the Update 1 data set:

Horse vacc. last_worm

William 07.07.02 12.10.02
Robin 07.07.02 12.10.02
Kayser 11.12.02 12.10.02
Heathcliff 07.07.02 12.10.02
Fairfax 11.12.02 12.10.02
Chaz 10.02.02 12.10.02

Here is the Update 2 data set:

Horse last_trim shoes

William 11.05.02 N/A

228 Parallel Job Developer Guide

Horse last_trim shoes
Robin 12.03.02 refit
Kayser 11.05.02 N/A
Heathcliff 12.03.02 new
Fairfax 12.03.02 N/A
Chaz 12.03.02 new

Here is the merged data set output by the stage:

Freeze
Horse mark Mchip Reg. Soc Level vacc. last worm last trim shoes
William DAM7 N/A FPS Adv 07.07.02 12.10.02 11.05.02 N/A
Robin DG36 N?A FPS Nov 07.07.02 12.10.02 12.03.02 refit
Kayser N/A N/A AHS Nov 11.12.02 12.10.02 11.05.02 N/A
Heathcliff A1B1 N/A N/A Adv 07.07.02 12.10.02 12.03.02 new
Fairfax N/A N/A FPS N/A 11.12.02 12.10.02 12.03.02 N/A
Chaz N/A a2961da AHS Inter 10.02.02 12.10.02 12.03.02 new

Must do’s
WebSphere DataStage has many defaults which means that Merges can be simple to set up. This section
specifies the minimum steps to take to get a Merge stage functioning. WebSphere DataStage provides a
versatile user interface, and there are many shortcuts to achieving a particular end, this section describes
the basic method, you will learn where the shortcuts are when you get familiar with the product.
v In the Stage page Properties Tab specify the key column or columns that the Merge will be performed
on.
v In the Stage page Properties Tab set the Unmatched Masters Mode, Warn on Reject Updates, and Warn
on Unmatched Masters options or accept the defaults.
v In the Stage page Link Ordering Tab, check that your input links are correctly identified as ″master″
and ″update(s)″, and your output links are correctly identified as ″master″ and ″update reject″. Reorder
if required.
v Ensure required column meta data has been specified (this may be done in another stage, or may be
omitted altogether if you are relying on Runtime Column Propagation).
v In the Output Page Mapping Tab, specify how the columns from the input links map onto output
columns.

Stage page
The General tab allows you to specify an optional description of the stage. The Properties tab lets you
specify what the stage does. The Advanced tab allows you to specify how the stage executes. The NLS
Locale tab appears if your have NLS enabled on your system. It allows you to select a locale other than
the project default to determine collating rules.

Properties tab
The Properties tab allows you to specify properties that determine what the stage actually does. Some of
the properties are mandatory, although many have default settings. Properties without default settings
appear in the warning color (red by default) and turn black when you supply a value for them.

Chapter 15. Merge Stage 229

The following table gives a quick reference list of the properties and their attributes. A more detailed
description of each property follows.

Category/
Property Values Default Mandatory? Repeats? Dependent of
Merge Keys/Key Input Column N/A Y Y N/A
Merge Keys/Sort Ascending/ Ascending Y N Key
Order Descending
Merge First/Last First N N Key
Keys/Nulls
position
Merge Keys/Sort True/False False N N Key
as EBCDIC
Merge Keys/Case True/False True N N Key
Sensitive
Options/ Keep/Drop Keep Y N N/A
Unmatched
Masters Mode
Options/Warn True/False True Y N N/A
On Reject Masters
Options/Warn True/False True Y N N/A
On Reject
Updates

Merge keys category

Key

This specifies the key column you are merging on. Repeat the property to specify multiple keys. You can
use the Column Selection dialog box to select several keys at once if required. Key has the following
dependent properties:
v Sort Order
Choose Ascending or Descending. The default is Ascending.
v Nulls position
By default columns containing null values appear first in the merged data set. To override this default
so that columns containing null values appear last in the merged data set, select Last.
v Sort as EBCDIC
To sort as in the EBCDIC character set, choose True.
v Case Sensitive
Use this to specify whether each merge key is case sensitive or not, this is set to True by default, i.e.,
the values ″CASE″ and ″case″ would not be judged equivalent.

Options category
Unmatched Masters Mode

Set to Keep by default. It specifies that unmatched rows from the master link are output to the merged
data set. Set to Drop to specify that rejected records are dropped instead.

Warn On Reject Masters

Set to True by default. This will warn you when bad records from the master link are rejected. Set it to
False to receive no warnings.

230 Parallel Job Developer Guide

Warn On Reject Updates

Set to True by default. This will warn you when bad records from any update links are rejected. Set it to
False to receive no warnings.

Advanced Tab
This tab allows you to specify the following:
v Execution Mode. The stage can execute in parallel mode or sequential mode. In parallel mode the
input data is processed by the available nodes as specified in the Configuration file, and by any node
constraints specified on the Advanced tab. In Sequential mode the entire data set is processed by the
conductor node.
v Combinability mode. This is Auto by default, which allows WebSphere DataStage to combine the
operators that underlie parallel stages so that they run in the same process if it is sensible for this type
of stage.
v Preserve partitioning. This is Propagate by default. It adopts the setting which results from ORing the
settings of the input stages, i.e., if any of the input stages uses Set then this stage will use Set. You can
explicitly select Set or Clear. Select Set to request the next stage in the job attempts to maintain the
partitioning.
v Node pool and resource constraints. Select this option to constrain parallel execution to the node pool
or pools and/or resource pool or pools specified in the grid. The grid allows you to make choices from
drop down lists populated from the Configuration file.
v Node map constraint. Select this option to constrain parallel execution to the nodes in a defined node
map. You can define a node map by typing node numbers into the text box or by clicking the browse
button to open the Available Nodes dialog box and selecting nodes from there. You are effectively
defining a new node pool for this stage (in addition to any node pools defined in the Configuration
file).

Link Ordering tab

This tab allows you to specify which of the input links is the master link and the order in which links
input to the Merge stage are processed. You can also specify which of the output links is the master link,
and which of the reject links corresponds to which of the incoming update links.

By default the links will be processed in the order they were added. To rearrange them, choose an input
link and click the up arrow button or the down arrow button.

NLS Locale tab

This appears if you have NLS enabled on your system. It lets you view the current default collate
convention, and select a different one for this stage if required. You can also use a job parameter to
specify the locale, or browse for a file that defines custom collate rules. The collate convention defines the
order in which characters are collated. The Merge stage uses this when it is determining the order of the
key fields. Select a locale from the list, or click the arrow button next to the list to use a job parameter or
browse for a collate file.

Input page
The Input page allows you to specify details about the data coming in to be merged. Choose an input
link from the Input name drop down list to specify which link you want to work on.

Chapter 15. Merge Stage 231

The General tab allows you to specify an optional description of the link. The Partitioning tab allows you
to specify how incoming data on the source data set link is partitioned. The Columns tab specifies the
column definitions of incoming data. The Advanced tab allows you to change the default buffering
settings for the input link.

Details about Merge stage partitioning are given in the following section. See , ″Stage Editors,″ for a
general description of the other tabs.

Partitioning tab
The Partitioning tab allows you to specify details about how the incoming data is partitioned or collected
before the merge is performed.

By default the stage uses the auto partitioning method. If the Preserve Partitioning option has been set on
the previous stage in the job, this stage will warn you if it cannot preserve the partitioning of the
incoming data. Auto mode ensures that data being input to the Merge stage is key partitioned and
sorted.

If the Merge stage is operating in sequential mode, it will first collect the data before writing it to the file
using the default auto collection method.

The Partitioning tab allows you to override this default behavior. The exact operation of this tab depends
on:
v Whether the Merge stage is set to execute in parallel or sequential mode.
v Whether the preceding stage in the job is set to execute in parallel or sequential mode.

If the Merge stage is set to execute in parallel, then you can set a partitioning method by selecting from
the Partition type drop-down list. This will override any current partitioning.

If the Merge stage is set to execute in sequential mode, but the preceding stage is executing in parallel,
then you can set a collection method from the Collector type drop-down list. This will override the
default auto collection method.

The following partitioning methods are available:

v (Auto). WebSphere DataStage attempts to work out the best partitioning method depending on
execution modes of current and preceding stages and how many nodes are specified in the
Configuration file. This is the default collection method for the Merge stage.
v Entire. Each file written to receives the entire data set.
v Hash. The records are hashed into partitions based on the value of a key column or columns selected
from the Available list.
v Modulus. The records are partitioned using a modulus function on the key column selected from the
Available list. This is commonly used to partition on tag fields.
v Random. The records are partitioned randomly, based on the output of a random number generator.
v Round Robin. The records are partitioned on a round robin basis as they enter the stage.
v Same. Preserves the partitioning already in place.
v DB2. Replicates the DB2 partitioning method of a specific DB2 table. Requires extra properties to be
set. Access these properties by clicking the properties button.
v Range. Divides a data set into approximately equal size partitions based on one or more partitioning
keys. Range partitioning is often a preprocessing step to performing a total sort on a data set. Requires
extra properties to be set. Access these properties by clicking the properties button.

The following Collection methods are available:

232 Parallel Job Developer Guide

v (Auto). This is the default collection method for the Merge stage. Normally, when you are using Auto
mode, WebSphere DataStage will eagerly read any row from any input partition as it becomes
available. In the case of a Merge stage, Auto will also ensure that the collected data is sorted.
v Ordered. Reads all records from the first partition, then all records from the second partition, and so
on.
v Round Robin. Reads a record from the first input partition, then from the second partition, and so on.
After reaching the last partition, the operator starts over.
v Sort Merge. Reads records in an order based on one or more columns of the record. This requires you
to select a collecting key column from the Available list.

The Partitioning tab also allows you to specify that data arriving on the input link should be sorted
before the merge is performed (you might use this if you have selected a partitioning method other than
auto or same). The sort is always carried out within data partitions. If the stage is partitioning incoming
data the sort occurs after the partitioning. If the stage is collecting data, the sort occurs before the
collection. The availability of sorting depends on the partitioning or collecting method chosen (it is not
available with the default auto methods).

Select the check boxes as follows:

v Perform Sort. Select this to specify that data coming in on the link should be sorted. Select the column
or columns to sort on from the Available list.
v Stable. Select this if you want to preserve previously sorted data sets. This is the default.
v Unique. Select this to specify that, if multiple records have identical sorting key values, only one
record is retained. If stable sort is also set, the first record is retained.

If NLS is enabled an additional button opens a dialog box allowing you to select a locale specifying the
collate convention for the sort.

You can also specify sort direction, case sensitivity, whether sorted as ASCII or EBCDIC, and whether null
columns will appear first or last for each column. Where you are using a keyed partitioning method, you
can also specify whether the column is used as a key for sorting, for partitioning, or for both. Select the
column in the Selected list and right-click to invoke the shortcut menu.

Output page
The Output page allows you to specify details about data output from the Merge stage. The Merge stage
can have only one master output link carrying the merged data and a number of reject links, each
carrying rejected records from one of the update links. Choose an output link from the Output name
drop down list to specify which link you want to work on.

The General tab allows you to specify an optional description of the output link. The Columns tab
specifies the column definitions of incoming data. The Mapping tab allows you to specify the relationship
between the columns being input to the Merge stage and the Output columns. The Advanced tab allows
you to change the default buffering settings for the output links.

Details about Merge stage mapping is given in the following section. See ″Stage Editors,″ for a general
description of the other tabs.

Reject links
You cannot change the properties of a Reject link. They have the meta data of the corresponding
incoming update link and this cannot be altered.

Chapter 15. Merge Stage 233

Mapping tab
For Merge stages the Mapping tab allows you to specify how the output columns are derived, i.e., what
input columns map onto them.

The left pane shows the columns of the merged data. These are read only and cannot be modified on this
tab. This shows the meta data from the master input link and any additional columns carried on the
update links.

The right pane shows the output columns for the master output link. This has a Derivations field where
you can specify how the column is derived. You can fill it in by dragging input columns over, or by
using the Auto-match facility.

In the above example the left pane represents the incoming data after the merge has been performed. The
right pane represents the data being output by the stage after the merge operation. In this example the
data has been mapped straight across.

234 Parallel Job Developer Guide

Chapter 16. Lookup Stage
The Lookup stage is a processing stage. It is used to perform lookup operations on a data set read into
memory from any other Parallel job stage that can output data. It can also perform lookups directly in a
DB2 or Oracle database (see Connectivity Guides for these two databases) or in a lookup table contained
in a Lookup File Set stage (see Chapter 7, “Lookup file set stage,” on page 121)

The most common use for a lookup is to map short codes in the input data set onto expanded
information from a lookup table which is then joined to the incoming data and output. For example, you
could have an input data set carrying names and addresses of your U.S. customers. The data as presented
identifies state as a two letter U. S. state postal code, but you want the data to carry the full name of the
state. You could define a lookup table that carries a list of codes matched to states, defining the code as
the key column. As the Lookup stage reads each line, it uses the key to look up the state in the lookup
table. It adds the state to a new column defined for the output link, and so the full state name is added
to each address. If any state codes have been incorrectly entered in the data set, the code will not be
found in the lookup table, and so that record will be rejected.

Lookups can also be used for validation of a row. If there is no corresponding entry in a lookup table to
the key’s values, the row is rejected.

The Lookup stage is one of three stages that join tables based on the values of key columns. The other
two are:
v Join stage - Chapter 14, “Join stage,” on page 219
v Merge stage - Chapter 15, “Merge Stage,” on page 227

The three stages differ mainly in the memory they use, the treatment of rows with unmatched keys, and
their requirements for data being input (for example, whether it is sorted). See ″Lookup Versus Join″ on
page Lookup Versus Join for help in deciding which stage to use.

The Lookup stage can have a reference link, a single input link, a single output link, and a single rejects
link. Depending upon the type and setting of the stage(s) providing the look up information, it can have
multiple reference links (where it is directly looking up a DB2 table or Oracle table, it can only have a
single reference link). A lot of the setting up of a lookup operation takes place on the stage providing the
lookup table.

The input link carries the data from the source data set and is known as the primary link. The following
pictures show some example jobs performing lookups.

For each record of the source data set from the primary link, the Lookup stage performs a table lookup
on each of the lookup tables attached by reference links. The table lookup is based on the values of a set
of lookup key columns, one set for each table. The keys are defined on the Lookup stage. For lookups of
data accessed through the Lookup File Set stage, the keys are specified when you create the look up file
set.

You can specify a condition on each of the reference links, such that the stage will only perform a lookup
on that reference link if the condition is satisfied.

Lookup stages do not require data on the input link or reference links to be sorted. Be aware, though,
that large in-memory lookup tables will degrade performance because of their paging requirements.

© Copyright IBM Corp. 2006 235

Each record of the output data set contains columns from a source record plus columns from all the
corresponding lookup records where corresponding source and lookup records have the same value for
the lookup key columns. The lookup key columns do not have to have the same names in the primary
and the reference links.

The optional reject link carries source records that do not have a corresponding entry in the input lookup
tables.

You can also perform a range lookup, which compares the value of a source column to a range of values
between two lookup table columns. If the source column value falls within the required range, a row is
passed to the output link. Alternatively, you can compare the value of a lookup column to a range of
values between two source columns. Range lookups must be based on column values, not constant
values. Multiple ranges are supported.

There are some special partitioning considerations for Lookup stages. You need to ensure that the data
being looked up in the lookup table is in the same partition as the input data referencing it. One way of
doing this is to partition the lookup tables using the Entire method. Another way is to partition it in the
same way as the input data (although this implies sorting of the data).

Unlike most of the other stages in a Parallel job, the Lookup stage has its own user interface. It does not
use the generic interface as described in Chapter 3, “Stage editors,” on page 37.

When you edit a Lookup stage, the Lookup Editor appears. An example Lookup stage is shown below.
The left pane represents input data and lookup data, and the right pane represents output data. In this
example, the Lookup stage has a primary link and single reference link, and a single output link. Meta
data has been defined for all links.

Lookup Versus Join

WebSphere DataStage doesn’t know how large your data is, so cannot make an informed choice whether
to combine data using a Join stage or a Lookup stage. Here’s how to decide which to use:

There are two data sets being combined. One is the primary or driving data set, sometimes called the left
of the join. The other data set(s) are the reference data sets, or the right of the join.

In all cases the size of the reference data sets is a concern. If these take up a large amount of memory
relative to the physical RAM memory size of the computer you are running on, then a Lookup stage
might thrash because the reference data sets might not fit in RAM along with everything else that has to
be in RAM. This results in very slow performance since each lookup operation can, and typically does,
cause a page fault and an I/O operation.

So, if the reference data sets are big enough to cause trouble, use a join. A join does a high-speed sort on
the driving and reference data sets. This can involve I/O if the data is big enough, but the I/O is all
highly optimized and sequential. After the sort is over, the join processing is very fast and never involves
paging or other I/O.

Example Look Up
This example shows what happens when data is looked up in a lookup table. The stage in this case will
look up the interest rate for each customer based on the account type. Here is the data that arrives on the
primary link:

Customer accountNo accountType balance

Latimer 7125678 plat 7890.76

236 Parallel Job Developer Guide

Ridley 7238892 flexi 234.88
Cranmer 7611236 gold 1288.00
Hooper 7176672 flexi 3456.99
Moore 7146789 gold 424.76

Here is the data in the lookup table:

accountType
InterestRate
bronze
1.25
silver 1.50
gold 1.75
plat 2.00
flexi 1.88
fixterm
3.00

Here is what the lookup stage will output:

Customer accountNo accountType balance InterestRate

Latimer 7125678 plat 7890.76 2.00
Ridley 7238892 flexi 234.88 1.88
Cranmer 7611236 gold 1288.00 1.75
Hooper 7176672 flexi 3456.99 1.88
Moore 7146789 gold 424.76 1.75

Here is a job that performs this simple lookup:

The accounts data set holds the details of customers and their account types, the interest rates are held in
an Oracle table. The lookup stage is set as follows:

All the columns in the accounts data set are mapped over to the output link. The AccountType column in
the accounts data set has been joined to the AccountType column of the interest_rates table. For each row,
the AccountType is looked up in the interest_rates table and the corresponding interest rate is returned.

The reference link has a condition on it. This detects if the balance is null in any of the rows of the
accounts data set. If the balance is null the row is sent to the rejects link (the rejects link does not appear
in the lookup editor because there is nothing you can change).

Must Do’s
WebSphere DataStage has many defaults which means that lookups can be simple to set up. This section
specifies the minimum steps to take to get a Lookup stage functioning. WebSphere DataStage provides a
versatile user interface, and there are many shortcuts to achieving a particular end, this section describes
the basic method, you will learn where the shortcuts are when you get familiar with the product.

Chapter 16. Lookup Stage 237

The exact steps you need to take when setting up a Lookup stage depend on what type of lookup table
you are looking up.

Using In-Memory Lookup tables

If you are accessing a lookup table read into memory from some other stage, you need to do the
following:

In the Data Input source stage:

v Specify details about the data source (for example, if using a File Set stage, give the name of the File
Set).
v Ensure required column meta data has been specified.
v Fulfil any ″must do’s″ for that particular stage editor.

In the stage providing the lookup table:

v Ensure required column meta data has been specified.
v Fulfil any ″must do’s″ for that particular stage editor.

In the Lookup stage:

v Map the required columns from your data input link to the output link (you can drag them or copy
and paste them).
v Map the required columns from your lookup table or tables to the output link (again you can drag
them or copy and paste them).
v Specify the key column or columns which are used for the lookup. Do this by dragging - or copying
and pasting - key columns from the data link to the Key Expression field in the lookup table link.
Note that key expressions can only be specified on key fields (i.e. columns that have the key field
selected in the column definitions). If you drag a column that is not currently defined as a key, you are
asked if you want to make it one. If you want the comparison performed on this column to ignore
case, then select the Caseless check box.

If you want to impose conditions on your lookup, or want to use a reject link, you need to double-click
on the Condition header of a reference link, choose Conditions from the link shortcut menu, or click the
Condition toolbar button. The Lookup Stage Conditions dialog box appears. This allows you to:
v Specify that one of the reference links is allowed to return multiple rows when performing a lookup
without causing an error (choose the relevant reference link from the Multiple rows returned from
link list).
v Specify a condition for the required references. Double-click the Condition box (or press CTRL-E) to
open the expression editor. This expression can access all the columns of the primary link, plus
columns in reference links that are processed before this link.
v Specify what happens if the condition is not met on each link.
v Specify what happens if a lookup fails on each link.

If you want to specify a range lookup, select the Range check box on the stream link or select Range
from the Key Type list on the reference link. Then double-click the Key Expression field to open the
Range dialog box, where you can build the range expression.

Next you need to open the Stage Properties dialog box for the Lookup stage. Do this by choosing the
Stage Properties icon from the stage editor toolbar, or by choosing Stage Properties or Link Properties
from the stage editor shortcut menu (choosing Link Properties will open the dialog box with the link you
are looking at selected, otherwise you might need to choose the correct link from the Input name or
Output name list).

238 Parallel Job Developer Guide

v In the Stage page Link Ordering Tab, check that your links are correctly identified as ″primary″ and
″lookup(s)″, and reorder if required (the links will be shown in the new order on the Lookup canvas).
v Unless you have particular partitioning requirements, leave the default auto setting on the Input Page
Partitioning Tab.

Using Oracle or DB2 Databases Directly

If you are doing a direct lookup in an Oracle or DB2 database table (known as `sparse’ mode), you need
to do the following:

In the Data Input source stage:

v Specify details about the data source (for example, if using a File Set stage, give the name of the File
Set).
v Ensure required column meta data has been specified (this can be done in another stage).
v Fulfil any ″must do’s″ for that particular stage editor.

In the Oracle or DB2/UDB Enterprise Stage:

v Set the Lookup Type to sparse. If you don’t do this the lookup will operate as an in-memory lookup.
v Specify required details for connecting to the database table.
v Ensure required column meta data has been specified (this can be omitted altogether if you are relying
on Runtime Column Propagation).

See the Connectivity Guides for these two databases for more details.

In the Lookup stage:

v Map the required columns from your data input link to the output link (you can drag them or copy
and paste them).
v Map the required columns from your lookup table or tables to the output link (again you can drag
them or copy and paste them).

If you want to impose conditions on your lookup, or want to use a reject link, you need to double-click
on the Condition header, choose Conditions from the link shortcut menu, or click the Condition toolbar
icon. The Lookup Stage Conditions dialog box appears. This allows you to:
v Specify what happens if a lookup fails on this link.

If you want to specify a range lookup, select the Range check box on the stream link or select Range
from the Key Type list on the reference link. Then double-click the Key Expression field to open the
Range dialog box, where you can build the range expression.

Next you need to open the Stage Properties dialog box for the Lookup stage. Do this by choosing the
Stage Properties icon from the stage editor toolbar, or by choosing Stage Properties or Link Properties
from the stage editor shortcut menu (choosing Link Properties will open the dialog box with the link you
are looking at selected, otherwise you might need to choose the correct link from the Input name or
Output name list).
v In the Stage page Link Ordering Tab, check that your links are correctly identified as ″primary″ and
″lookup(s)″, and reorder if required.
v Unless you have particular partitioning requirements, leave the default auto setting on the Input Page
Partitioning Tab.

Chapter 16. Lookup Stage 239

Using Lookup File Set
If you are accessing a lookup table held in a lookup file set that you have previously created using
WebSphere DataStage, you need to do the following:

In the Data Input source stage:

v Specify details about the data source (for example, if using a File Set stage, give the name of the file
set).
v Ensure required column meta data has been specified.
v Fulfil any ″must do’s″ for that particular stage editor.

In the Lookup File Set stage:

v Specify the name of the file set holding the lookup table.
v If you are performing a range lookup, specify the upper and lower bound columns (or the bounded
column if the lookup is reversed).
v Make sure that the key column or columns were specified when the file set holding the lookup table
was created.
v Ensure required column meta data has been specified.

See Chapter 7, “Lookup file set stage,” on page 121 for details about the Lookup File Set stage.

In the Lookup stage:

v Map the required columns from your data input link to the output link (you can drag them or copy
and paste them).
v Map the required columns from your lookup table or tables to the output link (again you can drag
them or copy and paste them).

As you are using a lookup file set this is all the mapping you need to do, the key column or columns for
the lookup is defined when you create the lookup file set.

If you are performing a range lookup, select the Range check box on the stream link or select Range from
the Key Type list on the reference link. Then double-click the Key Expression field to open the Range
dialog box, where you can build the range expression.

Next you need to open the Stage Properties dialog box for the Lookup stage. Do this by choosing the
Stage Properties icon from the stage editor toolbar, or by choosing Stage Properties or Link Properties
from the stage editor shortcut menu (choosing Link Properties will open the dialog with the link you are
looking at selected, otherwise you might need to choose the correct link from the Input name or Output
name list).
v In the Stage page Link Ordering Tab, check that your links are correctly identified as ″primary″ and
″lookup(s)″, and reorder if required.
v Unless you have particular partitioning requirements, leave the default auto setting on the Input Page
Partitioning Tab.

Lookup Editor Components

The Lookup Editor has the following components.

Toolbar
The Lookup toolbar contains the following buttons (from left to right):
v Stage properties

240 Parallel Job Developer Guide

v Constraints
v Show all
v Show/hide stage variables
v Cut
v Copy
v Paste
v Find/replace
v Load column definition
v Save column definition
v Column auto-match
v Input link execution order
v Output link execution order

Link Area
The top area displays links to and from the Lookup stage, showing their columns and the relationships
between them.

The link area is divided into two panes; you can drag the splitter bar between them to resize the panes
relative to one another. There is also a horizontal scroll bar, allowing you to scroll the view left or right.

The left pane shows the input link, the right pane shows output links. Output columns that have an
invalid derivation defined are shown in red. Reference link input key columns with invalid key
expressions are also shown in red.

Within the Lookup Editor, a single link can be selected at any one time. When selected, the link’s title bar
is highlighted, and arrowheads indicate any selected columns within that link.

Meta Data Area

The bottom area shows the column meta data for input and output links. Again this area is divided into
two panes: the left showing input link meta data and the right showing output link meta data.

The meta data for each link is shown in a grid contained within a tabbed page. Click the tab to bring the
required link to the front. That link is also selected in the link area.

If you select a link in the link area, its meta data tab is brought to the front automatically.

You can edit the grids to change the column meta data on any of the links. You can also add and delete
meta data.

As with column meta data grids on other stage editors, edit row in the context menu allows editing of
the full meta data definitions (see ″Columns Tab″ on page Columns Tab).

Shortcut Menus
The Lookup Editor shortcut menus are displayed by right-clicking the links in the links area.

There are slightly different menus, depending on whether you right-click an input link, or an output link.
The input link menu offers you operations on input columns, the output link menu offers you operations
on output columns and their derivations.

Chapter 16. Lookup Stage 241

The shortcut menu enables you to:
v Open the Stage Properties dialog box in order to specify stage or link properties.
v Open the Lookup Stage Conditions dialog box to specify a conditional lookup.
v Open the Column Auto Match dialog box.
v Display the Find/Replace dialog box.
v Display the Select dialog box.
v Validate, or clear a derivation.
v Append a new column to the selected link.
v Select all columns on a link.
v Insert or delete columns.
v Cut, copy, and paste a column or a key expression or a derivation.

Ifyou display the menu from the links area background, you can:
v Open the Stage Properties dialog box in order to specify stage or link properties.
v Open the Lookup Stage Conditions dialog box to specify a conditional lookup.
v Open the Link Execution Order dialog box in order to specify the order in which links should be
processed.
v Toggle between viewing link relations for all links, or for the selected link only.

Right-clicking in the meta data area of the Lookup Editor opens the standard grid editing shortcut
menus.

Editing Lookup Stages

The Lookup Editor enables you to perform the following operations on a Lookup stage:
v Create new columns on a link
v Delete columns from within a link
v Move columns within a link
v Edit column meta data
v Specify key expressions
v Map input columns to output columns

Using Drag and Drop

Many of the Lookup stage edits can be made simpler by using the Lookup Editor’s drag and drop
functionality. You can drag columns from any link to any other link. Common uses are:
v Copying input columns to output links
v Moving columns within a link
v Setting derivation or key expressions

To use drag and drop:

1. Click the source cell to select it.
2. Click the selected cell again and, without releasing the mouse button, drag the mouse pointer to the
desired location within the target link. An insert point appears on the target link to indicate where the
new cell will go. This can be to create a new column, or set a derivation. The exact action depends on
where you drop.
3. Release the mouse button to drop the selected cell.

242 Parallel Job Developer Guide

You can drag and drop multiple columns, key expressions, or derivations. Use the standard Explorer keys
when selecting the source column cells, then proceed as for a single cell.

You can drag and drop the full column set by dragging the link title.

Find and Replace Facilities

If you are working on a complex job where several links, each containing several columns, go in and out
of the Lookup stage, you can use the find/replace column facility to help locate a particular column or
expression and change it.

The find/replace facility enables you to:

v Find and replace a column name
v Find and replace expression text
v Find the next empty expression
v Find the next expression that contains an error

To use the find/replace facilities, do one of the following:

v Click the Find/Replace button on the toolbar
v Choose Find/Replace from the link shortcut menu
v Press Ctrl-F

The Find and Replace dialog box appears. It has three tabs:
v Expression Text. Allows you to locate the occurrence of a particular string within an expression, and
replace it if required. You can search up or down, and choose to match case, match whole words, or
neither. You can also choose to replace all occurrences of the string within an expression.
v Column Names. Allows you to find a particular column and rename it if required. You can search up
or down, and choose to match case, match the whole word, or neither.
v Expression Types. Allows you to find the next empty expression or the next expression that contains
an error. You can also press Ctrl-M to find the next empty expression or Ctrl-N to find the next
erroneous expression.

Note: The find and replace results are shown in the color specified in Tools → Options.

Press F3 to repeat the last search you made without opening the Find and Replace dialog box.

Select Facilities
If you are working on a complex job where several links, each containing several columns, go in and out
of the Lookup stage, you can use the select column facility to select multiple columns.

The select facility enables you to:

v Select all columns whose expressions contains text that matches the text specified.
v Select all columns whose name contains the text specified (and, optionally, matches a specified type).
v Select all columns with a certain data type.
v Select all columns with missing or invalid expressions.

To use the select facilities, choose Select from the link shortcut menu. The Select dialog box appears. It
has three tabs:
v Expression Text. The Expression Text tab allows you to select all columns/stage variables whose
expressions contain text that matches the text specified. The text specified is a simple text match, taking
into account the Match case setting.
Chapter 16. Lookup Stage 243
v Column Names. The Column Names tab allows you to select all column/stage variables whose Name
contains the text specified. There is an additional Data Type list, that will limit the columns selected to
those with that data type. You can use the Data Type list on its own to select all columns of a certain
data type. For example, all string columns can be selected by leaving the text field blank, and selecting
String as the data type. The data types in the list are generic data types, where each of the column SQL
data types belong to one of these generic types.
v Expression Types. The Expression Types tab allows you to select all columns with either empty
expressions or invalid expressions.

Creating and Deleting Columns

You can create columns on links to the Lookup stage using any of the following methods:
v Select the link, then click the Load Column Definition button in the toolbar to open the standard load
columns dialog box.
v Use drag and drop or copy and paste functionality to create a new column by copying from an
existing column on another link.
v Use the shortcut menus to create a new column definition.
v Edit the grids in the link’s meta data tab to insert a new column.

When copying columns, a new column is created with the same meta data as the column it was copied
from.

To delete a column from within the Lookup Editor, select the column you want to delete and click the cut
button or choose Delete Column from the shortcut menu.

Moving Columns Within a Link

You can move columns within a link using either drag and drop or cut and paste. Select the required
column, then drag it to its new location, or cut it and paste it in its new location.

Editing Column Meta Data

You can edit column meta data from within the grid in the bottom of the Lookup Editor. Select the tab
for the link meta data that you want to edit, then use the standard WebSphere DataStage edit grid
controls.

The meta data shown does not include column derivations since these are edited in the links area.

Defining Output Column Derivations

You can define the derivation of output columns from within the Lookup Editor in a number of ways:
v To map an input column (from data input or reference input) onto an output column you can use drag
and drop or copy and paste to copy an input column to an output link. The output columns will have
the same names as the input columns from which they were derived.
v If the output column already exists, you can drag or copy an input column to the output column’s
Derivation field. This specifies that the column is directly derived from an input column, with no
transformations performed.
v You can use the column auto-match facility to automatically set that output columns are derived from
their matching input columns.

If a derivation is displayed in red (or the color defined in Tools → Options), it means that the Lookup
Editor considers it incorrect. To see why it is invalid, choose Validate Derivation from the shortcut menu.

244 Parallel Job Developer Guide

After an output link column has a derivation defined that contains any input link columns, then a
relationship line is drawn between the input column and the output column. There can be one or more
relationship lines between columns. You can choose whether to view the relationships for all links, or just
the relationships for the selected links, using the button in the toolbar.

Column Auto-Match Facility

This time-saving feature allows you to automatically set columns on an output link to be derived from
matching columns on an input link. Using this feature you can fill in all the output link derivations to
route data from corresponding input columns, then go back and edit individual output link columns
where you want a different derivation.

To use this facility:

1. Do one of the following:
v Click the Auto-match button in the Lookup Editor toolbar.
v Choose Auto-match from the input link header or output link header shortcut menu.
TheColumn Auto-Match dialog box appears.
Choose the output link that you want to match columns with the input link from the list.
2. Click Location match or Name match from the Match type area.
If you choose Location match, this will set output column derivations to the input link columns in the
equivalent positions. It starts with the first input link column going to the first output link column,
and works its way down until there are no more input columns left.
3. Click OK to proceed with the auto-matching.

Note: Auto-matching does not take into account any data type incompatibility between matched
columns; the derivations are set regardless.

Defining Input Column Key Expressions

You can define key expressions for key fields of reference inputs. This is similar to defining derivations
for output columns.

The key expression is an equijoin from a primary input link column. You can specify it in two ways:
v Use drag and drop to drag a primary input link column to the appropriate key expression cell.
v Use copy and paste to copy a primary input link column and paste it on the appropriate key
expression cell.

A relationship link is drawn between the primary input link column and the key expression.

You can also use drag and drop or copy and paste to copy an existing key expression to another input
column, and you can drag or copy multiple selections.

If a key expression is displayed in red (or the color defined in Tools → Options), it means that the
Transformer Editor considers it incorrect. To see why it is invalid, choose Validate Derivation from the
shortcut menu.

Lookup Stage Properties

The Lookup stage has a Properties dialog box which allows you to specify details about how the stage
operates.

The Lookup Stage Properties dialog box has three pages:

v Stage Page. This is used to specify general information about the stage.

Chapter 16. Lookup Stage 245

v Input Page. This is where you specify details about the data input to the Transformer stage.
v Output Page. This is where you specify details about the output links from the Transformer stage.

Stage Page
The General tab allows you to specify an optional description of the stage. The Advanced tab allows you
to specify how the stage executes. The Link Ordering tab allows you to specify which order the input
links are processed in. The NLS Locale tab appears if your have NLS enabled on your system. It allows
you to select a locale other than the project default to determine collating rules. The Build tab allows you
to override the default compiler and linker flags for this particular stage.

Advanced Tab
This tab allows you to specify the following:
v Execution Mode. The stage can execute in parallel mode or sequential mode. In parallel mode the
input data is processed by the available nodes as specified in the Configuration file, and by any node
constraints specified on the Advanced tab. In Sequential mode the entire data set is processed by the
conductor node.
v Combinability mode. This is Auto by default, which allows WebSphere DataStage to combine the
operators that underlie parallel stages so that they run in the same process if it is sensible for this type
of stage.
v Preserve partitioning. This is Propagate by default. It adopts the setting of the previous stage on the
stream link. You can explicitly select Set or Clear. Select Set to request the next stage in the job should
attempt to maintain the partitioning.
v Node pool and resource constraints. Select this option to constrain parallel execution to the node pool
or pools and/or resource pool or pools specified in the grid. The grid allows you to make choices from
lists populated from the Configuration file.
v Node map constraint. Select this option to constrain parallel execution to the nodes in a defined node
map. You can define a node map by typing node numbers into the text box or by clicking the browse
button to open the Available Nodes dialog box and selecting nodes from there. You are effectively
defining a new node pool for this stage (in addition to any node pools defined in the Configuration
file).

Link Ordering Tab

This tab allows you to specify which input link is the primary link and the order in which the reference
links are processed.

By default the input links will be processed in the order they were added. To rearrange them, choose an
input link and click the up arrow button or the down arrow button.

You can also access this tab by clicking the input link order button in the toolbar, or by choosing Reorder
input links from the shortcut menu.

NLS Locale Tab

This appears if you have NLS enabled on your system. It lets you view the current default collate
convention, and select a different one for this stage if required. You can also use a job parameter to
specify the locale, or browse for a file that defines custom collate rules. The collate convention defines the
order in which characters are collated. The Lookup stage uses this when it is determining the order of the
key fields. Select a locale from the list, or click the arrow button next to the list to use a job parameter or
browse for a collate file.

246 Parallel Job Developer Guide

Build Tab
In some cases the Lookup stage may use C++ code to implement your lookup. In this case, you can use
the Build tab to override the compiler and linker flags that have been set for the job or project. The flags
you specify here will take effect for this stage and this stage alone. The flags available are platform and
compiler-dependent.

Input Page
The Input page allows you to specify details about the incoming data set and the reference links. Choose
a link from the Input name list to specify which link you want to work on.

The General tab allows you to specify an optional description of the link. When you are performing an
in-memory lookup, the General tab has two additional fields:
v Save to lookup fileset. Allows you to specify a lookup file set to save the look up data.
v Diskpool. Specify the name of the disk pool into which to write the file set. You can also specify a job
parameter.

The Partitioning tab allows you to specify how incoming data on the source data set link is partitioned.
The Advanced tab allows you to change the default buffering settings for the input link.

Details about Lookup stage partitioning are given in the following section. See Chapter 3, “Stage editors,”
on page 37 for a general description of the other tabs.

Partitioning Tab
The Partitioning tab allows you to specify details about how the incoming data is partitioned or collected
before the lookup is performed. It also allows you to specify that the data should be sorted before the
lookup. Note that you cannot specify partitioning or sorting on the reference links, this is specified in
their source stage.

By default the stage uses the auto partitioning method. If the Preserve Partitioning option has been set on
the previous stage in the job the stage will warn you when the job runs if it cannot preserve the
partitioning of the incoming data.

If the Lookup stage is operating in sequential mode, it will first collect the data before writing it to the
file using the default auto collection method.

The Partitioning tab allows you to override this default behavior. The exact operation of this tab depends
on:
v Whether the Lookup stage is set to execute in parallel or sequential mode.
v Whether the preceding stage in the job is set to execute in parallel or sequential mode.

If the Lookup stage is set to execute in parallel, then you can set a partitioning method by selecting from
the Partition type list. This will override any current partitioning.

You might need to ensure that your lookup tables have been partitioned using the Entire method, so that
the lookup tables will always contain the full set of data that might need to be looked up. For lookup
files and lookup tables being looked up in databases, the partitioning is performed on those stages.

If the Lookup stage is set to execute in sequential mode, but the preceding stage is executing in parallel,
then you can set a collection method from the Collector type list. This will override the default auto
collection method.

The following partitioning methods are available:

Chapter 16. Lookup Stage 247

v (Auto). WebSphere DataStage attempts to work out the best partitioning method depending on
execution modes of current and preceding stages and how many nodes are specified in the
Configuration file. This is the default method for the Lookup stage.
v Entire. Each file written to receives the entire data set.
v Hash. The records are hashed into partitions based on the value of a key column or columns selected
from the Available list.
v Modulus. The records are partitioned using a modulus function on the key column selected from the
Available list. This is commonly used to partition on tag fields.
v Random. The records are partitioned randomly, based on the output of a random number generator.
v Round Robin. The records are partitioned on a round robin basis as they enter the stage.
v Same. Preserves the partitioning already in place.
v DB2. Replicates the DB2 partitioning method of a specific DB2 table. Requires extra properties to be
set. Access these properties by clicking the properties button.
v Range. Divides a data set into approximately equal size partitions based on one or more partitioning
keys. Range partitioning is often a preprocessing step to performing a total sort on a data set. Requires
extra properties to be set. Access these properties by clicking the properties button.

The following Collection methods are available:

v (Auto). This is the default collection method for the Lookup stage. Normally, when you are using Auto
mode, WebSphere DataStage will eagerly read any row from any input partition as it becomes
available.
v Ordered. Reads all records from the first partition, then all records from the second partition, and so
on.
v Round Robin. Reads a record from the first input partition, then from the second partition, and so on.
After reaching the last partition, the operator starts over.
v Sort Merge. Reads records in an order based on one or more columns of the record. This requires you
to select a collecting key column from the Available list.

The Partitioning tab also allows you to specify that data arriving on the input link should be sorted
before the lookup is performed. The sort is always carried out within data partitions. If the stage is
partitioning incoming data, the sort occurs after the partitioning. If the stage is collecting data, the sort
occurs before the collection. The availability of sorting depends on the partitioning or collecting method
chosen (it is not available for the default auto methods).

Select the check boxes as follows:

v Perform Sort. Select this to specify that data coming in on the link should be sorted. Select the column
or columns to sort on from the Available list.
v Stable. Select this if you want to preserve previously sorted data sets. This is the default.
v Unique. Select this to specify that, if multiple records have identical sorting key values, only one
record is retained. If stable sort is also set, the first record is retained.

If NLS is enabled an additional button opens a dialog box allowing you to select a locale specifying the
collate convention for the sort.

You can also specify sort direction, case sensitivity, whether sorted as ASCII or EBCDIC, and whether null
columns will appear first or last for each column. Where you are using a keyed partitioning method, you
can also specify whether the column is used as a key for sorting, for partitioning, or for both. Select the
column in the Selected list and right-click to invoke the shortcut menu.

248 Parallel Job Developer Guide

Output Page
The Output page allows you to specify details about data output from the Lookup stage. The Lookup
stage can have only one output link. It can also have a single reject link, where records can be sent if the
lookup fails. The Output Link list allows you to choose whether you are looking at details of the main
output link (the stream link) or the reject link.

The General tab allows you to specify an optional description of the output link. The Advanced tab
allows you to change the default buffering settings for the output links.

Reject Links
You cannot set the mapping or edit the column definitions for a reject link. The link uses the column
definitions for the primary input link.

Lookup Stage Conditions

The Lookup stage has a Lookup Stage Conditions dialog box that allows you to specify:
v Which reference link (if any) can return multiple rows from a lookup.
v A condition that should be fulfilled before a lookup is performed on a reference link.
v What action should be taken if a condition on a reference link is not met.
v What action should be taken if a lookup on a link fails.

You can open the Lookup Stage Conditions dialog box by:
v Double-clicking the Condition: bar on a reference link.
v Selecting Conditions from the background shortcut menu.
v Clicking the Conditions toolbar button.
v Selecting Conditions from the link shortcut menu.

To specify that a link can legitimately return multiple rows:

v Select the link name from the Multiple rows returned from link list (note that only one reference link
in a Lookup stage is allowed to return multiple rows, and that this feature is only available for
in-memory lookups).

To specify a condition for a reference link:

v Double-click the Condition field for the link you want to specify a condition for. The field expands to
let you type in a condition, or click the browse button to open the expression editor to get help in
specifying an expression. The condition should return a TRUE/FALSE result (for example
DSLINK1.COL1 > 0).

To specify the action taken if the specified condition is not met:

v Choose an action from the Condition Not Met list. Possible actions are:
– Continue. The fields from that link are set to NULL if the field is nullable, or to a default value if
not. Continues processing any further lookups before sending the row to the output link.
– Drop. Drops the row and continues with the next lookup.
– Fail. Causes the job to issue a fatal error and stop.
– Reject. Sends the row to the reject link.

To specify the action taken if a lookup on a link fails:

v Choose an action from the Lookup Failure list. Possible actions are:
– Continue. The fields from that link are set to NULL if the field is nullable, or to a default value if
not. Continues processing any further lookups before sending the row to the output link.

Chapter 16. Lookup Stage 249

 – Drop. Drops the row and continues with the next lookup.
– Fail. Causes the job to issue a fatal error and stop.
– Reject. Sends the row to the reject link.

Range lookups
You can define a range lookup on the stream link or a reference link of a Lookup stage. On the stream
link, the lookup compares the value of a source column to a range of values between two lookup
columns. On the reference link, the lookup compares the value of a lookup column to a range of values
between two source columns. Multiple ranges are supported.

To define a range lookup:

1. Select the column for the lookup:
v To define the lookup on the stream link, select the Range check box next to the source column in
the links area.
v To define the lookup on a reference link, select the Key check box next to the reference column in
the meta data area. In the links area, select Range from the Key Type list.
2. Double-click the Key Expression field next to the selected column to open the Range dialog box.
3. Select a link from the Lookup Link list. (If you are defining the lookup on a reference link, the stream
link appears by default.)
4. Define the range expression by selecting the upper bound and lower bound range columns and the
required operators. For example:
Account_Detail.Trans_Date >= Customer_Detail.Start_Date AND
Account_Detail.Trans_Date <= Customer_Detail.End_Date
As you build the expression, it appears in the Expression box.
5. Select Caseless if you want the lookup to ignore case.
6. Click OK.

The WebSphere DataStage Expression Editor

The WebSphere DataStage Expression Editor helps you to enter correct expressions when you edit
Lookup stages. The Expression Editor can:
v Facilitate the entry of expression elements
v Complete the names of frequently used variables
v Validate the expression

The Expression Editor can be opened from:

v Lookup Stage Conditions dialog box

Expression Format
The format of an expression is as follows:
KEY:

something_like_this is a token
something_in_italics is a terminal, i.e., doesn’t break down any
further
| is a choice between tokens
[ is an optional part of the construction
"XXX" is a literal token (i.e., use XXX not
including the quotes)

250 Parallel Job Developer Guide

=================================================
expression ::= function_call |
variable_name |
other_name |
constant |
unary_expression |
binary_expression |
if_then_else_expression |
substring_expression |
"(" expression ")"

function_call ::= function_name "(" [argument_list] ")"

argument_list ::= expression | expression "," argument_list
function_name ::= name of a built-in function |
name of a user-defined_function
variable_name ::= job_parameter name
other_name ::= name of a built-in macro, system variable, etc.
constant ::= numeric_constant | string_constant
numeric_constant ::= ["+" | "-"] digits ["." [digits]] ["E" | "e" ["+" | "-"] digits]
string_constant ::= "’" [characters] "’" |
""" [characters] """ |
"\" [characters] "\"
unary_expression ::= unary_operator expression
unary_operator ::= "+" | "-"
binary_expression ::= expression binary_operator expression
binary_operator ::= arithmetic_operator |
concatenation_operator |
matches_operator |
relational_operator |
logical_operator
arithmetic_operator ::= "+" | "-" | "*" | "/" | "^"
concatenation_operator ::= ":"
relational_operator ::= " =" |"EQ" |
"<>" | "#" | "NE" |
">" | "GT" |
">=" | "=>" | "GE" |
"<" | "LT" |
"<=" | "=<" | "LE"
logical_operator ::= "AND" | "OR"
if_then_else_expression ::= "IF" expression "THEN" expression "ELSE" expression
substring_expression ::= expression "[" [expression ["," expression] "]"
field_expression ::= expression "[" expression ","
expression ","
expression "]"
/* That is, always 3 args
Note: keywords like "AND" or "IF" or "EQ" may be in any case

Entering Expressions
Whenever the insertion point is in an expression box, you can use the Expression Editor to suggest the
next element in your expression. Do this by right-clicking the box, or by clicking the Suggest button to
the right of the box. This opens the Suggest Operand or Suggest Operator menu. Which menu appears
depends on context, i.e., whether you should be entering an operand or an operator as the next
expression element. The Functions available from this menu are described in Appendix B. The DS macros
are described in WebSphere DataStage Parallel Job Advanced Developer Guide. You can also specify custom
routines for use in the expression editor (see WebSphere DataStage Designer Client Guide).

Completing Variable Names

The Expression Editor stores variable names. When you enter a variable name you have used before, you
can type the first few characters, then press F5. The Expression Editor completes the variable name for
you.

Chapter 16. Lookup Stage 251

If you enter the name of the input link followed by a period, for example, DailySales., the Expression
Editor displays a list of the column names of the link. If you continue typing, the list selection changes to
match what you type. You can also select a column name using the mouse. Enter a selected column name
into the expression by pressing Tab or Enter. Press Esc to dismiss the list without selecting a column
name.

Validating the Expression

When you have entered an expression in the Lookup Editor, press Enter to validate it. The Expression
Editor checks that the syntax is correct and that any variable names used are acceptable to the compiler.

If there is an error, a message appears and the element causing the error is highlighted in the expression
box. You can either correct the expression or close the Lookup Editor or Lookup dialog box.

For any expression, selecting Validate from its shortcut menu will also validate it and show any errors in
a message box.

Exiting the Expression Editor

You can exit the Expression Editor in the following ways:
v Press Esc (which discards changes).
v Press Return (which accepts changes).
v Click outside the Expression Editor box (which accepts changes).

Configuring the Expression Editor

You can resize the Expression Editor window by dragging. The next time you open the expression editor
in the same context (for example, editing output columns) on the same client, it will have the same size.

The Expression Editor is configured by editing the Designer options. This allows you to specify how
`helpful’ the expression editor is. For more information, see WebSphere DataStage Designer Client Guide.

252 Parallel Job Developer Guide

Chapter 17. Sort stage
The Sort stage is a processing stage. It is used to perform more complex sort operations than can be
provided for on the Input page Partitioning tab of parallel job stage editors. You can also use it to insert a
more explicit simple sort operation where you want to make your job easier to understand. The Sort
stage has a single input link which carries the data to be sorted, and a single output link carrying the
sorted data.

You specify sorting keys as the criteria on which to perform the sort. A key is a column on which to sort
the data, for example, if you had a name column you might specify that as the sort key to produce an
alphabetical list of names. The first column you specify as a key to the stage is the primary key, but you
can specify additional secondary keys. If multiple rows have the same value for the primary key column,
then WebSphere DataStage uses the secondary columns to sort these rows.

You can sort in sequential mode to sort an entire data set or in parallel mode to sort data within
partitions, as shown below:

© Copyright IBM Corp. 2006 253

 Tom Bill
Dick Bob
Harry Dave
Jack Sort Dick
Ted Stage Harry
Mary Jack
Bob Jane
Running
Jane Mary
sequentially
Monica Mike
Bill Monica
Dave Ted
Mike Tom

Tom Dick
Dick Harry
Harry Jack
Jack Tom

Sort
Bob
Ted Stage Jane
Mary
Mary
Bob
Tod
jane
Running
in parallel

Monica Bill
Bill Dave
Dave Mike
Mike Monica

The stage uses temporary disk space when performing a sort. It looks in the following locations, in the
following order, for this temporary space.
1. Scratch disks in the disk pool sort (you can create these pools in the configuration file).
2. Scratch disks in the default disk pool (scratch disks are included here by default).
3. The directory specified by the TMPDIR environment variable.
4. The directory /tmp.

You may perform a sort for several reasons. For example, you may want to sort a data set by a zip code
column, then by last name within the zip code. Once you have sorted the data set, you can filter the data
set by comparing adjacent records and removing any duplicates.

However, you must be careful when processing a sorted data set: many types of processing, such as
repartitioning, can destroy the sort order of the data. For example, assume you sort a data set on a
system with four processing nodes and store the results to a data set stage. The data set will therefore
have four partitions. You then use that data set as input to a stage executing on a different number of
nodes, possibly due to node constraints. WebSphere DataStage automatically repartitions a data set to
spread out the data set to all nodes in the system, unless you tell it not to, possibly destroying the sort

254 Parallel Job Developer Guide

order of the data. You could avoid this by specifying the Same partitioning method. The stage does not
perform any repartitioning as it reads the input data set; the original partitions are preserved.

You must also be careful when using a stage operating sequentially to process a sorted data set. A
sequential stage executes on a single processing node to perform its action. Sequential stages will collect
the data where the data set has more than one partition, which may also destroy the sorting order of its
input data set. You can overcome this if you specify the collection method as follows:
v If the data was range partitioned before being sorted, you should use the ordered collection method to
preserve the sort order of the data set. Using this collection method causes all the records from the first
partition of a data set to be read first, then all records from the second partition, and so on.
v If the data was hash partitioned before being sorted, you should use the sort merge collection method
specifying the same collection keys as the data was partitioned on.

Note: If you write a sorted data set to an RDBMS there is no guarantee that it will be read back in the
same order unless you specifically structure the SQL query to ensure this.

By default the stage will sort with the native WebSphere DataStage sorter, but you can also specify that it
uses the UNIX sort command.

The stage editor has three pages:

v Stage Page. This is always present and is used to specify general information about the stage.
v Input Page. This is where you specify details about the data sets being sorted.
v Output Page. This is where you specify details about the sorted data being output from the stage.

Examples

Sequential Sort
This job sorts the contents of a sequential file, and writes it to a data set. The data is a list of GlobalCo
customers sorted by customer number. We are going to sort it by customer name instead.

Here is a sample of the input data:

"ALDIS STORES","STAGE RD & APPLING RD","GC11199","GlobalCoUS"
"KINO COMMUNITY HOSPITAL URGENT","2800 E AJO WAY","GC11233","GlobalCoUS"
"INTL PAPER PLANT CITY FL","2104 HENDERSON WAY","GC11260","GlobalCoUS"
"HANK’S CLEANING SERVICE","PO BOX 4741","GC11326","GlobalCoUS"
"ADP INVESTOR COMMUNCATIONS SER","PO BOX 23487","GC11367","GlobalCoUS"
"FRANK H FURMAN INC","1314 E ATLANTIC BOULEVARD","GC11406","GlobalCoUS"
"DENNIS WEAVER POOL RENOVATION","23 E CALLE CONCORDIA","GC11441","GlobalCoUS"
"SAMCO STAMPING INC","15142 VISTA DEL RIO","GC11601","GlobalCoUS"
"BOSTON MARKET","1415 GOVENORS SQ BLVD","GC11647","GlobalCoUS"
"A-1 VACCUM SALES AND SERVICE","4523 FORSYTH RD","GC11697","GlobalCoUS"
"CMS NEW ELEMENTARY SCHOOL","7905 PLEASANT GROVE RD","GC11747","GlobalCoUS"
"HOLNAM PLANT","200 SAFETY STREET","GC11832","GlobalCoUS"
"PUBLIX @ WINTER SPRINGS TOWNE ","1160 E STATE ROAD 434","GC11930","GlobalCoUS"
"POTTER ROEMER","3100 SOUTH SUSAN ST","GC11977","GlobalCoUS"
"SAWYERS MILL SUBDIVISION","","GC12003","GlobalCoUS"
"REPUBLIC REFRIGERATION","2890 GRAY FOX RD","GC12048","GlobalCoUS"
"INTRAWEST SANDESTIN CO LLC","9300 HWY 98 W","GC12126","GlobalCoUS"
"ORO VALLEY LIBRARY","1305 W NARANJA DR","GC12175","GlobalCoUS"

The meta data for the file is as follows:

Table 7. Example metadata for writing to a sequential file
Column name Key SQL Type Length Nullable
CUSTOMER_NUMBER yes char 7 no

Chapter 17. Sort stage 255

Table 7. Example metadata for writing to a sequential file (continued)
Column name Key SQL Type Length Nullable
CUST_NAME varchar 30 no
ADDR_1 varchar 30 no
SOURCE char 10 no

The Sequential File stage runs sequentially because it only has one source file to read. The Sort stage is
set to run sequentially on the Stage page Advanced tab. The sort stage properties are used to specify the
column CUST_NAME as the primary sort key:

When the job is run the data is sorted into a single partition. The Data Set stage, GlobalCo_sorted, is set
to run sequentially to write the data to a single partition. Here is a sample of the sorted data:
"ATLANTIC SCIENTIFIC CORPORATIO","PO BOX 106023","GC27169","GlobalCoUS"
"ATLANTIC UNDERGROUND CONST","11192 60TH ST NORTH","GC23719","GlobalCoUS"
"ATLANTIC UNDERGROUND UTILITIES","203 EDSEL DR","GC23785","GlobalCoUS"
"ATLANTIC WATER CO","PO BOX 30806","GC23993","GlobalCoUS"
"ATLANTIS POOL & SPA","2323 NEPTUNE RD","GC23413","GlobalCoUS"
"ATLAS BOLT & SCREW COMPANY","PO BOX 96113","GC27196","GlobalCoUS"
"ATLAS ENGINEERING","PO BOX 140","GC23093","GlobalCoUS"
"ATLAS FOUNDATION REPAIR","2835 FAY ST","GC23110","GlobalCoUS"
"ATLAS REFRIGERATION & AC","1808 S ERVAY ST","GC23128","GlobalCoUS"
"ATLAS SCREW & SPECIALTY","PO BOX 41389","GC27225","GlobalCoUS"
"ATLAS UTILITY SUPPLY","2301 CARSON STREET","GC23182","GlobalCoUS"
"ATLAS UTILITY SUPPLY COMPANY","1206 PROCTOR ST","GC23200","GlobalCoUS"
"ATMEL Wireless and Microcontro","RÖSSLERSTRASSE 94 ","GC21356","GlobalCoDE"
"ATMOS ENERGY","PO BOX 9001949","GC23912","GlobalCoUS"
"ATNIP DESIGN & SUPPLY CENTER I","200 INDUSTRIAL DR","GC23215","GlobalCoUS"
"ATS","4901 E GRIMES","GC28576","GlobalCoUS"
"ATTALA WATER WORKS BD","509 4TH ST NW","GC23247","GlobalCoUS"
"ATTENTION HOME","","GC15998","GlobalCoUS"
"ATTN: C.L. MAR","","GC28189","GlobalCoUS"

256 Parallel Job Developer Guide

Parallel sort
This example uses the same job and the same data as the last previous example, but this time we are
going to run the Sort stage in parallel and create a number of partitions.

In the Sort stage we specify parallel execution in the Stage page Advanced tab. In the Input page
Partitioning tab we specify a partitioning type of Hash, and specify the column SOURCE as the hash key.
Because the partitioning takes place on the input link, the data is partitioned before the sort stage actually
tries to sort it. We hash partition to ensure that customers from the same country end up in the same
partition. The data is then sorted within those partitions.

The job is run on a four-node system, so we end up with a data set comprising four partitions.

The following is a sample of the data in partition 2 after partitioning, but before sorting:
"GTM construction ","Avenue De Lotz Et Cosse Ile Be","GC20115","GlobalCoFR"
"Laboratoires BOIRON ","14 Rue De La Ferme","GC20124","GlobalCoFR"
"Sofinco (Banque du Groupe Suez","113 Boulevard De Paris","GC20132","GlobalCoFR"
"Dingremont ","1 Avenue Charles Guillain","GC20140","GlobalCoFR"
"George Agenal - Tailleur de Pi","105 Rue La Fayette","GC20148","GlobalCoFR"
"Le Groupe Shell en France ","33-37 Rue Du Moulin Des Bruyèr","GC20156","GlobalCoFR"
"Bottin ","24 Rue Henri Barbusse","GC20165","GlobalCoFR"
"Crédit du Nord ","9 Rue Du Besly","GC20175","GlobalCoFR"
"LNET Multimedia ","4 Quai Du Point Du Jour","GC20184","GlobalCoFR"
"Merisel ","7 Allée Des Platanes","GC20192","GlobalCoFR"
"Groupe SEB ","100 Rue de Veeweyde","GC20200","GlobalCoFR"
"CSTB : Centre Scientifique et ","40 Rue Gabriel Crie","GC20208","GlobalCoFR"
"GTI-Informatique ","4 Avenue Montaigne","GC20219","GlobalCoFR"
"BIOTEC Biologie appliquée SA -","Chaussée Louise 143","GC20227","GlobalCoFR"
"Rank Xerox France ","4 Rue Jean-Pierre Timbaud","GC20236","GlobalCoFR"
"BHV : Bazar de l’Hotel de Vill","168 Bis Rue Cardinet","GC20246","GlobalCoFR"
"CerChimie ","Domaine De Voluceau","GC20254","GlobalCoFR"
"Renault S.A. [unofficial] ","11 Rue De Cambrai","GC20264","GlobalCoFR"
"Alcatel Communication","21-23 Rue D’Astorg","GC20272","GlobalCoFR"

And here is a sample of the data in partition 2 after it has been processed by the sort stage:
"Groupe BEC : Des entrepreneurs","91-95 Avenue François Arago","GC20900","GlobalCoFR"
"Groupe Courtaud ","2 Avenue Pierre Marzin","GC20692","GlobalCoFR"
"Groupe Courtaud ","99 Avenue Pierre Semard","GC20929","GlobalCoFR"
"Groupe FAYAT:Groupe Industriel","Allee Des Acacias","GC20020","GlobalCoFR"
"Groupe FAYAT:Groupe Industriel","Allee Des Acacias","GC20091","GlobalCoFR"

Chapter 17. Sort stage 257

"Groupe FAYAT:Groupe Industriel","5 Rue Du Marché","GC20554","GlobalCoFR"
"Groupe Finot, naval architects","33 Avenue Du Maine","GC20441","GlobalCoFR"
"Groupe Finot, naval architects","10 Avenue De Camberwell","GC20496","GlobalCoFR"
"Groupe Finot, naval architects","92 Avenue Du General De Gaulle","GC20776","GlobalCoFR"
"Groupe GAN ","41 Rue Camille Desmoulins","GC20253","GlobalCoFR"
"Groupe GAN ","1 Avenue Eugène Freyssinet","GC20212","GlobalCoFR"
"Groupe HELICE ","192 Avenue Charles De Gaulle","GC20437","GlobalCoFR"
"Groupe Heppner ","102 Rue De Richelieu","GC20411","GlobalCoFR"
"Groupe Heppner ","2 Chemin Gizy","GC20139","GlobalCoFR"
"Groupe Heppner ","2 Chemin Gizy","GC20035","GlobalCoFR"
"Groupe MD Concept ","74 Avenue Du Maine","GC20439","GlobalCoFR"

If we want to bring the data back together into a single partition, for example to write to another
sequential file, we need to be mindful of how it is collected, or we will lose the benefit of the sort. If we
use the sort/merge collection method, specifying the CUST_NAME column as the collection key, we will
end up with a totally sorted data set.

Total sort
You can also perform a total sort on a parallel data set, such that the data is ordered within each partition
and the partitions themselves are ordered. A total sort requires that all similar and duplicate records are
located in the same partition of the data set. Similarity is based on the key fields in a record. The
partitions also need to be approximately the same size so that no one node becomes a processing
bottleneck.

In order to meet these two requirements, the input data is partitioned using the range partitioner. This
guarantees that all records with the same key fields are in the same partition, and calculates the partition
boundaries based on the key field to ensure fairly even distribution. In order to use the range partitioner
you must first take a sample of your input data, sort it, then use it to build a range partition map as
described in Chapter 51, “Write Range Map stage,” on page 533, ″Write Range Map Stage.″ You then
specify this map when setting up the range partitioner in the Input page Partitioning tab of your Sort
stage.

258 Parallel Job Developer Guide

When you run the job it will produce a totally sorted data set across the four partitions.

Must do’s
WebSphere DataStage has many defaults which means that it can be very easy to include Sort stages in a
job. This section specifies the minimum steps to take to get a Sort stage functioning. WebSphere
DataStage provides a versatile user interface, and there are many shortcuts to achieving a particular end,
this section describes the basic method, you will learn where the shortcuts are when you get familiar
with the product.

To use a Sort stage:

v In the Stage page Properties Tab, under the Sorting Keys category:
– specify the key that you are sorting on. Repeat the property to specify a composite key.
v In the Output page Mapping Tab, specify how the output columns are derived.

Stage page
The General tab allows you to specify an optional description of the stage. The Properties tab lets you
specify what the stage does. The Advanced tab allows you to specify how the stage executes. The NLS
Locale tab appears if your have NLS enabled on your system. It allows you to select a locale other than
the project default to determine collating rules.

Properties tab
The Properties tab allows you to specify properties which determine what the stage actually does. Some
of the properties are mandatory, although many have default settings. Properties without default settings
appear in the warning color (red by default) and turn black when you supply a value for them.

The following table gives a quick reference list of the properties and their attributes. A more detailed
description of each property follows.

Category/
Property Values Default Mandatory? Repeats? Dependent of
Sorting Keys/Key Input Column N/A Y Y N/A

Chapter 17. Sort stage 259

Category/
Property Values Default Mandatory? Repeats? Dependent of
Sorting Keys/Sort Ascending/ Ascending Y N Key
Order Descending
Sorting First/Last First N N Key
Keys/Nulls
position (only
available for Sort
Utility =
DataStage)
Sorting Keys/Sort True/False False N N Key
as EBCDIC
Sorting True/False True N N Key
Keys/Case
Sensitive
Sorting Keys/Sort Sort/Don’t Sort Sort Y N Key
Key Mode (only (Previously
available for Sort Grouped)/Don’t
Utility = Sort (Previously
DataStage) Sorted)
Options/Sort DataStage/ UNIX DataStage Y N N/A
Utility
Options/Stable True/False True for Sort Y N N/A
Sort Utility =
DataStage, False
otherwise
Options/Allow True/False True Y N N/A
Duplicates (not
available for Sort
Utility = UNIX)
Options/Output True/False False Y N N/A
Statistics
Options/Create True/False False N N N/A
Cluster Key
Change Column
(only available for
Sort Utility =
DataStage)
Options/Create True/False False N N N/A
Key Change
Column
Options/Restrict number MB 20 N N N/A
Memory Usage
Options/ string N/A N N N/A
Workspace

Sorting keys category

Key

Specifies the key column for sorting. This property can be repeated to specify multiple key columns. You
can use the Column Selection dialog box to select several keys at once if required. Key has dependent
properties depending on the Sort Utility chosen:
v Sort Order

260 Parallel Job Developer Guide

 All sort types. Choose Ascending or Descending. The default is Ascending.
v Nulls position
This property appears for sort type DataStage and is optional. By default columns containing null
values appear first in the sorted data set. To override this default so that columns containing null
values appear last in the sorted data set, select Last.
v Sort as EBCDIC
To sort as in the EBCDIC character set, choose True.
v Case Sensitive
All sort types. This property is optional. Use this to specify whether each group key is case sensitive or
not, this is set to True by default, i.e., the values ″CASE″ and ″case″ would not be judged equivalent.
v Sort Key Mode
This property appears for sort type DataStage. It is set to Sort by default and this sorts on all the
specified key columns.
Set to Don’t Sort (Previously Sorted) to specify that input records are already sorted by this column.
The Sort stage will then sort on secondary key columns, if any. This option can increase the speed of
the sort and reduce the amount of temporary disk space when your records are already sorted by the
primary key column(s) because you only need to sort your data on the secondary key column(s).
Set to Don’t Sort (Previously Grouped) to specify that input records are already grouped by this
column, but not sorted. The operator will then sort on any secondary key columns. This option is
useful when your records are already grouped by the primary key column(s), but not necessarily
sorted, and you want to sort your data only on the secondary key column(s) within each group

Options category
Sort utility

The type of sort the stage will carry out. Choose from:
v DataStage. The default. This uses the built-in WebSphere DataStage sorter, you do not require any
additional software to use this option.
v UNIX. This specifies that the UNIX sort command is used to perform the sort.

Stable sort

Applies to a Sort Utility type of DataStage, the default is True. It is set to True to guarantee that this sort
operation will not rearrange records that are already in a properly sorted data set. If set to False no prior
ordering of records is guaranteed to be preserved by the sorting operation.

Allow duplicates

Set to True by default. If False, specifies that, if multiple records have identical sorting key values, only
one record is retained. If Stable Sort is True, then the first record is retained. This property is not available
for the UNIX sort type.

Output statistics

Set False by default. If True it causes the sort operation to output statistics. This property is not available
for the UNIX sort type.

Create cluster key change column

This property appears for sort type DataStage and is optional. It is set False by default. If set True it tells
the Sort stage to create the column clusterKeyChange in each output record. The clusterKeyChange
column is set to 1 for the first record in each group where groups are defined by using a Sort Key Mode

Chapter 17. Sort stage 261

of Don’t Sort (Previously Sorted) or Don’t Sort (Previously Grouped). Subsequent records in the group
have the clusterKeyChange column set to 0.

Create key change column

This property appears for sort type DataStage and is optional. It is set False by default. If set True it tells
the Sort stage to create the column KeyChange in each output record. The KeyChange column is set to 1
for the first record in each group where the value of the sort key changes. Subsequent records in the
group have the KeyChange column set to 0.

Restrict memory usage

This is set to 20 by default. It causes the Sort stage to restrict itself to the specified number of megabytes
of virtual memory on a processing node.

We recommend that the number of megabytes specified is smaller than the amount of physical memory
on a processing node.

Workspace

This property appears for sort type UNIX only. Optionally specifies the workspace used by the stage.

Advanced tab
This tab allows you to specify the following:
v Execution Mode. The stage can execute in parallel mode or sequential mode. In parallel mode the
input data is processed by the available nodes as specified in the Configuration file, and by any node
constraints specified on the Advanced tab. In Sequential mode the entire data set is processed by the
conductor node.
v Preserve partitioning. This is Set by default. You can explicitly select Set or Clear. Select Set to request
the next stage in the job should attempt to maintain the partitioning.
v Combinability mode. This is Auto by default, which allows WebSphere DataStage to combine the
operators that underlie parallel stages so that they run in the same process if it is sensible for this type
of stage.
v Node pool and resource constraints. Select this option to constrain parallel execution to the node pool
or pools and/or resource pool or pools specified in the grid. The grid allows you to make choices from
drop down lists populated from the Configuration file.
v Node map constraint. Select this option to constrain parallel execution to the nodes in a defined node
map. You can define a node map by typing node numbers into the text box or by clicking the browse
button to open the Available Nodes dialog box and selecting nodes from there. You are effectively
defining a new node pool for this stage (in addition to any node pools defined in the Configuration
file).

NLS Locale tab

This appears if you have NLS enabled on your system. If you are using the DataStage sort type, it lets
you view the current default collate convention, and select a different one for this stage if required (for
UNIX sorts, it is blank). You can also use a job parameter to specify the locale, or browse for a file that
defines custom collate rules. The collate convention defines the order in which characters are collated.
The Sort stage uses this when it is determining the order of the sorted fields. Select a locale from the list,
or click the arrow button next to the list to use a job parameter or browse for a collate file.

262 Parallel Job Developer Guide

Input page
The input page allows you to specify details about the data coming in to be sorted. The Sort stage can
have only one input link.

The General tab allows you to specify an optional description of the link. The Partitioning tab allows you
to specify how incoming data on the source data set link is partitioned. The Columns tab specifies the
column definitions of incoming data. The Advanced tab allows you to change the default buffering
settings for the input link.

Details about Sort stage partitioning are given in the following section. See ″Stage Editors,″ for a general
description of the other tabs.

Partitioning tab
The Partitioning tab allows you to specify details about how the incoming data is partitioned or collected
before the sort is performed.

By default the stage uses the auto partitioning method. If the Preserve Partitioning option has been set on
the previous stage in the job the stage will warn you when the job runs if it cannot preserve the
partitioning of the incoming data.

If the Sort Set stage is operating in sequential mode, it will first collect the data before writing it to the
file using the default auto collection method.

The Partitioning tab allows you to override this default behavior. The exact operation of this tab depends
on:
v Whether the Sort stage is set to execute in parallel or sequential mode.
v Whether the preceding stage in the job is set to execute in parallel or sequential mode.

If the Sort stage is set to execute in parallel, then you can set a partitioning method by selecting from the
Partition type drop-down list. This will override any current partitioning.

If the Sort stage is set to execute in sequential mode, but the preceding stage is executing in parallel, then
you can set a collection method from the Collector type drop-down list. This will override the default
auto collection method.

The following partitioning methods are available:

v (Auto). WebSphere DataStage attempts to work out the best partitioning method depending on
execution modes of current and preceding stages and how many nodes are specified in the
Configuration file. This is the default method for the Sort stage.
v Entire. Each file written to receives the entire data set.
v Hash. The records are hashed into partitions based on the value of a key column or columns selected
from the Available list.
v Modulus. The records are partitioned using a modulus function on the key column selected from the
Available list. This is commonly used to partition on tag fields.
v Random. The records are partitioned randomly, based on the output of a random number generator.
v Round Robin. The records are partitioned on a round robin basis as they enter the stage.
v Same. Preserves the partitioning already in place.
v DB2. Replicates the DB2 partitioning method of a specific DB2 table. Requires extra properties to be
set. Access these properties by clicking the properties button.

Chapter 17. Sort stage 263

v Range. Divides a data set into approximately equal size partitions based on one or more partitioning
keys. Range partitioning is often a preprocessing step to performing a total sort on a data set. Requires
extra properties to be set. Access these properties by clicking the properties button.

The following Collection methods are available:

v (Auto). This is the default collection method for the Sort stage. Normally, when you are using Auto
mode, WebSphere DataStage will eagerly read any row from any input partition as it becomes
available.
v Ordered. Reads all records from the first partition, then all records from the second partition, and so
on.
v Round Robin. Reads a record from the first input partition, then from the second partition, and so on.
After reaching the last partition, the operator starts over.
v Sort Merge. Reads records in an order based on one or more columns of the record. This requires you
to select a collecting key column from the Available list.

The Partitioning tab also allows you to specify that data arriving on the input link should be sorted
before the Sort is performed. This is a standard feature of the stage editors, if you make use of it you will
be running a simple sort before the main Sort operation that the stage provides. The sort is always
carried out within data partitions. If the stage is partitioning incoming data the sort occurs after the
partitioning. If the stage is collecting data, the sort occurs before the collection. The availability of sorting
depends on the partitioning or collecting method chosen (it is not available with the default auto
methods).

Select the check boxes as follows:

v Perform Sort. Select this to specify that data coming in on the link should be sorted. Select the column
or columns to sort on from the Available list.
v Stable. Select this if you want to preserve previously sorted data sets. This is the default.
v Unique. Select this to specify that, if multiple records have identical sorting key values, only one
record is retained. If stable sort is also set, the first record is retained.

If NLS is enabled an additional button opens a dialog box allowing you to select a locale specifying the
collate convention for the sort.

You can also specify sort direction, case sensitivity, whether sorted as ASCII or EBCDIC, and whether null
columns will appear first or last for each column. Where you are using a keyed partitioning method, you
can also specify whether the column is used as a key for sorting, for partitioning, or for both. Select the
column in the Selected list and right-click to invoke the shortcut menu.

Output page
The Output page allows you to specify details about data output from the Sort stage. The Sort stage can
have only one output link.

The General tab allows you to specify an optional description of the output link. The Columns tab
specifies the column definitions of the data. The Mapping tab allows you to specify the relationship
between the columns being input to the Sort stage and the Output columns. The Advanced tab allows
you to change the default buffering settings for the output link.

Details about Sort stage mapping is given in the following section. See ″Stage Editors,″ for a general
description of the other tabs.

264 Parallel Job Developer Guide

Mapping tab
For Sort stages the Mapping tab allows you to specify how the output columns are derived, i.e., what
input columns map onto them.

The left pane shows the columns of the sorted data. These are read only and cannot be modified on this
tab. This shows the meta data from the input link.

The right pane shows the output columns for the output link. This has a Derivations field where you can
specify how the column is derived. You can fill it in by dragging input columns over, or by using the
Auto-match facility.

In the above example the left pane represents the incoming data after the sort has been performed. The
right pane represents the data being output by the stage after the sort operation. In this example the data
has been mapped straight across.

Chapter 17. Sort stage 265

266 Parallel Job Developer Guide
Chapter 18. Funnel Stage
The Funnel stage is a processing stage. It copies multiple input data sets to a single output data set. This
operation is useful for combining separate data sets into a single large data set. The stage can have any
number of input links and a single output link.

The Funnel stage can operate in one of three modes:

v Continuous Funnel combines the records of the input data in no guaranteed order. It takes one record
from each input link in turn. If data is not available on an input link, the stage skips to the next link
rather than waiting.
v Sort Funnel combines the input records in the order defined by the value(s) of one or more key
columns and the order of the output records is determined by these sorting keys.
v Sequence copies all records from the first input data set to the output data set, then all the records
from the second input data set, and so on.

For all methods the meta data of all input data sets must be identical.

The sort funnel method has some particular requirements about its input data. All input data sets must
be sorted by the same key columns as to be used by the Funnel operation.

Typically all input data sets for a sort funnel operation are hash-partitioned before they’re sorted
(choosing the auto partitioning method will ensure that this is done). Hash partitioning guarantees that
all records with the same key column values are located in the same partition and so are processed on
the same node. If sorting and partitioning are carried out on separate stages before the Funnel stage, this
partitioning must be preserved.

© Copyright IBM Corp. 2006 267

The sortfunnel operation allows you to set one primary key and multiple secondary keys. The Funnel stage
first examines the primary key in each input record. For multiple records with the same primary key
value, it then examines secondary keys to determine the order of records it will output.

The stage editor has three pages:

v Stage Page. This is always present and is used to specify general information about the stage.
v Input Page. This is where you specify details about the data sets being joined.
v Output Page. This is where you specify details about the joined data being output from the stage.

Examples

Continuous funnel example

Our example data comprises four separate data sets. Each data set contains a list of GlobalCo customers
from a particular country. Here is a sample of the data for the US customers:
"JEREMY BUEHM","","GC13849","GlobalCoUS"
"3M","2807 PAYSPHERE CIRCLE","GC13933","GlobalCoUS"
"FOXWOOD APARTMENT","1701 HAMILTON AVE","GC14036","GlobalCoUS"
"PITNEY WORKS","PO BOX 85042","GC14127","GlobalCoUS"
"BRENDA GRIGG","HSI MCKINNEY WATER & SEWER #77","GC14263","GlobalCoUS"
"ROZAK EXCAVATING & CONST INC","PO BOX 710","GC14346","GlobalCoUS"
"MACEDONIA BAPTIST CHURCH","4656 PAGE RD","GC14428","GlobalCoUS"
"WORSHAM SPRINKLER **BAD DEBT**","3931-C GARWOOD AVE","GC14497","GlobalCoUS"
"WORSHAM SPRINKLER***BAD DEBT**","119 SLATE STONE DR","GC14572","GlobalCoUS"
"BINGLEMAN RESIDENCE","248 SPRINGLINE DRIVE","GC14653","GlobalCoUS"
"MOON EXCAVATING","3895 TAMPA RD.","GC14728","GlobalCoUS"
"TROPICANA NORTH AMERICA","6500 GLADES CUT OFF RD","GC14801","GlobalCoUS"
"ELECTRICAL SPECIALISTS CASH","PO BOX 2649","GC14874","GlobalCoUS"
"SEARS ROEBUCK & CO","100 GREENSPOINT MALL","GC14927","GlobalCoUS"
"MALL @ MILLENIA (#10289)","SE COR-MILLENIA BLVD & CONROY ","GC15005","GlobalCoUS"
"DIVISION ST-GORE TO WASHINGTON","DIVISION ST BETWEEN GORE & WAS","GC15094","GlobalCoUS"
"PEACHTREE LANDING APTS","LL27 9TH DIST","GC15180","GlobalCoUS"
"SW BELL TELEPHONE","PO BOX 4699","GC15248","GlobalCoUS"

The Funnel stage, when set to continuous funnel, will combine these into a single data set. The job to
perform the funnel is as follows:

268 Parallel Job Developer Guide

The continuous funnel method is selected on the Stage page Properties tab of the Funnel stage:

The continuous funnel method does not attempt to impose any order on the data it is processing. It
simply writes rows as they become available on the input links. In our example the stage has written a
row from each input link in turn. A sample of the final, funneled, data is as follows:
"VALUE TOOL REPAIR","4345 OKEECHOBEE BLVD STE F2","GC17697","GlobalCoUS"
"CHAPPEL HILL WSC MAIN STREET","PO BOX 215","GC17712","GlobalCoUS"
"ROBERT WILLIAMS","3615","GC17728","GlobalCoUS"
"USC TICKET OFFICE","REX ENRIGHT CENTER","GC17742","GlobalCoUS"
"STASCO INC","PO BOX 3087","GC17760","GlobalCoUS"
"VASCO BRANDS INC","PO BOX 4040","GC17786","GlobalCoUS"
"ROYAL ST WW IMPROVEMENTS*DO NO","4103 RIVER OAKS DR","GC17798","GlobalCoUS"
"KAY ROSE INC **CASH SALES**","PO BOX 617","GC17808","GlobalCoUS"
"Novatec sa","Bp 28","GC20002","GlobalCoFR"
"Casio - Esselte ","Route De Nozay","GC20012","GlobalCoFR"
"Citélis ","137 Rue Voltaire","GC20021","GlobalCoFR"
"DECATHLON ","3 Rue De La Nouvelle France","GC20032","GlobalCoFR"
"BNP : Banque Nationale de Pari","Sdap","GC20040","GlobalCoFR"
",Acton - Visserie Boulonnerie","Domaine De Voluceau","GC20049","GlobalCoFR"
"SKF France ","5 Rue Noël Pons","GC20059","GlobalCoFR"
"Admiral ","2 Rue Auguste Comte","GC20067","GlobalCoFR"
"Borland ","1 Avenue Newton","GC20076","GlobalCoFR"

Sort Funnel Example

In this example we are going to use the funnel stage to sort the GlobalCo data by customer number as it
combines the data into a single data set. The data and the basic job are the same as for the Continuous
Funnel example, but now we set the Funnel stage properties as follows:

Chapter 18. Funnel Stage 269

The following is a sample of the output data set:
Argia ","Bp 60","GC20912","GlobalCoFR"
"Carrefour ","5-7 Rue Du Centre","GC20916","GlobalCoFR"
"Haladjian ","19 Rue De Téhéran","GC20923","GlobalCoFR"
"ORTEC France SA. ","137 Rue De L’Université","GC20927","GlobalCoFR"
"SAPRR ","20 Avenue Georges Pompidou","GC20933","GlobalCoFR"
"Bic France ","8 Cours Olivier De Clisson","GC20959","GlobalCoFR"
"Sibille industrie ","2 Rue Auguste Comte","GC20960","GlobalCoFR"
"CNRS : Centre National de la R","28 Rue Cambacérès","GC20964","GlobalCoFR"
"INSEE : Institut National des ","198 Avenue De Verdun","GC20968","GlobalCoFR"
"MATRAnet ","14-16 Boulevard De Douaumont ","GC20970","GlobalCoFR"
"Imprimerie Roux ","41 Rue Camille Desmoulins","GC20974","GlobalCoFR"
"Paber Aluminium ","6 Avenue Des Usines","GC20980","GlobalCoFR"
"Larousse ","17 Rue De La Boëtie","GC20984","GlobalCoFR"
"Geoservices ","24 Avenue Du Petit Parc","GC20988","GlobalCoFR"
"Crédit du Nord ","7-9 Rue Hélène Boucher","GC20990","GlobalCoFR"
"soprate ","Keltenring 12","GC20994","GlobalCoFR"
"Lamy ","Chemin De La Brétèque","GC20998","GlobalCoFR"
"CARL SCHLÖSSER GmbH & Co. KG "," ","GC21002","GlobalCoDE"
"WEVO-CHEMIE HEINZ WEZEL GMBH &","OBERGASSE 85 ","GC21006","GlobalCoDE"
"BEFRAG ","Siemensstr. 7-9 ","GC21012","GlobalCoDE"
"STORZ AUTOMATION ","SERVICE REUTER GMBH ","GC21023","GlobalCoDE"

Note: If you are running your sort funnel stage in parallel, you should be aware of the various
considerations about sorting data and partitions. These are described in ″Sort Stage.″

Sequence funnel example

In this example we funnel the GlobalCo data on input one data set at a time. We end up with a data set
that contains all the US customers, then all the UK ones, then all the French ones and so on. Again the
basic job and the source data are the same as for the continuous funnel example. The Funnel type
property is set to Sequence on the Properties tab.

When using the sequence method, you need to specify the order in which the Funnel stage processes its
input links, as this affects the order of the sequencing. This is done on the Stage page Link Ordering tab.

270 Parallel Job Developer Guide

If you run the sequence funnel stage in parallel, you need to be mindful of the effects of data
partitioning. If, for example, you ran our example job on a four-node system, you would get four
partions each containing a section of US data, a section of UKdata, a section of FR data and so on.

Must do’s
WebSphere DataStage has many defaults which means that it can be very easy to include Funnel stages
in a job. This section specifies the minimum steps to take to get a Funnel stage functioning. WebSphere
DataStage provides a versatile user interface, and there are many shortcuts to achieving a particular end,
this section describes the basic method, you will learn where the shortcuts are when you get familiar
with the product.

To use a Funnel stage:

v In the Stage page Properties Tab, specify the Funnel Type. Continuous Funnel is the default, but you
can also choose Sequence or Sort Funnel.
If you choose to use the Sort Funnel method, you also need to specify the key on which data will be
sorted. You can repeat the key property to specify a composite key.
v If you are using the Sequence method, in the Stage page Link Ordering Tab specify the order in which
your data sets will be combined.
v In the Output page Mapping Tab, specify how the output columns are derived.

Stage page
The General tab allows you to specify an optional description of the stage. The Properties tab lets you
specify what the stage does. The Advanced tab allows you to specify how the stage executes. The Link
Ordering tab allows you to specify which order the input links are processed in. The NLS Locale tab
appears if your have NLS enabled on your system. It allows you to select a locale other than the project
default to determine collating rules.

Properties tab
The Properties tab allows you to specify properties which determine what the stage actually does. Some
of the properties are mandatory, although many have default settings. Properties without default settings
appear in the warning color (red by default) and turn black when you supply a value for them.

The following table gives a quick reference list of the properties and their attributes. A more detailed
description of each property follows.

Category/
Property Values Default Mandatory? Repeats? Dependent of
Options/Funnel Continuous Continuous Y N N/A
Type Funnel/ Funnel
Sequence/ Sort
funnel
Sorting Keys/Key Input Column N/A Y (if Funnel Type Y N/A
= Sort Funnel)
Sorting Keys/Sort Ascending/ Ascending Y (if Funnel Type N Key
Order Descending = Sort Funnel)
Sorting First/Last First Y (if Funnel Type N Key
Keys/Nulls = Sort Funnel)
position

Chapter 18. Funnel Stage 271

Category/
Property Values Default Mandatory? Repeats? Dependent of
Sorting True/False True N N Key
Keys/Case
Sensitive
Sorting Keys/Sort True/False False N N Key
as EBCDIC

Options category
Funnel type

Specifies the type of Funnel operation. Choose from:

v Continuous Funnel
v Sequence
v Sort Funnel

The default is Continuous Funnel.

Sorting keys category

Key

This property is only required for Sort Funnel operations. Specify the key column that the sort will be
carried out on. The first column you specify is the primary key, you can add multiple secondary keys by
repeating the key property. You can use the Column Selection dialog box to select several keys at once if
required.

Key has the following dependent properties:

v Sort Order
Choose Ascending or Descending. The default is Ascending.
v Nulls position
By default columns containing null values appear first in the funneled data set. To override this default
so that columns containing null values appear last in the funneled data set, select Last.
v Sort as EBCDIC
To sort as in the EBCDIC character set, choose True.
v Case Sensitive
Use this to specify whether each key is case sensitive or not, this is set to True by default, i.e., the
values ″CASE″ and ″case″ would not be judged equivalent.

Advanced tab
This tab allows you to specify the following:
v Execution Mode. The stage can execute in parallel mode or sequential mode. In parallel mode the
input data is processed by the available nodes as specified in the Configuration file, and by any node
constraints specified on the Advanced tab. In Sequential mode the entire data set is processed by the
conductor node.
v Combinability mode. This is Auto by default, which allows WebSphere DataStage to combine the
operators that underlie parallel stages so that they run in the same process if it is sensible for this type
of stage.

272 Parallel Job Developer Guide

v Preserve partitioning. This is Propagate by default. It adopts the setting which results from ORing the
settings of the input stages, i.e., if any of the input stages uses Set then this stage will use Set. You can
explicitly select Set or Clear. Select Set to request that the next stage in the job attempts to maintain
the partitioning.
v Node pool and resource constraints. Select this option to constrain parallel execution to the node pool
or pools and/or resource pool or pools specified in the grid. The grid allows you to make choices from
drop down lists populated from the Configuration file.
v Node map constraint. Select this option to constrain parallel execution to the nodes in a defined node
map. You can define a node map by typing node numbers into the text box or by clicking the browse
button to open the Available Nodes dialog box and selecting nodes from there. You are effectively
defining a new node pool for this stage (in addition to any node pools defined in the Configuration
file).

Link Ordering tab

This tab allows you to specify the order in which links input to the Funnel stage are processed. This is
only relevant if you have chosen the Sequence Funnel Type.

By default the input links will be processed in the order they were added. To rearrange them, choose an
input link and click the up arrow button or the down arrow button.

NLS Locale tab

This appears if you have NLS enabled on your system. If you are using the Sort Funnel funnel type, it
lets you view the current default collate convention, and select a different one for this stage if required
(for other funnel types, it is blank). You can also use a job parameter to specify the locale, or browse for a
file that defines custom collate rules. The collate convention defines the order in which characters are
collated. The Funnel stage uses this when it is determining the sort order for sort funnel. Select a locale
from the list, or click the arrow button next to the list to use a job parameter or browse for a collate file.

Input page
The Input page allows you to specify details about the incoming data sets. Choose an input link from the
Input name drop down list to specify which link you want to work on.

The General tab allows you to specify an optional description of the input link. The Partitioning tab
allows you to specify how incoming data is partitioned before being funneled. The Columns tab specifies
the column definitions of incoming data. The Advanced tab allows you to change the default buffering
settings for the input link.

Details about Funnel stage partitioning are given in the following section. See ″Stage Editors,″ for a
general description of the other tabs.

Partitioning on input links

The Partitioning tab allows you to specify details about how the data on each of the incoming links is
partitioned or collected before it is funneled. It also allows you to specify that the data should be sorted
before being operated on.

By default the stage partitions in Auto mode. This attempts to work out the best partitioning method
depending on execution modes of current and preceding stages and how many nodes are specified in the
Configuration file.

Chapter 18. Funnel Stage 273

If the Funnel stage is operating in sequential mode, it will first collect the data before writing it to the file
using the default Auto collection method.

The Partitioning tab allows you to override this default behavior. The exact operation of this tab depends
on:
v Whether the Funnel stage is set to execute in parallel or sequential mode.
v Whether the preceding stage in the job is set to execute in parallel or sequential mode.

If the Funnel stage is set to execute in parallel, then you can set a partitioning method by selecting from
the Partition type drop-down list. This will override any current partitioning.

If you are using the Sort Funnel method, and haven’t partitioned the data in a previous stage, you should
key partition it by choosing the Hash or modulus partition method on this tab.

If the Funnel stage is set to execute in sequential mode, but the preceding stage is executing in parallel,
then you can set a collection method from the Collector type drop-down list. This will override the
default collection method.

The following partitioning methods are available:

v (Auto). WebSphere DataStage attempts to work out the best partitioning method depending on
execution modes of current and preceding stages and how many nodes are specified in the
Configuration file. This is the default partitioning method for the Funnel stage.
v Entire. Each file written to receives the entire data set.
v Hash. The records are hashed into partitions based on the value of a key column or columns selected
from the Available list.
v Modulus. The records are partitioned using a modulus function on the key column selected from the
Available list. This is commonly used to partition on tag fields.
v Random. The records are partitioned randomly, based on the output of a random number generator.
v Round Robin. The records are partitioned on a round robin basis as they enter the stage.
v Same. Preserves the partitioning already in place.
v DB2. Replicates the DB2 partitioning method of a specific DB2 table. Requires extra properties to be
set. Access these properties by clicking the properties button.
v Range. Divides a data set into approximately equal size partitions based on one or more partitioning
keys. Range partitioning is often a preprocessing step to performing a total sort on a data set. Requires
extra properties to be set. Access these properties by clicking the properties button.

The following Collection methods are available:

v (Auto). This is the default collection method for Funnel stages. Normally, when you are using Auto
mode, WebSphere DataStage will eagerly read any row from any input partition as it becomes
available.
v Ordered. Reads all records from the first partition, then all records from the second partition, and so
on.
v Round Robin. Reads a record from the first input partition, then from the second partition, and so on.
After reaching the last partition, the operator starts over.
v Sort Merge. Reads records in an order based on one or more columns of the record. This requires you
to select a collecting key column from the Available list.

The Partitioning tab also allows you to specify that data arriving on the input link should be sorted
before being funneled. The sort is always carried out within data partitions. If the stage is partitioning
incoming data the sort occurs after the partitioning. If the stage is collecting data, the sort occurs before
the collection.

274 Parallel Job Developer Guide

If you are using the Sort Funnel method, and haven’t sorted the data in a previous stage, you should sort
it here using the same keys that the data is hash partitioned on and funneled on. The availability of
sorting depends on the partitioning or collecting method chosen (it is not available for the default auto
methods).

Select the check boxes as follows:

v Perform Sort. Select this to specify that data coming in on the link should be sorted. Select the column
or columns to sort on from the Available list.
v Stable. Select this if you want to preserve previously sorted data sets. This is the default.
v Unique. Select this to specify that, if multiple records have identical sorting key values, only one
record is retained. If stable sort is also set, the first record is retained.

If NLS is enabled an additional button opens a dialog box allowing you to select a locale specifying the
collate convention for the sort.

You can also specify sort direction, case sensitivity, whether sorted as ASCII or EBCDIC, and whether null
columns will appear first or last for each column. Where you are using a keyed partitioning method, you
can also specify whether the column is used as a key for sorting, for partitioning, or for both. Select the
column in the Selected list and right-click to invoke the shortcut menu.

Output page
The Output page allows you to specify details about data output from the Funnel stage. The Funnel stage
can have only one output link.

The General tab allows you to specify an optional description of the output link. The Columns tab
specifies the column definitions of the data. The Mapping tab allows you to specify the relationship
between the columns being input to the Funnel stage and the Output columns. The Advanced tab allows
you to change the default buffering settings for the output link.

Details about Funnel stage mapping is given in the following section. See ″Stage Editors,″ for a general
description of the other tabs.

Mapping tab
For Funnel stages the Mapping tab allows you to specify how the output columns are derived, i.e., what
input columns map onto them or how they are generated.

The left pane shows the input columns. These are read only and cannot be modified on this tab. It is a
requirement of the Funnel stage that all input links have identical meta data, so only one set of column
definitions is shown.

The right pane shows the output columns for each link. This has a Derivations field where you can
specify how the column is derived. You can fill it in by dragging input columns over, or by using the
Auto-match facility.

Chapter 18. Funnel Stage 275

276 Parallel Job Developer Guide
Chapter 19. Remove Duplicates Stage
The Remove Duplicates stage is a processing stage. It can have a single input link and a single output
link.

The Remove Duplicates stage takes a single sorted data set as input, removes all duplicate rows, and
writes the results to an output data set.

Removing duplicate records is a common way of cleansing a data set before you perform further
processing. Two rows are considered duplicates if they are adjacent in the input data set and have
identical values for the key column(s). A key column is any column you designate to be used in
determining whether two rows are identical.

The data set input to the Remove Duplicates stage must be sorted so that all records with identical key
values are adjacent. You can either achieve this using the in-stage sort facilities available on the Input
page Partitioning tab, or have an explicit Sort stage feeding the Remove Duplicates stage.

The stage editor has three pages:

v Stage Page. This is always present and is used to specify general information about the stage.
v Input Page. This is where you specify details about the data set that is having its duplicates removed.
v Output Page. This is where you specify details about the processed data that is being output from the
stage.

Example
In the example the data is a list of GlobalCo’s customers. The data contains some duplicate entries, and
we want to remove these.

The first step is to sort the data so that the duplicates are actually next to each other. As with all sorting
operations, there are implications around data partitions if you run the job in parallel (see ″Copy Stage,″
for a discussion of these). You should hash partition the data using the sort keys as hash keys in order to
guarantee that duplicate rows are in the same partition. In our example we sort on the
CUSTOMER_NUMBER columns and our sample of the sorted data shows up some duplicates:
"GC29834","AQUILUS CONDOS","917 N FIRST ST","8/29/1996 "
"GC29835","MINERAL COUNTRY","2991 TELLER CT","8/29/1996 "
"GC29836","ABC WATERWORKS","PO BOX 14093","8/30/1996 "
"GC29837","ANGEL BROTHERS INC","128 SOUTH MAIN ST","8/30/1996 "
"GC29837","ANGEL BROTHERS INC","128 SOUTH MAIN ST","8/30/1996 "
"GC29838","ENCNG WASHINGTON","1305 JOHN SMALL AV","8/30/1996 "
"GC29839","DYNEGY FACILITIES","1000 LOUISIANA STE 5800","8/30/1996 "
"GC29840","LITTLE HAITI GATEWAY","NE 2ND AVENUE AND NE 62ND STRE","8/30/1996 "

© Copyright IBM Corp. 2006 277

Next, we set up the Remove Duplicates stage to remove rows that share the same values in the
CUSTOMER_NUMBER column. The stage will retain the first of the duplicate records:

Here is a sample of the data after the job has been run and the duplicates removed:
"GC29834","AQUILUS CONDOS","917 N FIRST ST","8/29/1996 "
"GC29835","MINERAL COUNTRY","2991 TELLER CT","8/29/1996 "
"GC29836","ABC WATERWORKS","PO BOX 14093","8/30/1996 "
"GC29837","ANGEL BROTHERS INC","128 SOUTH MAIN ST","8/30/1996 "
"GC29838","ENCNG WASHINGTON","1305 JOHN SMALL AV","8/30/1996 "
"GC29839","DYNEGY FACILITIES","1000 LOUISIANA STE 5800","8/30/1996 "
"GC29840","LITTLE HAITI GATEWAY","NE 2ND AVENUE AND NE 62ND STRE","8/30/1996 "

Must do’s
WebSphere DataStage has many defaults which means that it can be very easy to include Remove
Duplicates stages in a job. This section specifies the minimum steps to take to get a Remove Duplicates
stage functioning. WebSphere DataStage provides a versatile user interface, and there are many shortcuts
to achieving a particular end, this section describes the basic method, you will learn where the shortcuts
are when you get familiar with the product.

To use a Remove Duplicates stage:

v In the Stage page Properties Tab select the key column. Identical values in this column will be taken to
denote duplicate rows, which the stage will remove. Repeat the property to specify a composite key.
v In the Output Page Mapping Tab, specify how output columns are derived.

Stage page
The General tab allows you to specify an optional description of the stage. The Properties tab lets you
specify what the stage does. The Advanced tab allows you to specify how the stage executes. The NLS
Locale tab appears if your have NLS enabled on your system. It allows you to select a locale other than
the project default to determine collating rules.

278 Parallel Job Developer Guide

Properties tab
The Properties tab allows you to specify properties which determine what the stage actually does. Some
of the properties are mandatory, although many have default settings. Properties without default settings
appear in the warning color (red by default) and turn black when you supply a value for them.

The following table gives a quick reference list of the properties and their attributes. A more detailed
description of each property follows.

Category/
Property Values Default Mandatory? Repeats? Dependent of
Keys that Define Input Column N/A Y Y N/A
Duplicates/Key
Keys that Define True/False False N N Key
Duplicates/Sort
as EBCDIC
Keys that Define True/False True N N Key
Duplicates/Case
Sensitive
Options/ First/Last First Y N N/A
Duplicate to
retain

Keys that define duplicates category

Key

Specifies the key column for the operation. This property can be repeated to specify multiple key
columns. You can use the Column Selection dialog box to select several keys at once if required. Key has
dependent properties as follows:
v Sort as EBCDIC
To sort as in the EBCDIC character set, choose True.
v Case Sensitive
Use this to specify whether each key is case sensitive or not, this is set to True by default, i.e., the
values ″CASE″ and ″case″ would not be judged equivalent.

Options category
Duplicate to retain

Specifies which of the duplicate columns encountered to retain. Choose between First and Last. It is set to
First by default.

Advanced tab
This tab allows you to specify the following:
v Execution Mode. The stage can execute in parallel mode or sequential mode. In parallel mode the
input data is processed by the available nodes as specified in the Configuration file, and by any node
constraints specified on the Advanced tab. In Sequential mode the entire data set is processed by the
conductor node.
v Combinability mode. This is Auto by default, which allows WebSphere DataStage to combine the
operators that underlie parallel stages so that they run in the same process if it is sensible for this type
of stage.

Chapter 19. Remove Duplicates Stage 279

v Preserve partitioning. This is Propagate by default. It adopts Set or Clear from the previous stage. You
can explicitly select Set or Clear. Select Set to request that next stage in the job should attempt to
maintain the partitioning.
v Node pool and resource constraints. Select this option to constrain parallel execution to the node pool
or pools and/or resource pool or pools specified in the grid. The grid allows you to make choices from
drop down lists populated from the Configuration file.
v Node map constraint. Select this option to constrain parallel execution to the nodes in a defined node
map. You can define a node map by typing node numbers into the text box or by clicking the browse
button to open the Available Nodes dialog box and selecting nodes from there. You are effectively
defining a new node pool for this stage (in addition to any node pools defined in the Configuration
file).

NLS Locale tab

This appears if you have NLS enabled on your system. It lets you view the current default collate
convention, and select a different one for this stage if required. You can also use a job parameter to
specify the locale, or browse for a file that defines custom collate rules. The collate convention defines the
order in which characters are collated. The Remove Duplicates stage uses this when it is determining the
sort order for the key column(s). Select a locale from the list, or click the arrow button next to the list to
use a job parameter or browse for a collate file.

Input page
The Input page allows you to specify details about the data coming in to be sorted. Choose an input link
from the Input name drop down list to specify which link you want to work on.

The General tab allows you to specify an optional description of the link. The Partitioning tab allows you
to specify how incoming data on the source data set link is partitioned. The Columns tab specifies the
column definitions of incoming data. The Advanced tab allows you to change the default buffering
settings for the input link.

Details about Remove Duplicates stage partitioning are given in the following section. See ″Stage
Editors,″ for a general description of the other tabs.

Partitioning on input links

The Partitioning tab allows you to specify details about how the incoming data is partitioned or collected
before the operation is performed.

By default the stage uses the auto partitioning method.

If the Remove Duplicates stage is operating in sequential mode, it will first collect the data before writing
it to the file using the default auto collection method.

The Partitioning tab allows you to override this default behavior. The exact operation of this tab depends
on:
v Whether the Remove Duplicates stage is set to execute in parallel or sequential mode.
v Whether the preceding stage in the job is set to execute in parallel or sequential mode.

If the Remove Duplicates stage is set to execute in parallel, then you can set a partitioning method by
selecting from the Partition type drop-down list. This will override any current partitioning.

If the Remove Duplicates stage is set to execute in sequential mode, but the preceding stage is executing
in parallel, then you can set a collection method from the Collector type drop-down list. This will
override the default auto collection method.

280 Parallel Job Developer Guide

The following partitioning methods are available:
v (Auto). WebSphere DataStage attempts to work out the best partitioning method depending on
execution modes of current and preceding stages and how many nodes are specified in the
Configuration file. This is the default method for the Remove Duplicates stage.
v Entire. Each file written to receives the entire data set.
v Hash. The records are hashed into partitions based on the value of a key column or columns selected
from the Available list.
v Modulus. The records are partitioned using a modulus function on the key column selected from the
Available list. This is commonly used to partition on tag fields.
v Random. The records are partitioned randomly, based on the output of a random number generator.
v Round Robin. The records are partitioned on a round robin basis as they enter the stage.
v Same. Preserves the partitioning already in place.
v DB2. Replicates the DB2 partitioning method of a specific DB2 table. Requires extra properties to be
set. Access these properties by clicking the properties button.
v Range. Divides a data set into approximately equal size partitions based on one or more partitioning
keys. Range partitioning is often a preprocessing step to performing a total sort on a data set. Requires
extra properties to be set. Access these properties by clicking the properties button.

The following Collection methods are available:

v (Auto). This is the default collection method for the Remove Duplicates stage. Normally, when you are
using Auto mode, WebSphere DataStage will eagerly read any row from any input partition as it
becomes available.
v Ordered. Reads all records from the first partition, then all records from the second partition, and so
on.
v Round Robin. Reads a record from the first input partition, then from the second partition, and so on.
After reaching the last partition, the operator starts over.
v Sort Merge. Reads records in an order based on one or more columns of the record. This requires you
to select a collecting key column from the Available list.

The Partitioning tab also allows you to specify that data arriving on the input link should be sorted
before the remove duplicates operation is performed. The sort is always carried out within data
partitions. If the stage is partitioning incoming data the sort occurs after the partitioning. If the stage is
collecting data, the sort occurs before the collection. The availability of sorting depends on the
partitioning or collecting method chosen (it is not available with the default auto methods).

Select the check boxes as follows:

v Perform Sort. Select this to specify that data coming in on the link should be sorted. Select the column
or columns to sort on from the Available list.
v Stable. Select this if you want to preserve previously sorted data sets. This is the default.
v Unique. Select this to specify that, if multiple records have identical sorting key values, only one
record is retained. If stable sort is also set, the first record is retained.

If NLS is enabled an additional button opens a dialog box allowing you to select a locale specifying the
collate convention for the sort.

You can also specify sort direction, case sensitivity, whether sorted as ASCII or EBCDIC, and whether null
columns will appear first or last for each column. Where you are using a keyed partitioning method, you
can also specify whether the column is used as a key for sorting, for partitioning, or for both. Select the
column in the Selected list and right-click to invoke the shortcut menu.

Chapter 19. Remove Duplicates Stage 281

Output page
The Output page allows you to specify details about data output from the Remove Duplicates stage. The
stage only has one output link.

The General tab allows you to specify an optional description of the output link. The Columns tab
specifies the column definitions of the data. The Mapping tab allows you to specify the relationship
between the columns being input to the Remove Duplicates stage and the output columns. The Advanced
tab allows you to change the default buffering settings for the output link.

Details about Remove Duplicates stage mapping is given in the following section. See ″Stage Editors,″ for
a general description of the other tabs.

Mapping tab
For Remove Duplicates stages the Mapping tab allows you to specify how the output columns are
derived, i.e., what input columns map onto them.

The left pane shows the columns of the input data. These are read only and cannot be modified on this
tab. This shows the meta data from the incoming link.

The right pane shows the output columns for the master output link. This has a Derivations field where
you can specify how the column is derived. You can fill it in by dragging input columns over, or by
using the Auto-match facility.

282 Parallel Job Developer Guide

Chapter 20. Compress stage
The Compress stage is a processing stage. It can have a single input link and a single output link.

The Compress stage uses the UNIX compress or GZIP utility to compress a data set. It converts a data set
from a sequence of records into a stream of raw binary data. The complement to the Compress stage is
the Expand stage, which is described in Chapter 21, “Expand Stage,” on page 287.

A compressed data set is similar to an ordinary data set and can be stored in a persistent form by a Data
Set stage. However, a compressed data set cannot be processed by many stages until it is expanded, that
is, until its rows are returned to their normal format. Stages that do not perform column-based processing
or reorder the rows can operate on compressed data sets. For example, you can use the Copy stage to
create a copy of the compressed data set.

Because compressing a data set removes its normal record boundaries, the compressed data set must not
be repartitioned before it is expanded.

DataStage puts the existing data set schema as a subrecord to a generic compressed schema. For example,
given a data set with a schema of:
a:int32;
b:string[50];

The schema for the compressed data set would be:

record
( t: tagged {preservePartitioning=no}
( encoded: subrec
( bufferNumber: dfloat;
bufferLength: int32;
bufferData: raw[32000];
);
schema: subrec
( a: int32;
b: string[50];
);

Therefore, when you are looking to reuse a file that has been compressed, ensure that you use the
’compressed schema’ to read the file rather than the schema that had gone into the compression.

The stage editor has three pages:

v Stage Page. This is always present and is used to specify general information about the stage.
v Input Page. This is where you specify details about the data set being compressed.
v Output Page. This is where you specify details about the compressed data being output from the stage.

© Copyright IBM Corp. 2006 283

Must do’s
WebSphere DataStage has many defaults which means that it can be very easy to include Compress
stages in a job. This section specifies the minimum steps to take to get a Compress stage functioning.
WebSphere DataStage provides a versatile user interface, and there are many shortcuts to achieving a
particular end, this section describes the basic method, you will learn where the shortcuts are when you
get familiar with the product.

To use a Compress stage:

v In the Stage page Properties Tab choose the compress command to use. Compress is the default but
you can also choose gzip.
v Ensure column meta data is defined for both the input and output link.

Stage page
The General tab allows you to specify an optional description of the stage. The Properties tab lets you
specify what the stage does. The Advanced tab allows you to specify how the stage executes.

Properties tab
The Properties tab allows you to specify properties which determine what the stage actually does. The
stage only has a single property which determines whether the stage uses compress or GZIP.

Category/
Property Values Default Mandatory? Repeats? Dependent of
Options/ compress/gzip compress Y N N/A
Command

Options category
Command

Specifies whether the stage will use compress (the default) or GZIP.

Advanced tab
This tab allows you to specify the following:
v Execution Mode. The stage can execute in parallel mode or sequential mode. In parallel mode the
input data is processed by the available nodes as specified in the Configuration file, and by any node
constraints specified on the Advanced tab. In Sequential mode the entire data set is processed by the
conductor node.
v Combinability mode. This is Auto by default, which allows WebSphere DataStage to combine the
operators that underlie parallel stages so that they run in the same process if it is sensible for this type
of stage.
v Preserve partitioning. This is Set by default. You can explicitly select Set or Clear. Select Set to request
the next stage should attempt to maintain the partitioning.
v Node pool and resource constraints. Select this option to constrain parallel execution to the node pool
or pools and/or resource pool or pools specified in the grid. The grid allows you to make choices from
drop down lists populated from the Configuration file.
v Node map constraint. Select this option to constrain parallel execution to the nodes in a defined node
map. You can define a node map by typing node numbers into the text box or by clicking the browse

284 Parallel Job Developer Guide

 button to open the Available Nodes dialog box and selecting nodes from there. You are effectively
defining a new node pool for this stage (in addition to any node pools defined in the Configuration
file).

Input page
The Input page allows you to specify details about the data set being compressed. There is only one
input link.

The General tab allows you to specify an optional description of the link. The Partitioning tab allows you
to specify how incoming data on the source data set link is partitioned. The Columns tab specifies the
column definitions of incoming data. The Advanced tab allows you to change the default buffering
settings for the input link.

Details about Compress stage partitioning are given in the following section. See ″Stage Editors,″ for a
general description of the other tabs.

Partitioning on input links

The Partitioning tab allows you to specify details about how the incoming data is partitioned or collected
before the compress is performed.

By default the stage uses the auto partitioning method.

If the Compress stage is operating in sequential mode, it will first collect the data before writing it to the
file using the default auto collection method.

The Partitioning tab allows you to override this default behavior. The exact operation of this tab depends
on:
v Whether the Compress stage is set to execute in parallel or sequential mode.
v Whether the preceding stage in the job is set to execute in parallel or sequential mode.

If the Compress stage is set to execute in parallel, then you can set a partitioning method by selecting
from the Partition type drop-down list. This will override any current partitioning.

If the Compress stage is set to execute in sequential mode, but the preceding stage is executing in
parallel, then you can set a collection method from the Collector type drop-down list. This will override
the default auto collection method.

The following partitioning methods are available:

v (Auto). WebSphere DataStage attempts to work out the best partitioning method depending on
execution modes of current and preceding stages and how many nodes are specified in the
Configuration file. This is the default method for the Compress stage.
v Entire. Each file written to receives the entire data set.
v Hash. The records are hashed into partitions based on the value of a key column or columns selected
from the Available list.
v Modulus. The records are partitioned using a modulus function on the key column selected from the
Available list. This is commonly used to partition on tag fields.
v Random. The records are partitioned randomly, based on the output of a random number generator.
v Round Robin. The records are partitioned on a round robin basis as they enter the stage.
v Same. Preserves the partitioning already in place.
v DB2. Replicates the DB2 partitioning method of a specific DB2 table. Requires extra properties to be
set. Access these properties by clicking the properties button.

Chapter 20. Compress stage 285

v Range. Divides a data set into approximately equal size partitions based on one or more partitioning
keys. Range partitioning is often a preprocessing step to performing a total sort on a data set. Requires
extra properties to be set. Access these properties by clicking the properties button.

The following Collection methods are available:

v (Auto). This is the default collection method for the Compress stage. Normally, when you are using
Auto mode, WebSphere DataStage will eagerly read any row from any input partition as it becomes
available.
v Ordered. Reads all records from the first partition, then all records from the second partition, and so
on.
v Round Robin. Reads a record from the first input partition, then from the second partition, and so on.
After reaching the last partition, the operator starts over.
v Sort Merge. Reads records in an order based on one or more columns of the record. This requires you
to select a collecting key column from the Available list.

The Partitioning tab also allows you to specify that data arriving on the input link should be sorted
before the compression is performed. The sort is always carried out within data partitions. If the stage is
partitioning incoming data the sort occurs after the partitioning. If the stage is collecting data, the sort
occurs before the collection. The availability of sorting depends on the partitioning or collecting method
chosen (it is not available for the default auto methods).

Select the check boxes as follows:

v Perform Sort. Select this to specify that data coming in on the link should be sorted. Select the column
or columns to sort on from the Available list.
v Stable. Select this if you want to preserve previously sorted data sets. This is the default.
v Unique. Select this to specify that, if multiple records have identical sorting key values, only one
record is retained. If stable sort is also set, the first record is retained.

If NLS is enabled an additional button opens a dialog box allowing you to select a locale specifying the
collate convention for the sort.

You can also specify sort direction, case sensitivity, whether sorted as ASCII or EBCDIC, and whether null
columns will appear first or last for each column. Where you are using a keyed partitioning method, you
can also specify whether the column is used as a key for sorting, for partitioning, or for both. Select the
column in the Selected list and right-click to invoke the shortcut menu.

Output page
The Output page allows you to specify details about data output from the Compress stage. The stage
only has one output link.

The General tab allows you to specify an optional description of the output link. The Columns tab
specifies the column definitions of the data. The Advanced tab allows you to change the default buffering
settings for the output link.

See ″Stage Editors,″ for a general description of the tabs.

286 Parallel Job Developer Guide

Chapter 21. Expand Stage
The Expand stage is a processing stage. It can have a single input link and a single output link.

The Expand stage uses the UNIX uncompress or GZIP utility to expand a data set. It converts a previously
compressed data set back into a sequence of records from a stream of raw binary data. The complement
to the Expand stage is the Compress stage which is described in Chapter 20, “Compress stage,” on page
283.

The stage editor has three pages:

v Stage Page. This is always present and is used to specify general information about the stage.
v Input Page. This is where you specify details about the data set being expanded.
v Output Page. This is where you specify details about the expanded data being output from the stage.

Must do’s
WebSphere DataStage has many defaults which means that it can be very easy to include Expand stages
in a job. This section specifies the minimum steps to take to get an Expand stage functioning. WebSphere
DataStage provides a versatile user interface, and there are many shortcuts to achieving a particular end,
this section describes the basic method, you will learn where the shortcuts are when you get familiar
with the product.

To use an Expand stage:

v In the Stage page Properties Tab choose the uncompress command to use. This is uncompress by
default but you can also choose gzip.
v Ensure column meta data is defined for both the input and output link.

Stage page
The General tab allows you to specify an optional description of the stage. The Properties tab lets you
specify what the stage does. The Advanced tab allows you to specify how the stage executes.

Properties tab
The Properties tab allows you to specify properties which determine what the stage actually does. The
stage only has a single property which determines whether the stage uses uncompress or GZIP.

© Copyright IBM Corp. 2006 287

Category/
Property Values Default Mandatory? Repeats? Dependent of
Options/ uncompress/gzip compress Y N N/A
Command

Options category
Command

Specifies whether the stage will use uncompress (the default) or GZIP.

Advanced tab
This tab allows you to specify the following:
v Execution Mode. The stage can execute in parallel mode or sequential mode. In parallel mode the
input data is processed by the available nodes as specified in the Configuration file, and by any node
constraints specified on the Advanced tab. In Sequential mode the entire data set is processed by the
conductor node.
v Combinability mode. This is Auto by default, which allows WebSphere DataStage to combine the
operators that underlie parallel stages so that they run in the same process if it is sensible for this type
of stage.
v Preserve partitioning. This is Propagate by default. The stage has a mandatory partitioning method of
Same, this overrides the preserve partitioning flag and so the partitioning of the incoming data is
always preserved.
v Node pool and resource constraints. Select this option to constrain parallel execution to the node pool
or pools and/or resource pool or pools specified in the grid. The grid allows you to make choices from
drop down lists populated from the Configuration file.
v Node map constraint. Select this option to constrain parallel execution to the nodes in a defined node
map. You can define a node map by typing node numbers into the text box or by clicking the browse
button to open the Available Nodes dialog box and selecting nodes from there. You are effectively
defining a new node pool for this stage (in addition to any node pools defined in the Configuration
file).

Input page
The Input page allows you to specify details about the data set being expanded. There is only one input
link.

The General tab allows you to specify an optional description of the link. The Partitioning tab allows you
to specify how incoming data on the source data set link is partitioned. The Columns tab specifies the
column definitions of incoming data. The Advanced tab allows you to change the default buffering
settings for the input link.

Details about Expand stage partitioning are given in the following section. See ″Stage Editors,″ for a
general description of the other tabs.

Partitioning on input Llinks

The Partitioning tab allows you to specify details about how the incoming data is partitioned or collected
before the expansion is performed.

By default the stage uses the Same partitioning method and this cannot be altered. This preserves the
partitioning already in place.

288 Parallel Job Developer Guide

If the Expand stage is set to execute in sequential mode, but the preceding stage is executing in parallel,
then you can set a collection method from the Collector type drop-down list. This will override the
default auto collection method.

The following Collection methods are available:

v (Auto). This is the default collection method for the Expand stage. Normally, when you are using Auto
mode, WebSphere DataStage will eagerly read any row from any input partition as it becomes
available.
v Ordered. Reads all records from the first partition, then all records from the second partition, and so
on.
v Round Robin. Reads a record from the first input partition, then from the second partition, and so on.
After reaching the last partition, the operator starts over.
v Sort Merge. Reads records in an order based on one or more columns of the record. This requires you
to select a collecting key column from the Available list.

The Partitioning tab normally also allows you to specify that data arriving on the input link should be
sorted before the expansion is performed. This facility is not available on the expand stage.

Output page
The Output page allows you to specify details about data output from the Expand stage. The stage only
has one output link.

The General tab allows you to specify an optional description of the output link. The Columns tab
specifies the column definitions of the data. The Advanced tab allows you to change the default buffering
settings for the output link.

See ″Stage Editors,″ for a general description of the tabs.

Chapter 21. Expand Stage 289

290 Parallel Job Developer Guide
Chapter 22. Copy stage
The Copy stage is a processing stage. It can have a single input link and any number of output links.

The Copy stage copies a single input data set to a number of output data sets. Each record of the input
data set is copied to every output data set. Records can be copied without modification or you can drop
or change the order of columns (to copy with more modification - for example changing column data
types - use the Modify stage as described in Chapter 23, “Modify stage,” on page 301). Copy lets you
make a backup copy of a data set on disk while performing an operation on another copy, for example.

Where you are using a Copy stage with a single input and a single output, you should ensure that you
set the Force property in the stage editor TRUE. This prevents WebSphere DataStage from deciding that
the Copy operation is superfluous and optimizing it out of the job.

The stage editor has three pages:

v Stage Page. This is always present and is used to specify general information about the stage.
v Input Page. This is where you specify details about the input link carrying the data to be copied.
v Output Page. This is where you specify details about the copied data being output from the stage.

Example
In this example we are going to copy data from a table containing billing information for GlobalCo’s
customers.. We are going to copy it to three separate data sets, and in each case we are only copying a
subset of the columns. The Copy stage will drop the unwanted columns as it copies the data set.

The column names for the input data set are as follows:
v BILL_TO_NUM
v CUST_NAME
v ,ADDR_1
v ,ADDR_2

© Copyright IBM Corp. 2006 291

v ,CITY
v ,REGION_CODE
v ,ZIP,
v ATTENT
v COUNTRY_CODE
v TEL_NUM
v FIRST_SALES_DATE
v LAST_SALES_DATE
v REVIEW_MONTH
v SETUP_DATE
v STATUS_CODE
v REMIT_TO_CODE
v CUST_TYPE_CODE
v CUST_VEND
v MOD_DATE
v MOD_USRNM
v CURRENCY_CODE
v CURRENCY_MOD_DATE
v MAIL_INVC_FLAG
v PYMNT_CODE
v YTD_SALES_AMT
v CNTRY_NAME
v CAR_RTE
v TPF_INVC_FLAG,
v INVC_CPY_CNT
v INVC_PRT_FLAG
v FAX_PHONE,
v FAX_FLAG
v ANALYST_CODE
v ERS_FLAG

Here is the job that will perform the copying:

292 Parallel Job Developer Guide

The Copy stage properties are fairly simple. The only property is Force, and we do not need to set it in
this instance as we are copying to multiple data sets (and WebSphere DataStage will not attempt to
optimize it out of the job). We need to concentrate on telling WebSphere DataStage which columns to
drop on each output link. The easiest way to do this is using the Output page Mapping tab. When you
open this for a link the left pane shows the input columns, simply drag the columns you want to
preserve across to the right pane. We repeat this for each link as follows:

Chapter 22. Copy stage 293

294 Parallel Job Developer Guide
Chapter 22. Copy stage 295
When the job is run, three copies of the original data set are produced, each containing a subset of the
original columns, but all of the rows. Here is some sample data from each of the data set on DSLink6,
which gives name and address information:
"GC10001 ","PEMBERTON CREEK SUBDIVISION","ONE LIEBICH LN ","","TAMPA","FL","33610"
"GC10015 ","SUMMIT PIPE & SUPPLY","6501 MCFARLAND BOULEVARD"," ","NORTHPORT","AL","35476"
"GC10022 ","M & C EQUIPMEMT","2106 HWY 290E"," ","BRENHAM","TX","77833-7136"
"GC10061 ","PLATEAU EQUIPMENT SUPPLY CO","805 S 8TH ST"," ","GRAND JUNCTION","CO","81501"
"GC10072 ","X10PRO","10014 NORTH DALE MABRY HWY"," ","TAMPA","FL","33618"
"GC10079 ","PLATEAU INSULATION CO","14200 EAST 33RD PL"," ","AURORA","CO","80011"
"GC10134 ","MACMILLAN BLOEDEL PCKGING INC","1901 E 22ND STREET"," ","LITTLE ROCK","AR","72206-2548"
"GC10144 ","PONTE VEDRA DERMATOLOGY","224 PONTE VEDRA PARK DR"," ","PONTE VEDRA BEACH","FL","32082"

Must do’s
WebSphere DataStage has many defaults which means that it can be very easy to include Copy stages in
a job. This section specifies the minimum steps to take to get a Copy stage functioning. WebSphere
DataStage provides a versatile user interface, and there are many shortcuts to achieving a particular end,
this section describes the basic method, you will learn where the shortcuts are when you get familiar
with the product.

To use a Copy stage:

v Ensure that meta data has been defined for input link and output links.

296 Parallel Job Developer Guide

v In the Output Page Mapping Tab, specify how the input columns of the data set being copied map
onto the columns of the various output links.

Stage page
The General tab allows you to specify an optional description of the stage. The Properties tab lets you
specify what the stage does. The Advanced tab allows you to specify how the stage executes.

Properties tab
The Properties tab allows you to specify properties which determine what the stage actually does. The
Copy stage only has one property.

Category/
Property Values Default Mandatory? Repeats? Dependent of
Options/Force True/False False N N N/A

Options category
Force

Set True to specify that WebSphere DataStage should not try to optimize the job by removing a Copy
operation where there is one input and one output. Set False by default.

Advanced tab
This tab allows you to specify the following:
v Execution Mode. The stage can execute in parallel mode or sequential mode. In parallel mode the
input data is processed by the available nodes as specified in the Configuration file, and by any node
constraints specified on the Advanced tab. In Sequential mode the entire data set is processed by the
conductor node.
v Combinability mode. This is Auto by default, which allows WebSphere DataStage to combine the
operators that underlie parallel stages so that they run in the same process if it is sensible for this type
of stage.
v Preserve partitioning. This is Propagate by default. It adopts the setting of the previous stage.You can
explicitly select Set or Clear. Select Set to request the stage should attempt to maintain the
partitioning.
v Node pool and resource constraints. Select this option to constrain parallel execution to the node pool
or pools and/or resource pool or pools specified in the grid. The grid allows you to make choices from
drop down lists populated from the Configuration file.
v Node map constraint. Select this option to constrain parallel execution to the nodes in a defined node
map. You can define a node map by typing node numbers into the text box or by clicking the browse
button to open the Available Nodes dialog box and selecting nodes from there. You are effectively
defining a new node pool for this stage (in addition to any node pools defined in the Configuration
file).

Input page
The Input page allows you to specify details about the data set being copied. There is only one input
link.

Chapter 22. Copy stage 297

The General tab allows you to specify an optional description of the link. The Partitioning tab allows you
to specify how incoming data on the source data set link is partitioned. The Columns tab specifies the
column definitions of incoming data. The Advanced tab allows you to change the default buffering
settings for the input link.

Details about Copy stage partitioning are given in the following section. See ″Stage Editors,″ for a general
description of the other tabs.

Partitioning on input links

The Partitioning tab allows you to specify details about how the incoming data is partitioned or collected
before the copy is performed.

By default the stage uses the auto partitioning method.

If the Copy stage is operating in sequential mode, it will first collect the data before writing it to the file
using the default auto collection method.

The Partitioning tab allows you to override this default behavior. The exact operation of this tab depends
on:
v Whether the Copy stage is set to execute in parallel or sequential mode.
v Whether the preceding stage in the job is set to execute in parallel or sequential mode.

If the Copy stage is set to execute in parallel, then you can set a partitioning method by selecting from
the Partition type drop-down list. This will override any current partitioning.

If the Copy stage is set to execute in sequential mode, but the preceding stage is executing in parallel,
then you can set a collection method from the Collector type drop-down list. This will override the
default auto collection method.

The following partitioning methods are available:

v (Auto). WebSphere DataStage attempts to work out the best partitioning method depending on
execution modes of current and preceding stages and how many nodes are specified in the
Configuration file. This is the default method for the Copy stage.
v Entire. Each file written to receives the entire data set.
v Hash. The records are hashed into partitions based on the value of a key column or columns selected
from the Available list.
v Modulus. The records are partitioned using a modulus function on the key column selected from the
Available list. This is commonly used to partition on tag fields.
v Random. The records are partitioned randomly, based on the output of a random number generator.
v Round Robin. The records are partitioned on a round robin basis as they enter the stage.
v Same. Preserves the partitioning already in place.
v DB2. Replicates the DB2 partitioning method of a specific DB2 table. Requires extra properties to be
set. Access these properties by clicking the properties button.
v Range. Divides a data set into approximately equal size partitions based on one or more partitioning
keys. Range partitioning is often a preprocessing step to performing a total sort on a data set. Requires
extra properties to be set. Access these properties by clicking the properties button.

The following Collection methods are available:

v (Auto). This is the default collection method for the Copy stage. Normally, when you are using Auto
mode, WebSphere DataStage will eagerly read any row from any input partition as it becomes
available.

298 Parallel Job Developer Guide

v Ordered. Reads all records from the first partition, then all records from the second partition, and so
on.
v Round Robin. Reads a record from the first input partition, then from the second partition, and so on.
After reaching the last partition, the operator starts over.
v Sort Merge. Reads records in an order based on one or more columns of the record. This requires you
to select a collecting key column from the Available list.

The Partitioning tab also allows you to specify that data arriving on the input link should be sorted
before the remove duplicates operation is performed. The sort is always carried out within data
partitions. If the stage is partitioning incoming data the sort occurs after the partitioning. If the stage is
collecting data, the sort occurs before the collection. The availability of sorting depends on the
partitioning or collecting method chosen (it is not available for the default auto methods).

Select the check boxes as follows:

v Perform Sort. Select this to specify that data coming in on the link should be sorted. Select the column
or columns to sort on from the Available list.
v Stable. Select this if you want to preserve previously sorted data sets. This is the default.
v Unique. Select this to specify that, if multiple records have identical sorting key values, only one
record is retained. If stable sort is also set, the first record is retained.

If NLS is enabled an additional button opens a dialog box allowing you to select a locale specifying the
collate convention for the sort.

You can also specify sort direction, case sensitivity, whether sorted as ASCII or EBCDIC, and whether null
columns will appear first or last for each column. Where you are using a keyed partitioning method, you
can also specify whether the column is used as a key for sorting, for partitioning, or for both. Select the
column in the Selected list and right-click to invoke the shortcut menu.

Output page
The Output page allows you to specify details about data output from the Copy stage. The stage can
have any number of output links, choose the one you want to work on from the Output name drop
down list.

The General tab allows you to specify an optional description of the output link. The Columns tab
specifies the column definitions of the data. The Mapping tab allows you to specify the relationship
between the columns being input to the Copy stage and the output columns. The Advanced tab allows
you to change the default buffering settings for the output links.

Details about Copy stage mapping is given in the following section. See ″Stage Editors,″ for a general
description of the other tabs.

Mapping tab
For Copy stages the Mapping tab allows you to specify how the output columns are derived, i.e., what
copied columns map onto them.

The left pane shows the copied columns. These are read only and cannot be modified on this tab.

The right pane shows the output columns for the output link. This has a Derivations field where you can
specify how the column is derived.You can fill it in by dragging copied columns over, or by using the
Auto-match facility.

Chapter 22. Copy stage 299

300 Parallel Job Developer Guide
Chapter 23. Modify stage
The Modify stage is a processing stage. It can have a single input link and a single output link.

The modify stage alters the record schema of its input data set. The modified data set is then output. You
can drop or keep columns from the schema, or change the type of a column.

The stage editor has three pages:

v Stage Page. This is always present and is used to specify general information about the stage.
v Input Page. This is where you specify details about the input link.
v Output Page. This is where you specify details about the modified data being output from the stage.

Examples

Dropping and keeping columns

The following example takes a data set comprising the following columns:

Column name SQL Type Length Scale

CUSTID Decimal 6
NAME Char 45
ADDRESS Char 40
CITY Char 30
STATE Char 2
ZIP Char 9
AREA Decimal 3
PHONE Char 9
REPID Decimal 4
CREDITLIMIT Decimal 9 2
COMMENTS VarChar 254

The modify stage is used to drop the REPID, CREDITLIMIT, and COMMENTS columns. To do this, the
stage properties are set as follows:
Specification = DROP REPID, CREDITLIMIT, COMMENTS

The easiest way to specify the outgoing meta data in this example would be to use runtime column
propagation. You could, however, choose to specify the meta data manually, in which case it would look

© Copyright IBM Corp. 2006 301

like:

Column name SQL Type Length Scale

CUSTID Decimal 6
NAME Char 45
ADDRESS Char 40
CITY Char 30
STATE Char 2
ZIP Char 9
AREA Decimal 3
PHONE Char 9

You could achieve the same effect by specifying which columns to keep, rather than which ones to drop.
In the case of this example the required specification to use in the stage properties would be:
KEEP CUSTID, NAME, ADDRESS, CITY, STATE, ZIP, AREA, PHONE

Changing data type

You could also change the data types of one or more of the columns from the above example. Say you
wanted to convert the CUSTID from decimal to string, you would specify a new column to take the
converted data, and specify the conversion in the stage properties:

Column name SQL Type Length Scale

conv_CUSTID Char 20
NAME Char 45
ADDRESS Char 40
CITY Char 30
STATE Char 2
ZIP Char 9
AREA Decimal 3
PHONE Char 9
REPID Decimal 4
CREDITLIMIT Decimal 9 2
COMMENTS VarChar 254

Specification = conv_CUSTID = CUSTID

Some data type conversions require you to use a transform command, a list of these, and the available
transforms, is given in ″Specification″ . The decimal to string conversion is one that can be performed
using an explicit transform. In this case, the specification on the Properties page is as follows:
conv_CUSTID:string = string_from_decimal(CUSTID)

Null handling
You can also use the Modify stage to handle columns that might contain null values. Any of the columns
in the example, other than CUSTID, could legally contain a null value. You could use the modify stage to
detect when the PHONE column contains a null value, and handle it so no errors occur. In this case, the
specification on the Properties page would be:

302 Parallel Job Developer Guide

PHONE = handle_null (PHONE,-128)

Other null handling transforms are described in ″Specification″ .

Must do’s
WebSphere DataStage has many defaults which means that it can be very easy to include Modify stages
in a job. This section specifies the minimum steps to take to get a Modify stage functioning. WebSphere
DataStage provides a versatile user interface, and there are many shortcuts to achieving a particular end,
this section describes the basic method, you will learn where the shortcuts are when you get familiar
with the product.

To use a Modify stage:

v In the Stage page Properties Tab, supply the Modify specification.
v Ensure you have specified the meta data for the input and output columns

Stage page
The General tab allows you to specify an optional description of the stage. The Properties tab lets you
specify what the stage does. The Advanced tab allows you to specify how the stage executes.

Properties tab
The Properties tab allows you to specify properties which determine what the stage actually does. The
modify stage only has one property, although you can repeat this as required.

Category/
Property Values Default Mandatory? Repeats? Dependent of
Options/ string N/A Y Y N/A
Specification

Options category
Specification

This is a statement with one of the following the forms:

v DROP columnname [, columnname]
v KEEP columnname [, columnname]
v new_columnname [:new_type] = [explicit_conversion_function] old_columnname

If you choose to drop a column or columns, all columns are retained except those you explicitly drop. If
you chose to keep a column or columns, all columns are excluded except those you explicitly keep.

If you specify multiple specifications each will be carried out sequentially.

Some type conversions WebSphere DataStage can carry out automatically, others need you to specify an
explicit conversion function. Some conversions are not available. The following table summarizes the
availability, ″d″ indicates automatic (default) conversion, ″m″ indicates that manual conversion is
required, a blank square indicates that conversion is not possible:

Chapter 23. Modify stage 303

 Destination Field
Source
Field
int8 uint8 int16 uint16 int32 uint32 int64 uint64 sfloat dfloat
int8 d d d d d d d d dm
uint8 d d d d d d d d d
int16 dm d d d d d d d d
uint16 d d d d d d d d d
int32 dm d d d d d d d d
uint32 d d d d d d d d d
int64 dm d d d d d d d d
uint64 d d d d d d d d d
sfloat dm d d d d d d d d
dfloat dm d d d d d d d d
decimal dm d d d dm d dm dm d dm
string dm d dm d d dm d d d dm
ustring dm d dm d d dm d d d dm
raw m m
date m m m m
time m m m
time m m m
stamp

Source Field
decimal string ustring raw date time timestamp
int8 d dm dm m m m
uint8 d d d
int16 d dm dm
uint16 d dm dm
int32 d dm dm m m
uint32 d m m m
int64 d d d
uint64 d d d
sfloat d d d
dfloat dm dm dm m m
decimal dm dm
string dm d m m m
ustring dm d m m
raw
date m m m
time m m dm
timestamp m m m m

304 Parallel Job Developer Guide

For a default type conversion, your specification would take the following form:
new_columnname = old_columnname

For example:
int8col = uint64col

Where a manual conversion is required, your specification takes the form:

new_columnname:new_type = conversion_function (old_columnname)

For example:
day_column:int8 = month_day_from_date (date_column)

The new_type can be any of the destination types that are supported for conversions from the source (that
is, any of the columns marked ″m″ in the above table). For example, you can use the conversion
hours_from_time to convert a time to an int8, or to an int16, int32, dfloat, and so on. WebSphere
DataStage warns you when it is performing an implicit data type conversion, for example
hours_from_time expects to convert a time to an int8, and will warn you if converting to a int16, int32,
or dfloat.

The following table lists the available conversion functions. The source and destinations are always
specified in terms of column names. Preliminary arguments are enclosed in square brackets, the source
column name is enclosed in round brackets.

Output
Conversion Arguments type Description Example
date_from_days_since [base_date (date)] date Converts an date_col:date =
(number_col integer field date_from_days_since
(int32)) into a date by [″1958-08-18″] (int_col)
adding the
integer to the
specified base
date. The
base_date must
be in the
format
yyyy-mm-dd and
must be either
double

quoted or a
variable.
date_from_julian_day (juliandate_col date Date from date_col:date =
(uint32)) Julian day. date_from_julian_day
(julian_col)
date_from_string [date_format] date Converts the date_col:date = date_from_string
(string_col string to a date [″%yyyy-%mm-%dd″]
(string)) representation (string_col)
using the
specified
date_format. By
default the
string format is
yyyy-mm-dd.

Chapter 23. Modify stage 305

 Output
Conversion Arguments type Description Example
date_from_timestamp (timestamp_col date Converts the date_col:date =
(timestamp) ) timestamp to a date_from_timestamp (ts_col)
date
representation.
date_from_ustring [date_format] date Converts the date_col:date =
(string_col string to a date date_from_ustring (ustring_col,
(ustring)) representation ″%yyyy-%mm-%dd″)
using the
specified
date_format. By
default the
string format is
yyyy-mm-dd.
days_since_from_date [source_date int32 Returns a value dayssince_col:int32 =
(date)] (date_col corresponding days_since_from_date
(string)) to the number [″1958-08-18″] (sourcedate_col,)
of days from
source_date to
the specified
date. source_date
must be in the
form
yyyy-mm-dd and
can be quoted
or unquoted.
decimal_from_decimal [r_type] decimal Decimal from decimal_col:decimal =
(source_decimal_col decimal. decimal_from_decimal [ceil]
(decimal)) (source_col)
decimal_from_dfloat [r_type] decimal Decimal from decimal_col:decimal =
(source_dfloat_col dfloat. decimal_from_dfloat [ceil]
(dfloat)) (source_col)
decimal_from_string [r_type] decimal Decimal from decimal_col:decimal =
(source_string_col string. decimal_from_string [ceil]
(string)) (source_col)
decimal_from_ustring [r_type] decimal Decimal from decimal_col:decimal =
(source_ustring_col ustring. decimal_from_ustring [ceil]
(ustring)) (source_col)
dfloat_from_decimal [fix_zero] dfloat Dfloat from dfloat_col:dfloat =
(source_dec_col decimal. dfloat_from_decimal [fix_zero]
(decimal)) (source_col)
hours_from_time (source_time_col int8 Hours from hours_col:int8 =
(time)) time. hours_from_time (time_col)
int32_from_decimal [r_type, fix_zero] int32 Int32 from int32_col:int32 =
(source_decimal_col decimal. int32_from_decimal [ceil]
(decimal)) [fix_zero] (dec_col)
int64_from_decimal [r_type, fix_zero] int64 Int64 from int64_col:int64 =
(source_decimal_col decimal. int64_from_decimal [ceil]
(decimal)) (dec_col)
julian_day_from_date (date_col (date)) uint32 Julian day from julianday_col:uint32 =
date. julian_day_from_from_date
(date_col)

306 Parallel Job Developer Guide

 Output
Conversion Arguments type Description Example
lookup_string_from_int16 [table_definition ], string Converts gendercol:string =
(number_col numeric values lookup_string_from_int16
(int16)) to strings by [{default_value = 2} (’f’ = 1; ’m’
means of a = 2)] (gendercode)
lookup table.
lookup_ustring_from_int16 [table_definition ] ustring Converts gendercol:ustring =
(number_col numeric values lookup_ustring_from_int16
(int16)) to ustrings by [{default_value = 2} (’f’ = 1; ’m’
means of a = 2)] (gendercode)
lookup table.
lookup_ustring_from_int32 [table_definition ] ustring Converts gendercol:ustring =
(number_col numeric values lookup_string_from_int32
(int32)) to ustrings by [{default_value = 2} (’f’ = 1; ’m’
means of a = 2)] (gendercode)
lookup table..
lookup_string_from_uint32 [table_definition ] string Converts gendercol:string =
(number_col numeric values lookup_string_from_uint16
(uint32)) to strings by [{default_value = 2} (’f’ = 1; ’m’
means of a = 2)] (gendercode)
lookup table.
lookup_int16_from_string [table_definition ] int16 Converts int_col:int16 =
(string_col strings to lookup_int16_from_string
(string)) numeric values [{default_value = 2} (’f’ = 1; ’m’
by means of a = 2)] (gendercode)
lookup table.
lookup_int16_from_ustring [table_definition ] int16 Converts int_col:int16 =
(ustring_col strings to lookup_int16_from_ustring
(ustring)) numeric values [{default_value = 2} (’f’ = 1; ’m’
by means of a = 2)] (gendercode)
lookup table.
lookup_uint32_from_string [table_definition ] uint32 Converts int_col:uint32 =
(string_col strings to lookup_uint32_from_ustring
(string)) numeric values [{default_value = 2} (’f’ = 1; ’m’
by means of a = 2)] (gendercode)
lookup table.
lookup_uint32_from_ustring [table_definition ] uint32 Converts int_col:uint32 =
(ustring_col ustrings to lookup_uint32_from_ustring
(ustring)) numeric values [{default_value = 2} (’f’ = 1; ’m’
by means of a = 2)] (gendercode)
lookup table.
lowercase_string (instring_col string Convert strings ostring_col:string =
(string)) to all lower lowercase_string (istring_col)
case.
Non-alphabetic
characters are
ignored in the
conversion.
lowercase_ustring (instring_col string Convert ostring_col:ustring =
(ustring)) ustrings to all lowercase_string (istring_col)
lower case.
Non-alphabetic
characters are
ignored in the
conversion.

Chapter 23. Modify stage 307

 Output
Conversion Arguments type Description Example
mantissa_from_decimal (decimal_col dfloat Returns the matissa_col:dfloat =
(decimal)) mantissa from mantissa_from_decimal (dec_col)
the given
decimal
mantissa_from_dfloat (dfloat_col (dfloat)) dfloat Returns the matissa_col:dfloat =
mantissa from mantissa_from_dfloat
the given dfloat (dfloat_col)
microseconds_from_time (time_col (time)) int32 Returns the msec_col:int32 =
microseconds microseconds_from_time
from a time (time_col)
field.
midnight_seconds_from_time (time_col (time)) dfloat Returns the midsec_col:dfloat =
seconds-from- midnight_seconds_from_time
midnight from (time_col)
the supplied
time.
minutes_from_time (time_col (time)) int8 Returns the minsec_col:int8 =
minutes from a minutes_from_time (time_col)
time field.
month_day_from_date (date_col (date)) int8 Returns the day monthday_col:int8 =
of month from month_day_from_date (date_col)
a date field.
month_from_date (date_col (date)) int8 Returns the month_col:int8 =
numeric month month_from_date (date_col)
from a date
field.
next_weekday_from_date [day] (date_col date Returns the nextday_col:date =
(date)) date of the next_weekday_from_date
specified day of [wed](date_col)
the week
soonest after
the source date
(including the
source date).
day is a string
specifying a
day of the
week. You can
specify day by
either the first
three characters
of the day
name or the
full day name.
The day can be
quoted in either
single or
double quotes
or quotes can
be omitted.

308 Parallel Job Developer Guide

 Output
Conversion Arguments type Description Example
notnull (any) int8 Returns true (1) isnotnull_col:int8 = notnull
when an (test_col)
expression does
not evaluate to
the null value.
null (any) int8 Returns true (1) isnull_col:int8 = null (test_col)
when an
expression does
evaluate to the
null value
previous_weekday_from_date [day] (date_col date The destination prevday_col:date =
(date)) contains the previous_weekday_from_date
closest date for [wed](date_col)
the specified
day of the
week earlier
than the source
date (including
the source
date). The day
is a string
specifying a
day of the
week. You can
specify day by
either the first
three characters
of the day
name or the
full day name.
The day can be
quoted in either
single or
double quotes
or quotes can
be omitted.
raw_from_string (string_col raw Returns a string raw_col:raw = raw_from_string
(string)) in raw (string_col)
representation.
raw_length (raw_col (raw)) int32 Returns the rawlength_col:int32 =
length of a raw raw_length (raw_col)
field.
seconds_from_time (time_col (time)) dfloat Returns the sec_col:dfloat =
seconds from a seconds_from_time (time_col)
time field.
seconds_since_from_timestamp (timestamp_col dfloat Seconds since secsince_col:dfloat =
(timestamp)) the time given seconds_since_from_timestamp
by timestamp. (timestamp_col)
string_from_date [date_format] string Converts the datestring_col:string =
(date_col (date)) date to a string string_from_date
representation [%dd-%mm-%yyyy] (date_col)
using the
specified
date_format.

Chapter 23. Modify stage 309

 Output
Conversion Arguments type Description Example
string_from_decimal [fix_zero] string Returns a string string_col:string =
(decimal_col from a decimal. string_from_decimal [fix_zero]
(decimal) (dec_col)
string_from_time [time_format] string Converts the timestring_col:string =
(time_col (time)) time to a string string_from_time
representation [%hh:%nn:%ss.] (time_col)
using the
specified
time_format. The
default time
format is
%hh:%nn:%ss.
string_from_timestamp [timestamp_format] Converts the stringtimestamp_col:string =
(timestamp_col timestamp to a string_from_timestamp
(timestamp)) string [%yyyy-%mm-%dd.
representation %hh:%nn:%ss.] (timestamp_col)
using the
specified
timestamp_format.
The default
timestamp
format is
%yyyy-%mm-
%dd.
%hh:%nn:%ss.
string_from_ustring (string_col string Returns a string string_col:string =
(ustring)) from a ustring. string_from_ustring (ustring_col)
string_length (string_col int32 Returns an length_col:int32 = string_length
(string)) int32 containing (string_col)
the length of a
string.

310 Parallel Job Developer Guide

 Output
Conversion Arguments type Description Example
substring [startPosition,len] string Converts long shorstring_col:string = substring
(string_col strings to [5,10] (longstring_col)
(string)) shorter strings
by string
extraction. The
startPosition
specifies the
starting location
of the
substring; len
specifies the
substring
length. If
startPosition is
positive, it
specifies the
byte offset into
the string from
the beginning
of the string. If
startPosition is
negative, it
specifies the
byte offset from
the end of the
string.
time_from_midnight_seconds (dfloat_col (dfloat)) time Returns a time time_col:time =
from time_from_midnight_seconds
aseconds-from- (dfloat_col)
midnight field.
time_from_string [time_format] time Converts the time_col:time = time_from_string
(string_col string to a time [%hh:%nn:%ss.] (string_col)
(string)) representation
using the
specified
time_format. The
default time
format is
%hh:%nn:%ss.
time_from_timestamp (timestamp_col time Time from time_col:time =
(timestamp)) timestamp. time_from_timestamp
(timestamp_col)
time_from_ustring (string_col time Returns a time time_col:time =
(ustring)) from a ustring. time_from_ustring (string_col)

Chapter 23. Modify stage 311

 Output
Conversion Arguments type Description Example
timestamp_from_date [time](date_col timestamp Timestamp timestamp_col:timestamp =
(date)) from date. The timestamp_from_date [08:20:33]
time argument (date_col)
optionally
specifies the
time to be used
in building the
timestamp
result and must
be in the form
hh:nn:ss. If
omitted, the
time defaults to
midnight.
timestamp_from_seconds_since (secondssince_col timestamp Timestamp timestamp_col:timestamp =
(dfloat)) from a seconds timestamp_from_seconds_since
since value. (secondssince_col)
timestamp_from_string [timestamp_format] timestamp Converts the timestamp_col:timestamp =
(string_col string to a timestamp_from_string
(string)) timestamp [%yyyy-%mm-%dd hh:nn:ss]
representation (string_col)
using the
specified
timestamp_format.
By default, the
string format is
%yyyy-
%mm-%dd
hh:nn:ss.

timestamp_from_time [date](time_col timestamp Timestamp timestamp_col:timestamp =

(time)) from time. The timestamp_from_time
date argument [1958-08-18] (time_col)
is required. It
specifies the
date portion of
the timestamp
and must be in
the form
yyyy-mm-dd.

timestamp_from_timet (timet_col (int32)) timestamp Timestamp timestamp_col:timestamp =

from time_t. timestamp_from_timet
The source field (timet_col)
must contain a
timestamp as
defined by the
UNIX time_t
representation.
timestamp_from_ustring (string_col timestamp Returns a timestamp_col:timestamp =
(ustring)) timestamp from timestamp_from_ustring
a ustring. (string_col)

312 Parallel Job Developer Guide

 Output
Conversion Arguments type Description Example
timet_from_timestamp (tstamp_col int32 Time_t from timet_col:int32 =
(timestamp)) timestamp. The timet_from_timestamp
destination (tstamp_col)
column
contains a
timestamp as
defined by the
UNIX time_t
representation.
uint64_from_decimal [r_type, fix_zero] uint64 Uint64 from int_col:uint64 =
(dec_col (decimal)) decimal. uint64_from_decimal [ceil,
fix_zero] (dec_col)
uppercase_string (string_col string Convert strings string_col:string =
(string)) to all upper uppercase_string (instring_col)
case.
Non-alphabetic
characters are
ignored in the
conversion.
uppercase_ustring (string_col ustring Convert ustring_col:string =
(ustring)) ustrings to all uppercase_ustring (string_col)
upper case.
Non-alphabetic
characters are
ignored in the
conversion.
u_raw_from_string (string_col raw Returns a raw raw_col:raw =
(ustring)) from a ustring u_raw_from_string (string_col)
ustring_from_date (date_col (date)) ustring Returns a string_col:ustring =
ustring from a ustring_from_date (date_col)
date.
ustring_from_decimal (dec_col (decimal)) ustring Returns a string_col:ustring =
ustring from a ustring_from_decimal (dec_col)
decimal.
ustring_from_string (string_col ustring Returns a string_col:ustring =
(string)) ustring from a ustring_from_string (string_col)
string.
ustring_from_time (time_col (time)) ustring Returns a string_col:ustring =
ustring from a ustring_from_time (time_col)
time.
ustring_from_timestamp (timestamp_col ustring Returns a string_col:ustring =
(timestamp)) ustring from a ustring_from_timestamp
timestamp. (timestamp_col)
ustring_length (string_col int32 Returns the length_col:int32 = ustring_length
(ustring)) length of a (string_col)
ustring.

Chapter 23. Modify stage 313

 Output
Conversion Arguments type Description Example
u_substring [startPosition,len] ustring Converts long shorstring_col:ustring =
(string_col ustrings to substring [5,10] (longstring_col)
(string)) shorter ustrings
by string
extraction. The
startPosition
specifies the
starting location
of the
substring; len
specifies the
substring
length. If
startPosition is
positive, it
specifies the
byte offset into
the string from
the beginning
of the string. If
startPosition is
negative, it
specifies the
byte offset from
the end of the
string.
weekday_from_date [originDay] int8 Day of week dow_int:int8 = [mon] (date_col)
(date_col (date)) from date.
originDay is a
string
specifying the
day considered
to be day zero
of the week.
You can specify
the day using
either the first
three characters
of the day
name or the
full day name.
If omitted,
Sunday is
defined as day
zero. The
originDay can
be either single-
or
double-quoted
or the quotes
can be omitted.
year_day_from_date (date_col (date)) int16 Day of year doy_col:int16 =
from date year_day_from_date (date_col)
(returned value
1-366).

314 Parallel Job Developer Guide

 Output
Conversion Arguments type Description Example
year_from_date (date_col (date)) int16 Year from date. year_col:int16 = year_from_date
(date_col)
year_week_from_date (date_col (date)) int8 Week of year week_col:int8 =
from date. year_week_from_date (date_col)

tableDefinition defines the rows of a string lookup table and has the following form:
{propertyList} (’string’ = value; ’string’ = value; ... )

where:
v propertyList is one or more of the following options; the entire list is enclosed in braces and properties
are separated by commas if there are more than one:
– case_sensitive. Perform a case-sensitive search for matching strings; the default is case-insensitive.
– default_value = defVal. The default numeric value returned for a string that does not match any of
the strings in the table.
– default_string = defString. The default string returned for numeric values that do not match any
numeric value in the table.
v string specifies a comma-separated list of strings associated with value; enclose each string in quotes.
v value specifies a comma-separated list of 16-bit integer values associated with string.

date_format is the standard date formatting string described in “Date and time formats” on page 30

R_type is a string representing the rounding type and should contain one of the following:
v ceil. Round the source field toward positive infinity. E.g, 1.4 -> 2, -1.6 -> -1.
v floor. Round the source field toward negative infinity. E.g, 1.6 -> 1, -1.4 -> -2.
v round_inf. Round or truncate the source field toward the nearest representable value, breaking ties by
rounding positive values toward positive infinity and negative values toward negative infinity. E.g, 1.4
-> 1, 1.5 -> 2, -1.4 -> -1, -1.5 -> -2.
v trunc_zero. Discard any fractional digits to the right of the rightmost fractional digit supported in the
destination, regardless of sign. For example, if the destination is an integer, all fractional digits are
truncated. If the destination is another decimal with a smaller scale, round or truncate to the scale size
of the destination decimal. E.g, 1.6 -> 1, -1.6 -> -1.

You can specify fix_zero for decimal source columns so that columns containing all zeros (by default
illegal) are treated as a valid decimal with a value of zero.

Advanced tab
This tab allows you to specify the following:
v Execution Mode. The stage can execute in parallel mode or sequential mode. In parallel mode the
input data is processed by the available nodes as specified in the Configuration file, and by any node
constraints specified on the Advanced tab. In Sequential mode the entire data set is processed by the
conductor node.
v Combinability mode. This is Auto by default, which allows WebSphere DataStage to combine the
operators that underlie parallel stages so that they run in the same process if it is sensible for this type
of stage.
v Preserve partitioning. This is Propagate by default. If you have an input data set, it adopts Set or
Clear from the previous stage. You can explicitly select Set or Clear. Select Set to request the next stage
should attempt to maintain the partitioning.

Chapter 23. Modify stage 315

v Node pool and resource constraints. Select this option to constrain parallel execution to the node pool
or pools and/or resource pool or pools specified in the grid. The grid allows you to make choices from
drop down lists populated from the Configuration file.
v Node map constraint. Select this option to constrain parallel execution to the nodes in a defined node
map. You can define a node map by typing node numbers into the text box or by clicking the browse
button to open the Available Nodes dialog box and selecting nodes from there. You are effectively
defining a new node pool for this stage (in addition to any node pools defined in the Configuration
file).

Input page
The Input page allows you to specify details about the incoming data set you are modifying. There is
only one input link.

The General tab allows you to specify an optional description of the link. The Partitioning tab allows you
to specify how incoming data on the source data set link is partitioned. The Columns tab specifies the
column definitions of incoming data. The Advanced tab allows you to change the default buffering
settings for the input link.

Details about Modify stage partitioning are given in the following section. See ″Stage Editors,″ for a
general description of the other tabs.

Partitioning on input links

The Partitioning tab allows you to specify details about how the incoming data is partitioned or collected
before the modify is performed.

By default the stage uses the auto partitioning method.

If the Modify stage is operating in sequential mode, it will first collect the data before writing it to the file
using the default auto collection method.

The Partitioning tab allows you to override this default behavior. The exact operation of this tab depends
on:
v Whether the Modify stage is set to execute in parallel or sequential mode.
v Whether the preceding stage in the job is set to execute in parallel or sequential mode.

If the Modify stage is set to execute in parallel, then you can set a partitioning method by selecting from
the Partition type drop-down list. This will override any current partitioning.

If the Modify stage is set to execute in sequential mode, but the preceding stage is executing in parallel,
then you can set a collection method from the Collector type drop-down list. This will override the
default auto collection method.

The following partitioning methods are available:

v (Auto). WebSphere DataStage attempts to work out the best partitioning method depending on
execution modes of current and preceding stages and how many nodes are specified in the
Configuration file. This is the default method for the Modify stage.
v Entire. Each file written to receives the entire data set.
v Hash. The records are hashed into partitions based on the value of a key column or columns selected
from the Available list.
v Modulus. The records are partitioned using a modulus function on the key column selected from the
Available list. This is commonly used to partition on tag fields.
v Random. The records are partitioned randomly, based on the output of a random number generator.
316 Parallel Job Developer Guide
v Round Robin. The records are partitioned on a round robin basis as they enter the stage.
v Same. Preserves the partitioning already in place.
v DB2. Replicates the DB2 partitioning method of a specific DB2 table. Requires extra properties to be
set. Access these properties by clicking the properties button.
v Range. Divides a data set into approximately equal size partitions based on one or more partitioning
keys. Range partitioning is often a preprocessing step to performing a total sort on a data set. Requires
extra properties to be set. Access these properties by clicking the properties button.

The following Collection methods are available:

v (Auto). This is the default collection method for the Modify stage. Normally, when you are using Auto
mode, WebSphere DataStage will eagerly read any row from any input partition as it becomes
available.
v Ordered. Reads all records from the first partition, then all records from the second partition, and so
on.
v Round Robin. Reads a record from the first input partition, then from the second partition, and so on.
After reaching the last partition, the operation starts over.
v Sort Merge. Reads records in an order based on one or more columns of the record. This requires you
to select a collecting key column from the Available list.

The Partitioning tab also allows you to specify that data arriving on the input link should be sorted
before the modify operation is performed. The sort is always carried out within data partitions. If the
stage is partitioning incoming data the sort occurs after the partitioning. If the stage is collecting data, the
sort occurs before the collection. The availability of sorting depends on the partitioning or collecting
method chosen (it is not available for the default auto methods).

Select the check boxes as follows:

v Perform Sort. Select this to specify that data coming in on the link should be sorted. Select the column
or columns to sort on from the Available list.
v Stable. Select this if you want to preserve previously sorted data sets. This is the default.
v Unique. Select this to specify that, if multiple records have identical sorting key values, only one
record is retained. If stable sort is also set, the first record is retained.

If NLS is enabled an additional button opens a dialog box allowing you to select a locale specifying the
collate convention for the sort.

You can also specify sort direction, case sensitivity, whether sorted as ASCII or EBCDIC, and whether null
columns will appear first or last for each column. Where you are using a keyed partitioning method, you
can also specify whether the column is used as a key for sorting, for partitioning, or for both. Select the
column in the Selected list and right-click to invoke the shortcut menu.

Output page
See ″Stage Editors,″ for a general description of the output tabs.

Chapter 23. Modify stage 317

318 Parallel Job Developer Guide
Chapter 24. Filter Stage
The Filter stage is a processing stage. It can have a single input link and a any number of output links
and, optionally, a single reject link.

The Filter stage transfers, unmodified, the records of the input data set which satisfy the specified
requirements and filters out all other records. You can specify different requirements to route rows down
different output links. The filtered out records can be routed to a reject link, if required.

The stage editor has three pages:

v Stage Page. This is always present and is used to specify general information about the stage.
v Input Page. This is where you specify details about the input link carrying the data to be filtered.
v Output Page. This is where you specify details about the filtered data being output from the stage
down the various output links.

Specifying the filter

The operation of the filter stage is governed by the expressions you set in the Where property on the
Properties tab. You can use the following elements to specify the expressions:
v Input columns.
v Requirements involving the contents of the input columns.
v Optional constants to be used in comparisons.
v The Boolean operators AND and OR to combine requirements.

When a record meets the requirements, it is written unchanged to the specified output link. The Where
property supports standard SQL expressions, except when comparing strings.

When quoting in the filter, you should use single, not double, inverted commas.

© Copyright IBM Corp. 2006 319

Input data columns
If you specify a single column for evaluation, that column can be of any data type. Note that WebSphere
DataStage’s treatment of strings differs slightly from that of standard SQL. If you compare columns they
must be of the same or compatible data types. Otherwise, the operation terminates with an error.
Compatible data types are those that WebSphere DataStage converts by default. Regardless of any
conversions the whole row is transferred unchanged to the output. If the columns are not compatible
upstream of the filter stage, you can convert the types by using a Modify stage prior to the Filter stage.

Column data type conversion is based on the following rules:

v Any integer, signed or unsigned, when compared to a floating-point type, is converted to
floating-point.
v Comparisons within a general type convert the smaller to the larger size (sfloat to dfloat, uint8 to
uint16, etc.)
v When signed and unsigned integers are compared, unsigned are converted to signed.
v Decimal, raw, string, time, date, and timestamp do not figure in type conversions. When any of these is
compared to another type, filter returns an error and terminates.

The input field can contain nulls. If it does, null values are less than all non-null values, unless you
specify the operators’s nulls last option.

Note: The conversion of numeric data types may result in a loss of range and cause incorrect results.
WebSphere DataStage displays a warning message to that effect when range is lost.

Supported Boolean expressions and operators

The following list summarizes the Boolean expressions that are supported. In the list, BOOLEAN denotes
any Boolean expression.
v true
v false
v six comparison operators: =, <>, <, >, <=, >=
v is null
v is not null
v like ’abc’ (the second operand must be a regular expression)
v between (for example, A between B and C is equivalent to
v B <= A and A => C)
v not BOOLEAN
v BOOLEAN is true
v BOOLEAN is false
v BOOLEAN is not true
v BOOLEAN is not false

Any of these can be combined using AND or OR.

Order of association
As in SQL, expressions are associated left to right. AND and OR have the same precedence. You may
group fields and expressions in parentheses to affect the order of evaluation.

String comparison
WebSphere DataStage sorts string values according to these general rules:
v Characters are sorted in lexicographic order.
v Strings are evaluated by their ASCII value.

320 Parallel Job Developer Guide

v Sorting is case sensitive, that is, uppercase letters appear before lowercase letter in sorted data.
v Null characters appear before non-null characters in a sorted data set, unless you specify the nulls last
option.
v Byte-for-byte comparison is performed.

Examples
The following give some example Where properties.

Comparing two fields

You want to compare columns number1 and number2. If the data in column number1 is greater than the
data in column number2, the corresponding records are to be written to output link 2.

You enter the following in the Where property:

name1 > name2

You then select output link 2 in the dependent Output Link property. (You use the Link Ordering tab to
specify the number order of the output links).

Testing for a null

You want to test column serialno to see if it contains a null. If it does, you want to write the
corresponding records to the output link.

You enter the following in the Where property:

serialno is null

In this example the stage only has one output link. You do not need to specify the Output Link property
because the stage will write to the output link by default.

Evaluating input columns

You want to evaluate each input row to see if these conditions prevail:
v EITHER all the following are true
– Column number1 does not have the value 0
– Column number2 does not have the value 3
– Column number3 has the value 0
v OR column name equals the string ZAG

You enter the following in the Where property:

number1 <> 0 and number2 <> 3 and number3 = 0 or name = ’ZAG’

If these conditions are met, the stage writes the row to the output link.

Must do’s
WebSphere DataStage has many defaults which means that it can be very easy to include Filter stages in
a job. This section specifies the minimum steps to take to get a Filter stage functioning. WebSphere
DataStage provides a versatile user interface, and there are many shortcuts to achieving a particular end,
this section describes the basic method, you will learn where the shortcuts are when you get familiar
with the product.

To use a Filter stage:

Chapter 24. Filter Stage 321

v In the Stage page Properties Tab:
– Supply the specifications that determine which records are accepted and which are filtered out. This
is given in the form of a Where clause. You can multiple statements each applying to different links.
– Specify which Where clause correspond to which output links.
– Specify whether rows that fail to satisfy any of the Where clauses will be routed to a reject link.
– Specify whether rows are output only for the first Where clause they satisfy, or for any clauses they
satisfy.
v In the Stage page Link Ordering Tab, specify which order the output links are processed in. This is
important where you specify that rows are only output for the first Where clause that they satisfy.
v Ensure that meta data has been defined for input link and output links, and reject link, if applicable.
v In the Output Page Mapping Tab, specify how the input columns of the data set being filtered map
onto the columns of the various output links.

Stage page
The General tab allows you to specify an optional description of the stage. The Properties tab lets you
specify what the stage does. The Advanced tab allows you to specify how the stage executes. The Link
Ordering tab allows you to specify what order the output links are processed in. The NLS Locale tab
appears if your have NLS enabled on your system. It allows you to select a locale other than the project
default to determine collating rules.

Properties tab
The Properties tab allows you to specify properties which determine what the stage actually does. Some
of the properties are mandatory, although many have default settings. Properties without default settings
appear in the warning color (red by default) and turn black when you supply a value for them.

The following table gives a quick reference list of the properties and their attributes. A more detailed
description of each property follows.

Category/
Property Values Default Mandatory? Repeats? Dependent of
Predicates/Where string N/A Y Y N/A
clause
Predicates/ Output link N/A Y N Where clause
Output link
Options/Output True/False False Y N N/A
rejects
Options/Output True/False False Y N N/A
rows only once
Options/Nulls Less Less Than N N N/A
value Than/Greater
Than

Predicates category
Where clause

Specify a Where statement that a row must satisfy in order to be routed down this link. This is like an
SQL Where clause, see ″Specifying the Filter″ for details.

322 Parallel Job Developer Guide

Output link

Specify the output link corresponding to the Where clause.

Options category
Output rejects

Set this to true to output rows that satisfy no Where clauses down the reject link (remember to specify
which link is the reject link on the parallel job canvas).

Output rows only once

Set this to true to specify that rows are only output down the link of the first Where clause they satisfy.
Set to false to have rows output down the links of all Where clauses that they satisfy.

Nulls value

Specify whether null values are treated as greater than or less than other values.

Advanced tab
This tab allows you to specify the following:
v Execution Mode. The stage can execute in parallel mode or sequential mode. In parallel mode the
input data is processed by the available nodes as specified in the Configuration file, and by any node
constraints specified on the Advanced tab. In Sequential mode the entire data set is processed by the
conductor node.
v Combinability mode. This is Auto by default, which allows WebSphere DataStage to combine the
operators that underlie parallel stages so that they run in the same process if it is sensible for this type
of stage.
v Preserve partitioning. This is Propagate by default. It adopts the setting of the previous stage.You can
explicitly select Set or Clear. Select Set to request the stage should attempt to maintain the
partitioning.
v Node pool and resource constraints. Select this option to constrain parallel execution to the node pool
or pools and/or resource pool or pools specified in the grid. The grid allows you to make choices from
drop down lists populated from the Configuration file.
v Node map constraint. Select this option to constrain parallel execution to the nodes in a defined node
map. You can define a node map by typing node numbers into the text box or by clicking the browse
button to open the Available Nodes dialog box and selecting nodes from there. You are effectively
defining a new node pool for this stage (in addition to any node pools defined in the Configuration
file).

Link Ordering tab

This tab allows you to specify the order in which output links are processed. This is important where you
have set the Output rows only once property to True.

NLS Locale tab

This appears if you have NLS enabled on your system. It lets you view the current default collate
convention, and select a different one for this stage if required. You can also use a job parameter to
specify the locale, or browse for a file that defines custom collate rules. The collate convention defines the
order in which characters are collated. The Filter stage uses this when evaluating Where clauses. Select a
locale from the list, or click the arrow button next to the list to use a job parameter or browse for a collate
file.

Chapter 24. Filter Stage 323

Input page
The Input page allows you to specify details about the data set being filtered. There is only one input
link.

The General tab allows you to specify an optional description of the link. The Partitioning tab allows you
to specify how incoming data on the source data set link is partitioned. The Columns tab specifies the
column definitions of incoming data. The Advanced tab allows you to change the default buffering
settings for the input link.

Details about Filter stage partitioning are given in the following section. See ″Stage Editors,″ for a general
description of the other tabs.

Partitioning on input links

The Partitioning tab allows you to specify details about how the incoming data is partitioned or collected
before the filter is performed.

By default the stage uses the auto partitioning method.

If the Filter stage is operating in sequential mode, it will first collect the data before writing it to the file
using the default auto collection method.

The Partitioning tab allows you to override this default behavior. The exact operation of this tab depends
on:
v Whether the Filter stage is set to execute in parallel or sequential mode.
v Whether the preceding stage in the job is set to execute in parallel or sequential mode.

If the Filter stage is set to execute in parallel, then you can set a partitioning method by selecting from
the Partition type drop-down list. This will override any current partitioning.

If the Filter stage is set to execute in sequential mode, but the preceding stage is executing in parallel,
then you can set a collection method from the Collector type drop-down list. This will override the
default auto collection method.

The following partitioning methods are available:

v (Auto). WebSphere DataStage attempts to work out the best partitioning method depending on
execution modes of current and preceding stages and how many nodes are specified in the
Configuration file. This is the default method for the Filter stage.
v Entire. Each file written to receives the entire data set.
v Hash. The records are hashed into partitions based on the value of a key column or columns selected
from the Available list.
v Modulus. The records are partitioned using a modulus function on the key column selected from the
Available list. This is commonly used to partition on tag fields.
v Random. The records are partitioned randomly, based on the output of a random number generator.
v Round Robin. The records are partitioned on a round robin basis as they enter the stage.
v Same. Preserves the partitioning already in place.
v DB2. Replicates the DB2 partitioning method of a specific DB2 table. Requires extra properties to be
set. Access these properties by clicking the properties button.
v Range. Divides a data set into approximately equal size partitions based on one or more partitioning
keys. Range partitioning is often a preprocessing step to performing a total sort on a data set. Requires
extra properties to be set. Access these properties by clicking the properties button.

324 Parallel Job Developer Guide

The following Collection methods are available:
v (Auto). This is the default collection method for the Filter stage. Normally, when you are using Auto
mode, WebSphere DataStage will eagerly read any row from any input partition as it becomes
available.
v Ordered. Reads all records from the first partition, then all records from the second partition, and so
on.
v Round Robin. Reads a record from the first input partition, then from the second partition, and so on.
After reaching the last partition, the operator starts over.
v Sort Merge. Reads records in an order based on one or more columns of the record. This requires you
to select a collecting key column from the Available list.

The Partitioning tab also allows you to specify that data arriving on the input link should be sorted
before the remove duplicates operation is performed. The sort is always carried out within data
partitions. If the stage is partitioning incoming data the sort occurs after the partitioning. If the stage is
collecting data, the sort occurs before the collection. The availability of sorting depends on the
partitioning or collecting method chosen (it is not available for the default auto methods).

Select the check boxes as follows:

v Perform Sort. Select this to specify that data coming in on the link should be sorted. Select the column
or columns to sort on from the Available list.
v Stable. Select this if you want to preserve previously sorted data sets. This is the default.
v Unique. Select this to specify that, if multiple records have identical sorting key values, only one
record is retained. If stable sort is also set, the first record is retained.

If NLS is enabled an additional button opens a dialog box allowing you to select a locale specifying the
collate convention for the sort.

You can also specify sort direction, case sensitivity, whether sorted as ASCII or EBCDIC, and whether null
columns will appear first or last for each column. Where you are using a keyed partitioning method, you
can also specify whether the column is used as a key for sorting, for partitioning, or for both. Select the
column in the Selected list and right-click to invoke the shortcut menu.

Output page
The Output page allows you to specify details about data output from the Filter stage. The stage can
have any number of output links, plus one reject link, choose the one you want to work on from the
Output name drop down list.

The General tab allows you to specify an optional description of the output link. The Columns tab
specifies the column definitions of the data. The Mapping tab allows you to specify the relationship
between the columns being input to the Filter stage and the output columns. The Advanced tab allows
you to change the default buffering settings for the output links.

Details about Filter stage mapping is given in the following section. See ″Stage Editors,″ for a general
description of the other tabs.

Mapping tab
For Filter stages the Mapping tab allows you to specify how the output columns are derived, i.e., what
filtered columns map onto them.

The left pane shows the filtered columns. These are read only and cannot be modified on this tab.

Chapter 24. Filter Stage 325

The right pane shows the output columns for the output link. This has a Derivations field where you can
specify how the column is derived.You can fill it in by dragging copied columns over, or by using the
Auto-match facility.

326 Parallel Job Developer Guide

Chapter 25. External Filter stage
The External Filter stage is a processing stage. It can have a single input link and a single output link.

The External Filter stage allows you to specify a UNIX command that acts as a filter on the data you are
processing. An example would be to use the stage to grep a data set for a certain string, or pattern, and
discard records which did not contain a match. This can be a quick and efficient way of filtering data.

The stage editor has three pages:

v Stage Page. This is always present and is used to specify general information about the stage.
v Input Page. This is where you specify details about the input link carrying the data to be filtered.
v Output Page. This is where you specify details about the filtered data being output from the stage.

Must do’s
WebSphere DataStage has many defaults which means that it can be very easy to include External Filter
stages in a job. This section specifies the minimum steps to take to get an External Filter stage
functioning. WebSphere DataStage provides a versatile user interface, and there are many shortcuts to
achieving a particular end, this section describes the basic method, you will learn where the shortcuts are
when you get familiar with the product.

To use an External Filter stage:

v In the Stage page Properties Tab specify the filter command the stage will use. Optionally add
arguments that the command requires.

Stage page
The General tab allows you to specify an optional description of the stage. The Properties tab lets you
specify what the stage does. The Advanced tab allows you to specify how the stage executes.

Properties tab
The Properties tab allows you to specify properties which determine what the stage actually does. Some
of the properties are mandatory, although many have default settings. Properties without default settings
appear in the warning color (red by default) and turn black when you supply a value for them.

The following table gives a quick reference list of the properties and their attributes. A more detailed
description of each property follows.

© Copyright IBM Corp. 2006 327

Category/
Property Values Default Mandatory? Repeats? Dependent of
Options/Filter string N/A Y N N/A
Command
Options/ string N/A N N N/A
Arguments

Options category
Filter command

Specifies the filter command line to be executed and any command line options it requires. For example:
grep

Arguments

Allows you to specify any arguments that the command line requires. For example:
\(cancel\).*\1

Together with the grep command would extract all records that contained the string ″cancel″ twice and
discard other records.

Advanced tab
This tab allows you to specify the following:
v Execution Mode. The stage can execute in parallel mode or sequential mode. In parallel mode the
input data is processed by the available nodes as specified in the Configuration file, and by any node
constraints specified on the Advanced tab. In Sequential mode the entire data set is processed by the
conductor node.
v Combinability mode. This is Auto by default, which allows WebSphere DataStage to combine the
operators that underlie parallel stages so that they run in the same process if it is sensible for this type
of stage.
v Preserve partitioning. This is Propagate by default. It adopts the setting of the previous stage.You can
explicitly select Set or Clear. Select Set to request the next stage should attempt to maintain the
partitioning.
v Node pool and resource constraints. Select this option to constrain parallel execution to the node pool
or pools and/or resource pool or pools specified in the grid. The grid allows you to make choices from
drop down lists populated from the Configuration file.
v Node map constraint. Select this option to constrain parallel execution to the nodes in a defined node
map. You can define a node map by typing node numbers into the text box or by clicking the browse
button to open the Available Nodes dialog box and selecting nodes from there. You are effectively
defining a new node pool for this stage (in addition to any node pools defined in the Configuration
file).

Input page
The Input page allows you to specify details about the data set being filtered. There is only one input
link.

The General tab allows you to specify an optional description of the link. The Partitioning tab allows you
to specify how incoming data on the source data set link is partitioned. The Columns tab specifies the
column definitions of incoming data. The Advanced tab allows you to change the default buffering
settings for the input link.

328 Parallel Job Developer Guide

Details about External Filter stage partitioning are given in the following section. See ″Stage Editors,″ for
a general description of the other tabs.

Partitioning on input links

The Partitioning tab allows you to specify details about how the incoming data is partitioned or collected
before the filter is executed.

By default the stage uses the auto partitioning method.

If the External Filter stage is operating in sequential mode, it will first collect the data before writing it to
the file using the default auto collection method.

The Partitioning tab allows you to override this default behavior. The exact operation of this tab depends
on:
v Whether the External Filter stage is set to execute in parallel or sequential mode.
v Whether the preceding stage in the job is set to execute in parallel or sequential mode.

If the External Filter stage is set to execute in parallel, then you can set a partitioning method by selecting
from the Partition type drop-down list. This will override any current partitioning.

If the External Filter stage is set to execute in sequential mode, but the preceding stage is executing in
parallel, then you can set a collection method from the Collector type drop-down list. This will override
the default auto collection method.

The following partitioning methods are available:

v (Auto). WebSphere DataStage attempts to work out the best partitioning method depending on
execution modes of current and preceding stages and how many nodes are specified in the
Configuration file. This is the default method for the External Filter stage.
v Entire. Each file written to receives the entire data set.
v Hash. The records are hashed into partitions based on the value of a key column or columns selected
from the Available list.
v Modulus. The records are partitioned using a modulus function on the key column selected from the
Available list. This is commonly used to partition on tag fields.
v Random. The records are partitioned randomly, based on the output of a random number generator.
v Round Robin. The records are partitioned on a round robin basis as they enter the stage.
v Same. Preserves the partitioning already in place.
v DB2. Replicates the DB2 partitioning method of a specific DB2 table. Requires extra properties to be
set. Access these properties by clicking the properties button.
v Range. Divides a data set into approximately equal size partitions based on one or more partitioning
keys. Range partitioning is often a preprocessing step to performing a total sort on a data set. Requires
extra properties to be set. Access these properties by clicking the properties button.

The following Collection methods are available:

v (Auto). This is the default collection method for the External Filter stage. Normally, when you are
using Auto mode, WebSphere DataStage will eagerly read any row from any input partition as it
becomes available.
v Ordered. Reads all records from the first partition, then all records from the second partition, and so
on.
v Round Robin. Reads a record from the first input partition, then from the second partition, and so on.
After reaching the last partition, the operator starts over.

Chapter 25. External Filter stage 329

v Sort Merge. Reads records in an order based on one or more columns of the record. This requires you
to select a collecting key column from the Available list.

The Partitioning tab also allows you to specify that data arriving on the input link should be sorted
before the remove duplicates operation is performed. The sort is always carried out within data
partitions. If the stage is partitioning incoming data the sort occurs after the partitioning. If the stage is
collecting data, the sort occurs before the collection. The availability of sorting depends on the
partitioning or collecting method chosen (it is not available for the default auto methods).

Select the check boxes as follows:

v Perform Sort. Select this to specify that data coming in on the link should be sorted. Select the column
or columns to sort on from the Available list.
v Stable. Select this if you want to preserve previously sorted data sets. This is the default.
v Unique. Select this to specify that, if multiple records have identical sorting key values, only one
record is retained. If stable sort is also set, the first record is retained.

If NLS is enabled an additional button opens a dialog box allowing you to select a locale specifying the
collate convention for the sort.

You can also specify sort direction, case sensitivity, whether sorted as ASCII or EBCDIC, and whether null
columns will appear first or last for each column. Where you are using a keyed partitioning method, you
can also specify whether the column is used as a key for sorting, for partitioning, or for both. Select the
column in the Selected list and right-click to invoke the shortcut menu.

Output page
The Output page allows you to specify details about data output from the External Filter stage. The stage
can only have one output link.

The General tab allows you to specify an optional description of the output link. The Columns tab
specifies the column definitions of the data. The Advanced tab allows you to change the default buffering
settings for the output link.

See ″Stage Editors,″ for a general description of these tabs.

330 Parallel Job Developer Guide

Chapter 26. Change Capture stage
The Change Capture Stage is a processing stage. The stage compares two data sets and makes a record of
the differences.

The Change Capture stage takes two input data sets, denoted before and after, and outputs a single data
set whose records represent the changes made to the before data set to obtain the after data set. The stage
produces a change data set, whose table definition is transferred from the after data set’s table definition
with the addition of one column: a change code with values encoding the four actions: insert, delete,
copy, and edit. The preserve-partitioning flag is set on the change data set.

The compare is based on a set a set of key columns, rows from the two data sets are assumed to be
copies of one another if they have the same values in these key columns. You can also optionally specify
change values. If two rows have identical key columns, you can compare the value columns in the rows
to see if one is an edited copy of the other.

The stage assumes that the incoming data is key-partitioned and sorted in ascending order. The columns
the data is hashed on should be the key columns used for the data compare. You can achieve the sorting
and partitioning using the Sort stage or by using the built-in sorting and partitioning abilities of the
Change Capture stage.

You can use the companion Change Apply stage to combine the changes from the Change Capture stage
with the original before data set to reproduce the after data set (see Chapter 32, “Switch stage,” on page
375).

The Change Capture stage is very similar to the Difference stage described in Chapter 28, “Difference
stage,” on page 351.

The stage editor has three pages:

v Stage Page. This is always present and is used to specify general information about the stage.
v Input Page. This is where you specify details about the data set having its duplicates removed.
v Output Page. This is where you specify details about the processed data being output from the stage.

© Copyright IBM Corp. 2006 331

Example Data
This example shows a before and after data set, and the data set that is output by the Change Capture
stage when it has compared them.

This is the before data set:

bcol0 bcol1 bcol2 bcol3 bcol4

0 0 0 0 a
1 7 1 1 b
2 2 2 2 c
3 3 3 3 d
4 5 4 4 e
5 2 5 5 f
6 6 6 6 g
7 7 7 7 h
8 8 8 8 i
9 9 9 9 j

This is the after data set:

bcol0 bcol1 bcol2 bcol3 bcol4

0 0 0 0 a
1 1 1 1 b
2 2 2 2 c
3 3 3 3 d
4 4 4 4 e
5 5 5 5 f
6 6 6 6 g
7 7 7 7 h
8 8 8 8 i
9 9 9 9 j

This is the data set output by the Change Capture stage (bcol4 is the key column, bcol1 the value
column):

bcol0 bcol1 bcol2 bcol3 bcol4 change_code

1 1 1 1 b 3
4 4 4 4 e 3
5 5 5 5 f 3

The change_code indicates that, in these three rows, the bcol1 column in the after data set has been
edited. The bcol1 column carries the edited value.

332 Parallel Job Developer Guide

Must do’s
WebSphere DataStage has many defaults which means that it can be very easy to include Change
Capture stages in a job. This section specifies the minimum steps to take to get a Change Capture stage
functioning. WebSphere DataStage provides a versatile user interface, and there are many shortcuts to
achieving a particular end, this section describes the basic method, you will learn where the shortcuts are
when you get familiar with the product.

To use a Change Capture stage:

v In the Stage page Properties Tab:
– Specify the key column. You can repeat this property to specify a composite key. Before and after
rows are considered to be the same if they have the same value in the key column or columns.
– Optionally specify one or more Value columns. This enables you to determine if an after row is an
edited version of a before row.
(You can also set the Change Mode property to have WebSphere DataStage treat all columns not
defined as keys treated as values, or all columns not defined as values treated as keys.)
– Specify whether the stage will output the changed row or drop it. You can specify this individually
for each type of change (copy, delete, edit, or insert).
v In the Stage page Link Ordering Tab, specify which of the two links carries the before data set and
which carries the after data set.
v If the two incoming data sets aren’t already key partitioned on the key columns and sorted, set
WebSphere DataStage to do this on the Input Page Partitioning Tab.
v In the Output Page Mapping Tab, specify how the change data columns are mapped onto the output
link columns.

Stage page
The General tab allows you to specify an optional description of the stage. The Properties tab lets you
specify what the stage does. The Advanced tab allows you to specify how the stage executes. The Link
Ordering tab allows you to specify which input link carries the before data set and which the after data
set. The NLS Locale tab appears if your have NLS enabled on your system. It allows you to select a
locale other than the project default to determine collating rules.

Properties tab
The Properties tab allows you to specify properties which determine what the stage actually does. Some
of the properties are mandatory, although many have default settings. Properties without default settings
appear in the warning color (red by default) and turn black when you supply a value for them.

The following table gives a quick reference list of the properties and their attributes. A more detailed
description of each property follows.

Category/
Property Values Default Mandatory? Repeats? Dependent of
Change Input Column N/A Y Y N/A
Keys/Key
Change True/False True N N Key
Keys/Case
Sensitive
Change Ascending/ Ascending N N Key
Keys/Sort Order Descending

Chapter 26. Change Capture stage 333

Category/
Property Values Default Mandatory? Repeats? Dependent of
Change First/Last First N N Key
Keys/Nulls
Position
Change Input Column N/A N Y N/A
Values/Value
Change True/False True N N Value
Values/Case
Sensitive
Options/Change Explicit Keys & Explicit Keys & Y N N/A
Mode Values/All keys, Values
Explicit
values/Explicit
Keys, All Values
Options/Log True/False False N N N/A
Statistics
Options/Drop True/False False N N N/A
Output for Insert
Options/Drop True/False False N N N/A
Output for Delete
Options/Drop True/False False N N N/A
Output for Edit
Options/Drop True/False True N N N/A
Output for Copy
Options/Code string change_ code N N N/A
Column Name
Options/Copy number 0 N N N/A
Code
Options/Deleted number 2 N N N/A
Code
Options/Edit number 3 N N N/A
Code
Options/Insert number 1 N N N/A
Code

Change Keys category

Key

Specifies the name of a difference key input column. This property can be repeated to specify multiple
difference key input columns. You can use the Column Selection dialog box to select several keys at once
if required. Key has the following dependent properties:
v Case Sensitive
Use this property to specify whether each key is case sensitive or not. It is set to True by default; for
example, the values ″CASE″ and ″case″ would not be judged equivalent.
v Sort Order
Specify ascending or descending sort order.
v Nulls Position
Specify whether null values should be placed first or last.

334 Parallel Job Developer Guide

Change Value category
Value

Specifies the name of a value input column. You can use the Column Selection dialog box to select values
at once if required . Value has the following dependent properties:
v Case Sensitive
Use this to property to specify whether each value is case sensitive or not. It is set to True by default;
for example, the values ″CASE″ and ″case″ would not be judged equivalent.

Options category
Change mode

This mode determines how keys and values are specified. Choose Explicit Keys & Values to specify the
keys and values yourself. Choose All keys, Explicit values to specify that value columns must be defined,
but all other columns are key columns unless excluded. Choose Explicit Keys, All Values to specify that
key columns must be defined but all other columns are value columns unless they are excluded.

Log statistics

This property configures the stage to display result information containing the number of input rows and
the number of copy, delete, edit, and insert rows.

Drop output for insert

Specifies to drop (not generate) an output row for an insert result. By default, an output row is always
created by the stage.

Drop output for delete

Specifies to drop (not generate) the output row for a delete result. By default, an output row is always
created by the stage.

Drop output for edit

Specifies to drop (not generate) the output row for an edit result. By default, an output row is always
created by the stage.

Drop output for copy

Specifies to drop (not generate) the output row for a copy result. By default, an output row is not created
by the stage.

Code column name

Allows you to specify a different name for the output column carrying the change code generated for
each record by the stage. By default the column is called change_code.

Copy code

Allows you to specify an alternative value for the code that indicates the after record is a copy of the
before record. By default this code is 0.

Chapter 26. Change Capture stage 335

Deleted code

Allows you to specify an alternative value for the code that indicates that a record in the before set has
been deleted from the after set. By default this code is 2.

Edit code

Allows you to specify an alternative value for the code that indicates the after record is an edited version
of the before record. By default this code is 3.

Insert cCode

Allows you to specify an alternative value for the code that indicates a new record has been inserted in
the after set that did not exist in the before set. By default this code is 1.

Advanced tab
This tab allows you to specify the following:
v Execution Mode. The stage can execute in parallel mode or sequential mode. In parallel mode the
input data is processed by the available nodes as specified in the Configuration file, and by any node
constraints specified on the Advanced tab. In Sequential mode the entire data set is processed by the
conductor node.
v Combinability mode. This is Auto by default, which allows WebSphere DataStage to combine the
operators that underlie parallel stages so that they run in the same process if it is sensible for this type
of stage.
v Preserve partitioning. This is Propagate by default. It adopts Set or Clear from the previous stage. You
can explicitly select Set or Clear. Select Set to request that next stage in the job should attempt to
maintain the partitioning.
v Node pool and resource constraints. Select this option to constrain parallel execution to the node pool
or pools and/or resource pools or pools specified in the grid. The grid allows you to make choices
from drop down lists populated from the Configuration file.
v Node map constraint. Select this option to constrain parallel execution to the nodes in a defined node
map. You can define a node map by typing node numbers into the text box or by clicking the browse
button to open the Available Nodes dialog box and selecting nodes from there. You are effectively
defining a new node pool for this stage (in addition to any node pools defined in the Configuration
file).

Link Ordering tab

This tab allows you to specify which input link carries the before data set and which carries the after data
set.

By default the first link added will represent the before set. To rearrange the links, choose an input link
and click the up arrow button or the down arrow button.

NLS Locale tab

This appears if you have NLS enabled on your system. It lets you view the current default collate
convention, and select a different one for this stage if required. You can also use a job parameter to
specify the locale, or browse for a file that defines custom collate rules. The collate convention defines the
order in which characters are collated. The Change Capture stage uses this when it is determining the
sort order for key columns. Select a locale from the list, or click the arrow button next to the list to use a
job parameter or browse for a collate file.

336 Parallel Job Developer Guide

Input page
The Input page allows you to specify details about the incoming data sets. The Change Capture expects
two incoming data sets: a before data set and an after data set.

The General tab allows you to specify an optional description of the input link. The Partitioning tab
allows you to specify how incoming data is partitioned before being compared. The Columns tab
specifies the column definitions of incoming data. The Advanced tab allows you to change the default
buffering settings for the input link.

Details about Change Capture stage partitioning are given in the following section. See ″Stage Editors,″
for a general description of the other tabs.

Partitioning tab
The Partitioning tab allows you to specify details about how the incoming data is partitioned or collected
before it is compared. It also allows you to specify that the data should be sorted before being operated
on.

By default the stage partitions in Auto mode. This attempts to work out the best partitioning method
depending on execution modes of current and preceding stages and how many nodes are specified in the
Configuration file. In the case of the Change Capture stage, WebSphere DataStage will determine if the
incoming data is key partitioned. If it is, the Same method is used, if not, WebSphere DataStage will hash
partition the data and sort it. You could also explicitly choose hash and take advantage of the on-stage
sorting.

If the Change Capture stage is operating in sequential mode, it will first collect the data using the default
Auto collection method.

The Partitioning tab allows you to override this default behavior. The exact operation of this tab depends
on:
v Whether the Change Capture stage is set to execute in parallel or sequential mode.
v Whether the preceding stage in the job is set to execute in parallel or sequential mode.

If the Change Capture stage is set to execute in parallel, then you can set a partitioning method by
selecting from the Partition type drop-down list. This will override any current partitioning.

If the Change Capture stage is set to execute in sequential mode, but the preceding stage is executing in
parallel, then you can set a collection method from the Collector type drop-down list. This will override
the default collection method.

The following partitioning methods are available:

v (Auto). WebSphere DataStage attempts to work out the best partitioning method depending on
execution modes of current and preceding stages and how many nodes are specified in the
Configuration file. This is the default partitioning method for the Change Capture stage.
v Entire. Each file written to receives the entire data set.
v Hash. The records are hashed into partitions based on the value of a key column or columns selected
from the Available list.
v Modulus. The records are partitioned using a modulus function on the key column selected from the
Available list. This is commonly used to partition on tag fields.
v Random. The records are partitioned randomly, based on the output of a random number generator.
v Round Robin. The records are partitioned on a round robin basis as they enter the stage.
v Same. Preserves the partitioning already in place.

Chapter 26. Change Capture stage 337

v DB2. Replicates the DB2 partitioning method of a specific DB2 table. Requires extra properties to be
set. Access these properties by clicking the properties button.
v Range. Divides a data set into approximately equal size partitions based on one or more partitioning
keys. Range partitioning is often a preprocessing step to performing a total sort on a data set. Requires
extra properties to be set. Access these properties by clicking the properties button.

The following Collection methods are available:

v (Auto). This is the default collection method for Change Capture stages. For the Change Capture stage,
WebSphere DataStage will ensure that the data is sorted as it is collected.
v Ordered. Reads all records from the first partition, then all records from the second partition, and so
on.
v Round Robin. Reads a record from the first input partition, then from the second partition, and so on.
After reaching the last partition, the operator starts over.
v Sort Merge. Reads records in an order based on one or more columns of the record. This requires you
to select a collecting key column from the Available list.

The Partitioning tab also allows you to specify that data arriving on the input link should be sorted
before being compared. The sort is always carried out within data partitions. If the stage is partitioning
incoming data the sort occurs after the partitioning. If the stage is collecting data, the sort occurs before
the collection. The availability of sorting depends on the partitioning or collecting method chosen (it is
not available for the default auto methods).

Select the check boxes as follows:

v Perform Sort. Select this to specify that data coming in on the link should be sorted. Select the column
or columns to sort on from the Available list.
v Stable. Select this if you want to preserve previously sorted data sets. This is the default.
v Unique. Select this to specify that, if multiple records have identical sorting key values, only one
record is retained. If stable sort is also set, the first record is retained.

If NLS is enabled an additional button opens a dialog box allowing you to select a locale specifying the
collate convention for the sort.

You can also specify sort direction, case sensitivity, whether sorted as ASCII or EBCDIC, and whether null
columns will appear first or last for each column. Where you are using a keyed partitioning method, you
can also specify whether the column is used as a key for sorting, for partitioning, or for both. Select the
column in the Selected list and right-click to invoke the shortcut menu.

Output page
The Output page allows you to specify details about data output from the Change Capture stage. The
Change Capture stage can have only one output link.

The General tab allows you to specify an optional description of the output link. The Columns tab
specifies the column definitions of the data. The Mapping tab allows you to specify the relationship
between the columns being input to the Change Capture stage and the Output columns. The Advanced
tab allows you to change the default buffering settings for the output link.

Details about Change Capture stage mapping is given in the following section. See ″Stage Editors,″ for a
general description of the other tabs.

Mapping tab
For the Change Capture stage the Mapping tab allows you to specify how the output columns are
derived, i.e., what input columns map onto them and which column carries the change code data.
338 Parallel Job Developer Guide
The left pane shows the columns from the before/after data sets plus the change code column. These are
read only and cannot be modified on this tab.

The right pane shows the output columns for each link. This has a Derivations field where you can
specify how the column is derived.You can fill it in by dragging input columns over, or by using the
Auto-match facility. By default the data set columns are mapped automatically. You need to ensure that
there is an output column to carry the change code and that this is mapped to the Change_code column.

Chapter 26. Change Capture stage 339

340 Parallel Job Developer Guide
Chapter 27. Change Apply stage
The Change Apply stage is a processing stage. It takes the change data set, that contains the changes in
the before and after data sets, from the Change Capture stage and applies the encoded change operations
to a before data set to compute an after data set. (See Chapter 26, “Change Capture stage,” on page 331 for
a description of the Change Capture stage.)

The before input to Change Apply must have the same columns as the before input that was input to
Change Capture, and an automatic conversion must exist between the types of corresponding columns. In
addition, results are only guaranteed if the contents of the before input to Change Apply are identical (in
value and record order in each partition) to the before input that was fed to Change Capture, and if the
keys are unique.

Note: The change input to Change Apply must have been output from Change Capture without
modification. Because preserve-partitioning is set on the change output of Change Capture, you
will be warned at run time if the Change Apply stage does not have the same number of partitions
as the Change Capture stage. Additionally, both inputs of Change Apply are designated as
partitioned using the Same partitioning method

The Change Apply stage reads a record from the change data set and from the before data set, compares
their key column values, and acts accordingly:
v If the before keys come before the change keys in the specified sort order, the before record is copied to
the output. The change record is retained for the next comparison.
v If the before keys are equal to the change keys, the behavior depends on the code in the change_code
column of the change record:
– Insert: The change record is copied to the output; the stage retains the same before record for the
next comparison. If key columns are not unique, and there is more than one consecutive insert with
the same key, then Change Apply applies all the consecutive inserts before existing records. This
record order may be different from the after data set given to Change Capture.
– Delete: The value columns of the before and change records are compared. If the value columns are
the same or if the Check Value Columns on Delete is specified as False, the change and before
records are both discarded; no record is transferred to the output. If the value columns are not the
same, the before record is copied to the output and the stage retains the same change record for the

© Copyright IBM Corp. 2006 341

 next comparison. If key columns are not unique, the value columns ensure that the correct record is
deleted. If more than one record with the same keys have matching value columns, the
first-encountered record is deleted. This may cause different record ordering than in the after data
set given to the Change Capture stage. A warning is issued and both change record and before
record are discarded, i.e. no output record results.
– Edit: The change record is copied to the output; the before record is discarded. If key columns are
not unique, then the first before record encountered with matching keys will be edited. This may be
a different record from the one that was edited in the after data set given to the Change Capture
stage. A warning is issued and the change record is copied to the output; but the stage retains the
same before record for the next comparison.
– Copy: The change record is discarded. The before record is copied to the output.
v If the before keys come after the change keys, behavior also depends on the change_code column:
– Insert. The change record is copied to the output, the stage retains the same before record for the
next comparison. (The same as when the keys are equal.)
– Delete. A warning is issued and the change record discarded while the before record is retained for
the next comparison.
– Edit or Copy. A warning is issued and the change record is copied to the output while the before
record is retained for the next comparison.

Note: If the before input of Change Apply is identical to the before input of Change Capture and
either the keys are unique or copy records are used, then the output of Change Apply is
identical to the after input of Change Capture. However, if the before input of Change Apply
is not the same (different record contents or ordering), or the keys are not unique and copy
records are not used, this is not detected and the rules described above are applied anyway,
producing a result that might or might not be useful.

The stage editor has three pages:

v Stage Page. This is always present and is used to specify general information about the stage.
v Input Page. This is where you specify the details about the single input set from which you are
selecting records.
v Output Page. This is where you specify details about the processed data being output from the stage.

Example Data
This example shows a before and change data set, and the data set that is output by the Change Apply
stage when it has compared them.:

This is the before data set:

bcol0 bcol1 bcol2 bcol3 bcol4

0 0 0 0 a
1 7 1 1 b
2 2 2 2 c
3 3 3 3 d
4 5 4 4 e
5 2 5 5 f
6 6 6 6 g
7 7 7 7 h
8 8 8 8 i
9 9 9 9 j

342 Parallel Job Developer Guide

This is the change data set, as output by a Change Capture stage:

bcol0 bcol1 bcol2 bcol3 bcol4 change_code

1 1 1 1 b 3
4 4 4 4 e 3
5 5 5 5 f 3

This is the after data set, output by the Change Apply stage (bcol4 is the key column, bcol1 the value
column):

bcol0 bcol1 bcol2 bcol3 bcol4

0 0 0 0 a
1 1 1 1 b
2 2 2 2 c
3 3 3 3 d
4 4 4 4 e
5 5 5 5 f
6 6 6 6 g
7 7 7 7 h
8 8 8 8 i
9 9 9 9 j

Must do’s
WebSphere DataStage has many defaults which means that it can be very easy to include Change Apply
stages in a job. This section specifies the minimum steps to take to get a Change Apply stage functioning.
WebSphere DataStage provides a versatile user interface, and there are many shortcuts to achieving a
particular end, this section describes the basic method, you will learn where the shortcuts are when you
get familiar with the product.

To use a Change Apply stage:

v In the Stage page Properties Tab:
– Specify the key column. You can repeat this property to specify a composite key. Before and change
rows are considered to be the same if they have the same value in the key column or columns.
– Optionally specify one or more Value columns.
(You can also set the Change Mode property to have WebSphere DataStage treat all columns not
defined as keys treated as values, or all columns not defined as values treated as keys.)
v In the Stage page Link Ordering Tab, specify which of the two links carries the before data set and
which carries the change data set.
v In the Output Page Mapping Tab, specify how the change data columns are mapped onto the output
link columns.

Chapter 27. Change Apply stage 343

Stage page
The General tab allows you to specify an optional description of the stage. The Properties tab lets you
specify what the stage does. The Advanced tab allows you to specify how the stage executes. The NLS
Locale tab appears if your have NLS enabled on your system. It allows you to select a locale other than
the project default to determine collating rules.

Properties tab
The Properties tab allows you to specify properties which determine what the stage actually does. Some
of the properties are mandatory, although many have default settings. Properties without default settings
appear in the warning color (red by default) and turn black when you supply a value for them.

The following table gives a quick reference list of the properties and their attributes. A more detailed
description of each property follows.

Category/
Property Values Default Mandatory? Repeats? Dependent of
Change Input Column N/A Y Y N/A
Keys/Key
Change True/False True N N Key
Keys/Case
Sensitive
Change Ascending/ Ascending N N Key
Keys/Sort Order Descending
Change First/Last First N N Key
Keys/Nulls
Position
Change Input Column N/A N Y N/A
Values/Value
Change True/False True N N Value
Values/Case
Sensitive
Options/Change Explicit Keys & Explicit Keys & Y N N/A
Mode Values/All keys, Values
Explicit
values/Explicit
Keys, All Values
Options/Log True/False False N N N/A
Statistics
Options/Check True/False True Y N N/A
Value Columns
on Delete
Options/Code string change_ code N N N/A
Column Name
Options/Copy number 0 N N N/A
Code
Options/Deleted number 2 N N N/A
Code
Options/Edit number 3 N N N/A
Code
Options/Insert number 1 N N N/A
Code

344 Parallel Job Developer Guide

Change Keys category
Key

Specifies the name of a difference key input column. This property can be repeated to specify multiple
difference key input columns. You can use the Column Selection dialog box to select several keys at once
if required. Key has the following dependent properties:
v Case Sensitive
Use this to property to specify whether each key is case sensitive or not. It is set to True by default; for
example, the values ″CASE″ and ″case″ would not be judged equivalent.
v Sort Order
Specify ascending or descending sort order.
v Nulls Position
Specify whether null values should be placed first or last.

Change Value category

Value

Specifies the name of a value input column for an explanation of how Value columns are used). You can
use the Column Selection dialog box to select several values at once if required. Value has the following
dependent properties:
v Case Sensitive
Use this to property to specify whether each value is case sensitive or not. It is set to True by default;
for example, the values ″CASE″ and ″case″ would not be judged equivalent.

Options category
Change mode

This mode determines how keys and values are specified. Choose Explicit Keys & Values to specify the
keys and values yourself. Choose All keys, Explicit values to specify that value columns must be defined,
but all other columns are key columns unless excluded. Choose Explicit Keys, All Values to specify that
key columns must be defined but all other columns are value columns unless they are excluded.

Log statistics

This property configures the stage to display result information containing the number of input records
and the number of copy, delete, edit, and insert records.

Check value columns on delete

Specifies that WebSphere DataStage should not check value columns on deletes. Normally, Change Apply
compares the value columns of delete change records to those in the before record to ensure that it is
deleting the correct record.

Code column name

Allows you to specify that a different name has been used for the change data set column carrying the
change code generated for each record by the stage. By default the column is called change_code.

Copy code

Allows you to specify an alternative value for the code that indicates a record copy. By default this code
is 0.

Chapter 27. Change Apply stage 345

Deleted code

Allows you to specify an alternative value for the code that indicates a record delete. By default this code
is 2.

Edit code

Allows you to specify an alternative value for the code that indicates a record edit. By default this code is
3.

Insert code

Allows you to specify an alternative value for the code that indicates a record insert. By default this code
is 1.

Advanced tab
This tab allows you to specify the following:
v Execution Mode. The stage can execute in parallel mode or sequential mode. In parallel mode the
input data is processed by the available nodes as specified in the Configuration file, and by any node
constraints specified on the Advanced tab. In Sequential mode the entire data set is processed by the
conductor node.
v Combinability mode. This is Auto by default, which allows WebSphere DataStage to combine the
operators that underlie parallel stages so that they run in the same process if it is sensible for this type
of stage.
v Preserve partitioning. This is Propagate by default. It adopts Set or Clear from the previous stage. You
can explicitly select Set or Clear. Select Set to request that next stage in the job should attempt to
maintain the partitioning.
v Node pool and resource constraints. Select this option to constrain parallel execution to the node pool
or pools and/or resource pool or pools specified in the grid. The grid allows you to make choices from
drop down lists populated from the Configuration file.
v Node map constraint. Select this option to constrain parallel execution to the nodes in a defined node
map. You can define a node map by typing node numbers into the text box or by clicking the browse
button to open the Available Nodes dialog box and selecting nodes from there. You are effectively
defining a new node pool for this stage (in addition to any node pools defined in the Configuration
file).

Link Ordering tab

This tab allows you to specify which input link carries the before data set and which carries the change
data set.

By default the first link added will represent the before set. To rearrange the links, choose an input link
and click the up arrow button or the down arrow button.

NLS Locale tab

This appears if you have NLS enabled on your system. It lets you view the current default collate
convention, and select a different one for this stage if required. You can also use a job parameter to
specify the locale, or browse for a file that defines custom collate rules. The collate convention defines the
order in which characters are collated. The Change Apply stage uses this when it is determining the sort
order for key columns. Select a locale from the list, or click the arrow button next to the list to use a job
parameter or browse for a collate file.

346 Parallel Job Developer Guide

Input page
The Input page allows you to specify details about the incoming data set.

The General tab allows you to specify an optional description of the input link. The Partitioning tab
allows you to specify how incoming data is partitioned before being compared. The Columns tab
specifies the column definitions of incoming data. The Advanced tab allows you to change the default
buffering settings for the input link.

Details about Change Apply stage partitioning are given in the following section. See ″Stage Editors,″ for
a general description of the other tabs.

Partitioning tab
The change input to Change Apply should have been output from the Change Capture stage without
modification and should have the same number of partitions. Additionally, both inputs of Change Apply
are automatically designated as partitioned using the Same partitioning method.

The standard partitioning and collecting controls are available on the Change Apply stage, however, so
you can override this behavior.

If the Change Apply stage is operating in sequential mode, it will first collect the data before writing it to
the file using the default auto collection method.

The Partitioning tab allows you to override the default behavior. The exact operation of this tab depends
on:
v Whether the Change Apply stage is set to execute in parallel or sequential mode.
v Whether the preceding stage in the job is set to execute in parallel or sequential mode.

If the Change Apply stage is set to execute in parallel, then you can set a partitioning method by
selecting from the Partition type drop-down list. This will override any current partitioning.

If the Change Apply stage is set to execute in sequential mode, but the preceding stage is executing in
parallel, then you can set a collection method from the Collector type drop-down list. This will override
the default auto collection method.

The following partitioning methods are available:

v (Auto). WebSphere DataStage attempts to work out the best partitioning method depending on
execution modes of current and preceding stages and how many nodes are specified in the
Configuration file. This is the default method for the Change Apply stage, and will apply the Same
method.
v Entire. Each file written to receives the entire data set.
v Hash. The records are hashed into partitions based on the value of a key column or columns selected
from the Available list.
v Modulus. The records are partitioned using a modulus function on the key column selected from the
Available list. This is commonly used to partition on tag fields.
v Random. The records are partitioned randomly, based on the output of a random number generator.
v Round Robin. The records are partitioned on a round robin basis as they enter the stage.
v Same. Preserves the partitioning already in place.
v DB2. Replicates the DB2 partitioning method of a specific DB2 table. Requires extra properties to be
set. Access these properties by clicking the properties button.

Chapter 27. Change Apply stage 347

v Range. Divides a data set into approximately equal size partitions based on one or more partitioning
keys. Range partitioning is often a preprocessing step to performing a total sort on a data set. Requires
extra properties to be set. Access these properties by clicking the properties button.

The following Collection methods are available:

v (Auto). This is the default collection method for the Change Apply stage. Normally, when you are
using Auto mode, WebSphere DataStage will eagerly read any row from any input partition as it
becomes available.
v Ordered. Reads all records from the first partition, then all records from the second partition, and so
on.
v Round Robin. Reads a record from the first input partition, then from the second partition, and so on.
After reaching the last partition, the operator starts over.
v Sort Merge. Reads records in an order based on one or more columns of the record. This requires you
to select a collecting key column from the Available list.

The Partitioning tab also allows you to specify that data arriving on the input link should be sorted
before the operation is performed. The sort is always carried out within data partitions. If the stage is
partitioning incoming data the sort occurs after the partitioning. If the stage is collecting data, the sort
occurs before the collection. The availability of sorting depends on the partitioning or collecting method
chosen (it is not available with the default auto methods).

Select the check boxes as follows:

v Perform Sort. Select this to specify that data coming in on the link should be sorted. Select the column
or columns to sort on from the Available list.
v Stable. Select this if you want to preserve previously sorted data sets. This is the default.
v Unique. Select this to specify that, if multiple records have identical sorting key values, only one
record is retained. If stable sort is also set, the first record is retained.

If NLS is enabled an additional button opens a dialog box allowing you to select a locale specifying the
collate convention for the sort.

You can also specify sort direction, case sensitivity, whether sorted as ASCII or EBCDIC, and whether null
columns will appear first or last for each column. Where you are using a keyed partitioning method, you
can also specify whether the column is used as a key for sorting, for partitioning, or for both. Select the
column in the Selected list and right-click to invoke the shortcut menu.

Output page
The Output page allows you to specify details about data output from the Change Apply stage. The
Change Apply stage can have only one output link.

The General tab allows you to specify an optional description of the output link. The Columns tab
specifies the column definitions of the data.The Mapping tab allows you to specify the relationship
between the columns being input to the Change Apply stage and the Output columns. The Advanced tab
allows you to change the default buffering settings for the output link.

Details about Change Apply stage mapping is given in the following section. See ″Stage Editors,″ for a
general description of the other tabs.

Mapping tab
For the Change Capture stage the Mapping tab allows you to specify how the output columns are
derived, i.e., what input columns map onto them or how they are generated.

348 Parallel Job Developer Guide

The left pane shows the common columns of the before and change data sets. These are read only and
cannot be modified on this tab.

The right pane shows the output columns for the output link. This has a Derivations field where you can
specify how the column is derived. You can fill it in by dragging input columns over, or by using the
Auto-match facility. By default the columns are mapped straight across.

Chapter 27. Change Apply stage 349

350 Parallel Job Developer Guide
Chapter 28. Difference stage
The Difference stage is a processing stage. It performs a record-by-record comparison of two input data
sets, which are different versions of the same data set designated the before and after data sets. The
Difference stage outputs a single data set whose records represent the difference between them. The stage
assumes that the input data sets have been key-partitioned and sorted in ascending order on the key
columns you specify for the Difference stage comparison. You can achieve this by using the Sort stage or
by using the built in sorting and partitioning abilities of the Difference stage.

The comparison is performed based on a set of difference key columns. Two records are copies of one
another if they have the same value for all difference keys. You can also optionally specify change values.
If two records have identical key columns, you can compare the value columns to see if one is an edited
copy of the other.

The Difference stage is similar, but not identical, to the Change Capture stage described in Chapter 26,
“Change Capture stage,” on page 331. The Change Capture stage is intended to be used in conjunction
with the Change Apply stage (Chapter 27, “Change Apply stage,” on page 341); it produces a change
data set which contains changes that need to be applied to the before data set to turn it into the after data
set. The Difference stage outputs the before and after rows to the output data set, plus a code indicating
if there are differences. Usually, the before and after data will have the same column names, in which
case the after data set effectively overwrites the before data set and so you only see one set of columns in
the output. You are warned that WebSphere DataStage is doing this. If your before and after data sets
have different column names, columns from both data sets are output; note that any key and value
columns must have the same name.

The stage generates an extra column, Diff, which indicates the result of each record comparison.

The stage editor has three pages:

v Stage Page. This is always present and is used to specify general information about the stage.
v Input Page. This is where you specify details about the data set having its duplicates removed.
v Output Page. This is where you specify details about the processed data being output from the stage.

Example data
This example shows a before and after data set, and the data set that is output by the Difference stage
when it has compared them.
© Copyright IBM Corp. 2006 351
This is the before data set:

acol0 acol1 acol2 acol3 key

0 0 0 0 a
1 7 1 1 b
2 2 2 2 c
3 3 3 3 d
4 5 4 4 e
5 2 5 5 f
6 6 6 6 g
7 7 7 7 h
8 8 8 8 i
9 9 9 9 j

This is the after data set:

acol0 acol1 acol2 acol3 key

0 0 0 0 a
1 1 1 1 b
2 2 2 2 c
3 3 3 3 d
4 4 4 4 e
5 5 5 5 f
6 6 6 6 g
7 7 7 7 h
8 8 8 8 i
9 9 9 9 j

This is the data set output by the Difference stage (Key is the key column, All non-key columns values
are set True, all other settings take the default):

acol0 acol1 acol2 acol3 key diff

0 0 0 0 a 2
1 1 1 1 b 3
2 2 2 2 c 2
3 3 3 3 d 2
4 4 4 4 e 3
5 5 5 5 f 3
6 6 6 6 g 2
7 7 7 7 h 2
8 8 8 8 i 2
9 9 9 9 j 2

352 Parallel Job Developer Guide

The diff column indicates that rows b, e, and f have been edited in the after data set (the rows output
carry the data after editing).

Must do’s
WebSphere DataStage has many defaults which means that it can be very easy to include Difference
stages in a job. This section specifies the minimum steps to take to get a Difference stage functioning.
WebSphere DataStage provides a versatile user interface, and there are many shortcuts to achieving a
particular end, this section describes the basic method, you will learn where the shortcuts are when you
get familiar with the product.

To use a Difference stage:

v In the Stage page Properties Tab:
– Specify the key column. You can repeat this property to specify a composite key. Before and after
rows are considered to be the same if they have the same value in the key column or columns.
– Optionally specify one or more Difference Value columns. This enables you to determine if an after
row is an edited version of a before row.
(You can also set the All non-Key columns are Values property to have WebSphere DataStage treat
all columns not defined as keys treated as values.)
– Specify whether the stage will output the changed row or drop it. You can specify this individually
for each type of change (copy, delete, edit, or insert).
v In the Stage page Link Ordering Tab, specify which of the two links carries the before data set and
which carries the after data set.
v If the two incoming data sets aren’t already hash partitioned on the key columns and sorted, set
WebSphere DataStage to do this on the Input Page Partitioning Tab.
v In the Output Page Mapping Tab, specify how the difference columns are mapped onto the output
link columns.

Stage page
The General tab allows you to specify an optional description of the stage. The Properties tab lets you
specify what the stage does. The Advanced tab allows you to specify how the stage executes. The Link
Ordering tab allows you to specify which input link carries the before data set and which the after data
set. The NLS Locale tab appears if your have NLS enabled on your system. It allows you to select a
locale other than the project default to determine collating rules.

Properties tab
The Properties tab allows you to specify properties which determine what the stage actually does. Some
of the properties are mandatory, although many have default settings. Properties without default settings
appear in the warning color (red by default) and turn black when you supply a value for them.

The following table gives a quick reference list of the properties and their attributes. A more detailed
description of each property follows.

Category/
Property Values Default Mandatory? Repeats? Dependent of
Difference Input Column N/A Y Y N/A
Keys/Key
Difference True/False True N N Key
Keys/Case
Sensitive

Chapter 28. Difference stage 353

Category/
Property Values Default Mandatory? Repeats? Dependent of
Difference True/False False Y N N/A
Values/All
non-Key Columns
are Values
Difference True/False True N N All non-Key
Values/Case Columns are
Sensitive Values (when
true)
Options/Tolerate True/False False N N N/A
Unsorted Inputs
Options/Log True/False False N N N/A
Statistics
Options/Drop True/False False N N N/A
Output for Insert
Options/Drop True/False False N N N/A
Output for Delete
Options/Drop True/False False N N N/A
Output for Edit
Options/Drop True/False False N N N/A
Output for Copy
Options/Copy number 0 N N N/A
Code
Options/Deleted number 2 N N N/A
Code
Options/Edit number 3 N N N/A
Code
Options/Insert number 1 N N N/A
Code

Difference Keys category

Key

Specifies the name of a difference key input column. This property can be repeated to specify multiple
difference key input columns. You can use the Column Selection dialog box to select several keys at once
if required. Key has this dependent property:
v Case Sensitive
Use this to property to specify whether each key is case sensitive or not. It is set to True by default; for
example, the values ″CASE″ and ″case″ would not be judged equivalent.

Difference Values category

All non-key columns are values

Set this to True to indicate that any columns not designated as difference key columns are value columns
for a description of value columns). It is False by default. The property has this dependent property:
v Case Sensitive
Use this to property to specify whether each value is case sensitive or not. It is set to True by default;
for example, the values ″CASE″ and ″case″ would not be judged equivalent. This property is only
available if the All non-Key columns are values property is set to True.

354 Parallel Job Developer Guide

Options category
Tolerate unsorted inputs

Specifies that the input data sets are not sorted. This property allows you to process groups of records
that may be arranged by the difference key columns but not sorted. The stage processed the input records
in the order in which they appear on its input. It is False by default.

Log statistics

This property configures the stage to display result information containing the number of input records
and the number of copy, delete, edit, and insert records. It is False by default.

Drop output for insert

Specifies to drop (not generate) an output record for an insert result. By default, an output record is
always created by the stage.

Drop output for delete

Specifies to drop (not generate) the output record for a delete result. By default, an output record is
always created by the stage.

Drop output for edit

Specifies to drop (not generate) the output record for an edit result. By default, an output record is
always created by the stage.

Drop output for copy

Specifies to drop (not generate) the output record for a copy result. By default, an output record is always
created by the stage.

Copy code

Allows you to specify an alternative value for the code that indicates the after record is a copy of the
before record. By default this code is 2.

Deleted code

Allows you to specify an alternative value for the code that indicates that a record in the before set has
been deleted from the after set. By default this code is 1.

Edit code

Allows you to specify an alternative value for the code that indicates the after record is an edited version
of the before record. By default this code is 3.

Insert code

Allows you to specify an alternative value for the code that indicates a new record has been inserted in
the after set that did not exist in the before set. By default this code is 0.

Advanced tab
This tab allows you to specify the following:

Chapter 28. Difference stage 355

v Execution Mode. The stage can execute in parallel mode or sequential mode. In parallel mode the
input data is processed by the available nodes as specified in the Configuration file, and by any node
constraints specified on the Advanced tab. In Sequential mode the entire data set is processed by the
conductor node.
v Combinability mode. This is Auto by default, which allows WebSphere DataStage to combine the
operators that underlie parallel stages so that they run in the same process if it is sensible for this type
of stage.
v Preserve partitioning. This is Propagate by default. It adopts Set or Clear from the previous stage. You
can explicitly select Set or Clear. Select Set to request that next stage in the job should attempt to
maintain the partitioning.
v Node pool and resource constraints. Select this option to constrain parallel execution to the node pool
or pools and/or resource pool or pools specified in the grid. The grid allows you to make choices from
drop down lists populated from the Configuration file.
v Node map constraint. Select this option to constrain parallel execution to the nodes in a defined node
map. You can define a node map by typing node numbers into the text box or by clicking the browse
button to open the Available Nodes dialog box and selecting nodes from there. You are effectively
defining a new node pool for this stage (in addition to any node pools defined in the Configuration
file).

Link Ordering tab

This tab allows you to specify which input link carries the before data set and which carries the after data
set.

By default the first link added will represent the before set. To rearrange the links, choose an input link
and click the up arrow button or the down arrow button.

NLS Locale tab

This appears if you have NLS enabled on your system. It lets you view the current default collate
convention, and select a different one for this stage if required. You can also use a job parameter to
specify the locale, or browse for a file that defines custom collate rules. The collate convention defines the
order in which characters are collated. The Difference stage uses this when it is determining the sort
order for key columns. Select a locale from the list, or click the arrow button next to the list to use a job
parameter or browse for a collate file.

Input page
The Input page allows you to specify details about the incoming data sets. The Difference stage expects
two incoming data sets: a before data set and an after data set.

The General tab allows you to specify an optional description of the input link. The Partitioning tab
allows you to specify how incoming data is partitioned before being compared. The Columns tab
specifies the column definitions of incoming data. The Advanced tab allows you to change the default
buffering settings for the input link.

Details about Difference stage partitioning are given in the following section. See ″Stage Editors,″ for a
general description of the other tabs.

Partitioning tab
The Partitioning tab allows you to specify details about how the incoming data is partitioned or collected
before the operation is performed. It also allows you to specify that the data should be sorted before
being operated on.

356 Parallel Job Developer Guide

By default the stage partitions in Auto mode. This attempts to work out the best partitioning method
depending on execution modes of current and preceding stages and how many nodes are specified in the
Configuration file. For a Difference stage, WebSphere DataStage checks to see if the incoming data is
key-partitioned and sorted. If it is, the Same method is used, if not, WebSphere DataStage will key
partition the data and sort it. You could also explicitly choose hash or modulus partitioning methods and
take advantage of the on-stage sorting.

If the Difference stage is operating in sequential mode, it will first collect the data using the default Auto
collection method.

The Partitioning tab allows you to override this default behavior. The exact operation of this tab depends
on:
v Whether the Difference stage is set to execute in parallel or sequential mode.
v Whether the preceding stage in the job is set to execute in parallel or sequential mode.

If the Difference stage is set to execute in parallel, then you can set a partitioning method by selecting
from the Partition type drop-down list. This will override any current partitioning.

If the Difference stage is set to execute in sequential mode, but the preceding stage is executing in
parallel, then you can set a collection method from the Collector type drop-down list. This will override
the default collection method.

The following partitioning methods are available:

v (Auto). WebSphere DataStage attempts to work out the best partitioning method depending on
execution modes of current and preceding stages and how many nodes are specified in the
Configuration file. This is the default partitioning method for the Difference stage. If the incoming data
is already key-partitioned and sorted, WebSphere DataStage will use the Same method. Otherwise it
will key partition and sort for you.
v Entire. Each file written to receives the entire data set.
v Hash. The records are hashed into partitions based on the value of a key column or columns selected
from the Available list.
v Modulus. The records are partitioned using a modulus function on the key column selected from the
Available list. This is commonly used to partition on tag fields.
v Random. The records are partitioned randomly, based on the output of a random number generator.
v Round Robin. The records are partitioned on a round robin basis as they enter the stage.
v Same. Preserves the partitioning already in place.
v DB2. Replicates the DB2 partitioning method of a specific DB2 table. Requires extra properties to be
set. Access these properties by clicking the properties button.
v Range. Divides a data set into approximately equal size partitions based on one or more partitioning
keys. Range partitioning is often a preprocessing step to performing a total sort on a data set. Requires
extra properties to be set. Access these properties by clicking the properties button.

The following Collection methods are available:

v (Auto). This is the default collection method for Difference stages. Normally, when you are using Auto
mode, WebSphere DataStage will eagerly read any row from any input partition as it becomes
available. For the Difference stage, WebSphere DataStage will ensure that the data is sorted as it is
collected.
v Ordered. Reads all records from the first partition, then all records from the second partition, and so
on.
v Round Robin. Reads a record from the first input partition, then from the second partition, and so on.
After reaching the last partition, the operator starts over.

Chapter 28. Difference stage 357

v Sort Merge. Reads records in an order based on one or more columns of the record. This requires you
to select a collecting key column from the Available list.

The Partitioning tab also allows you to specify that data arriving on the input link should be sorted
before the operation is performed. The sort is always carried out within data partitions. If the stage is
partitioning incoming data the sort occurs after the partitioning. If the stage is collecting data, the sort
occurs before the collection. The availability of sorting depends on the partitioning or collecting method
chosen (it is not available for the default auto methods).

Select the check boxes as follows:

v Perform Sort. Select this to specify that data coming in on the link should be sorted. Select the column
or columns to sort on from the Available list.
v Stable. Select this if you want to preserve previously sorted data sets. This is the default.
v Unique. Select this to specify that, if multiple records have identical sorting key values, only one
record is retained. If stable sort is also set, the first record is retained.

If NLS is enabled an additional button opens a dialog box allowing you to select a locale specifying the
collate convention for the sort.

You can also specify sort direction, case sensitivity, whether sorted as ASCII or EBCDIC, and whether null
columns will appear first or last for each column. Where you are using a keyed partitioning method, you
can also specify whether the column is used as a key for sorting, for partitioning, or for both. Select the
column in the Selected list and right-click to invoke the shortcut menu.

Output page
The Output page allows you to specify details about data output from the Difference stage. The
Difference stage can have only one output link.

The General tab allows you to specify an optional description of the output link. The Columns tab
specifies the column definitions of the data. The Mapping tab allows you to specify the relationship
between the columns being input to the Difference stage and the Output columns. The Advanced tab
allows you to change the default buffering settings for the output link.

Details about Difference stage mapping is given in the following section. See ″Stage Editors,″ for a
general description of the other tabs.

Mapping tab
For the Difference stage the Mapping tab allows you to specify how the output columns are derived, i.e.,
what input columns map onto them or how they are generated.

The left pane shows the columns from the before/after data sets plus the DiffCode column. These are
read only and cannot be modified on this tab.

The right pane shows the output columns for each link. This has a Derivations field where you can
specify how the column is derived.You can fill it in by dragging input columns over, or by using the
Auto-match facility. By default the data set columns are mapped automatically. You need to ensure that
there is an output column to carry the change code and that this is mapped to the DiffCode column.

358 Parallel Job Developer Guide

Chapter 29. Compare stage
The Compare stage is a processing stage. It can have two input links and a single output link.

The Compare stage performs a column-by-column comparison of records in two presorted input data
sets. You can restrict the comparison to specified key columns.

The Compare stage does not change the table definition, partitioning, or content of the records in either
input data set. It transfers both data sets intact to a single output data set generated by the stage. The
comparison results are also recorded in the output data set.

We recommend that you use runtime column propagation in this stage and allow WebSphere DataStage
to define the output column schema for you. The stage outputs a data set with three columns:
v result. Carries the code giving the result of the comparison.
v first. A subrecord containing the columns of the first input link.
v second. A subrecord containing the columns of the second input link.

If you specify the output link meta data yourself, you should use fully qualified names for the column
definitions (e.g. first.col1, second.col1 etc.), because WebSphere DataStage will not let you specify two lots
of identical column names.

The stage editor has three pages:

v Stage Page. This is always present and is used to specify general information about the stage.
v Input Page. This is where you specify the details about the single input set from which you are
selecting records.
v Output Page. This is where you specify details about the processed data being output from the stage.

Example Data
This example shows two data sets being compared, and the data set that is output by the Compare stage
when it has compared them.

© Copyright IBM Corp. 2006 359

This is the first data set::

bcol0 bcol1 bcol2 bcol3 bcol4

0 0 0 0 a
1 7 1 1 b
2 2 2 2 c
3 3 3 3 d
4 5 4 4 e
5 2 5 5 f
6 6 6 6 g
7 7 7 7 h
8 8 8 8 i
9 9 9 9 j

This is the second data set:

bcol0 bcol1 bcol2 bcol3 bcol4

0 0 0 0 a
1 1 1 1 b
2 2 2 2 c
3 3 3 3 d
4 4 4 4 e
5 5 5 5 f
6 6 6 6 g
7 7 7 7 h
8 8 8 8 i
9 9 9 9 j

The stage compares on the Key columns bcol1 and bcol4. This is the output data set:

Result First Second

bcol0 bcol1 bcol2 bcol3 bcol4 bcol0 bcol1 bcol2 bcol3 bcol4
0 0 0 0 0 a 0 0 0 0 a
2 1 7 1 1 b 1 1 1 1 b
0 2 2 2 2 c 2 2 2 2 c
0 3 3 3 3 d 3 3 3 3 d
2 4 5 4 4 e 4 4 4 4 e
-1 5 2 5 5 f 5 5 5 5 f
0 6 6 6 6 g 6 6 6 6 g
0 7 7 7 7 h 7 7 7 7 h
0 8 8 8 8 i 8 8 8 8 i
0 9 9 9 9 j 9 9 9 9 j

360 Parallel Job Developer Guide

Must do’s
WebSphere DataStage has many defaults which means that it can be very easy to include Compare stages
in a job. This section specifies the minimum steps to take to get a Compare stage functioning. WebSphere
DataStage provides a versatile user interface, and there are many shortcuts to achieving a particular end,
this section describes the basic method, you will learn where the shortcuts are when you get familiar
with the product.

To use a Compare stage:

v In the Stage page Properties Tab, check that the default settings are suitable for your requirements.
v In the Stage page Link Ordering Tab, specify which of your input links is the first link and which is
the second.

Stage page
The General tab allows you to specify an optional description of the stage. The Properties tab lets you
specify what the stage does. The Advanced tab allows you to specify how the stage executes. The NLS
Locale tab appears if your have NLS enabled on your system. It allows you to select a locale other than
the project default to determine collating rules.

Properties tab
The Properties tab allows you to specify properties which determine what the stage actually does. Some
of the properties are mandatory, although many have default settings. Properties without default settings
appear in the warning color (red by default) and turn black when you supply a value for them.

The following table gives a quick reference list of the properties and their attributes. A more detailed
description of each property follows.

Category/
Property Values Default Mandatory? Repeats? Dependent of
Options/Abort True/False False Y N N/A
On Difference
Options/Warn on True/False False Y N N/A
Record Count
Mismatch
Options/`Equals’ number 0 N N N/A
Value
Options/`First is number 1 N N N/A
Empty’ Value
Options/`Greater number 2 N N N/A
Than’ Value
Options/`Less number -1 N N N/A
Than’ Value
Options/`Second number -2 N N N/A
is Empty’ Value
Options/Key Input Column N/A N Y N/A
Options/Case True/False True N N Key
Sensitive

Chapter 29. Compare stage 361

Options category
Abort on difference

This property forces the stage to abort its operation each time a difference is encountered between two
corresponding columns in any record of the two input data sets. This is False by default, if you set it to
True you cannot set Warn on Record Count Mismatch.

Warn on record count mismatch

This property directs the stage to output a warning message when a comparison is aborted due to a
mismatch in the number of records in the two input data sets. This is False by default, if you set it to
True you cannot set Abort on difference.

`Equals’ value

Allows you to set an alternative value for the code which the stage outputs to indicate two compared
records are equal. This is 0 by default.

`First is empty’ value

Allows you to set an alternative value for the code which the stage outputs to indicate the first record is
empty. This is -2 by default.

`Greater than’ value

Allows you to set an alternative value for the code which the stage outputs to indicate the first record is
greater than the other. This is 1 by default.

`Less than’ value

Allows you to set an alternative value for the code which the stage outputs to indicate the second record
is greater than the other. This is -1 by default.

`Second is empty’ value

Allows you to set an alternative value for the code which the stage outputs to indicate the second record
is empty. This is -2 by default.

Key

Allows you to specify one or more key columns. Only these columns will be compared. Repeat the
property to specify multiple columns. You can use the Column Selection dialog box to select several keys
at once if required. The Key property has a dependent property:
v Case Sensitive
Use this to specify whether each key is case sensitive or not, this is set to True by default, i.e., the
values ″CASE″ and ″case″ in would end up in different groups.

Advanced tab
This tab allows you to specify the following:
v Execution Mode. The stage can execute in parallel mode or sequential mode. In parallel mode the
input data is processed by the available nodes as specified in the Configuration file, and by any node
constraints specified on the Advanced tab. In Sequential mode the entire data set is processed by the
conductor node.

362 Parallel Job Developer Guide

v Combinability mode. This is Auto by default, which allows WebSphere DataStage to combine the
operators that underlie parallel stages so that they run in the same process if it is sensible for this type
of stage.
v Preserve partitioning. This is Propagate by default. It adopts Set or Clear from the previous stage. You
can explicitly select Set or Clear. Select Set to request that next stage in the job should attempt to
maintain the partitioning.
v Node pool and resource constraints. Select this option to constrain parallel execution to the node pool
or pools and/or resource pool or pools specified in the grid. The grid allows you to make choices from
drop down lists populated from the Configuration file.
v Node map constraint. Select this option to constrain parallel execution to the nodes in a defined node
map. You can define a node map by typing node numbers into the text box or by clicking the browse
button to open the Available Nodes dialog box and selecting nodes from there. You are effectively
defining a new node pool for this stage (in addition to any node pools defined in the Configuration
file).

Link Ordering tab

This tab allows you to specify which input link carries the First data set and which carries the Second
data set. Which is categorized as first and which second affects the setting of the comparison code.

By default the first link added will represent the First set. To rearrange the links, choose an input link and
click the up arrow button or the down arrow button.

NLS Locale tab

This appears if you have NLS enabled on your system. It lets you view the current default collate
convention, and select a different one for this stage if required. You can also use a job parameter to
specify the locale, or browse for a file that defines custom collate rules. The collate convention defines the
order in which characters are collated. The Compare stage uses this when it is determining the sort order
for key columns. Select a locale from the list, or click the arrow button next to the list to use a job
parameter or browse for a collate file.

Input page
The Input page allows you to specify details about the incoming data sets. The Compare stage expects
two incoming data sets.

The General tab allows you to specify an optional description of the input link. The Partitioning tab
allows you to specify how incoming data is partitioned before being compared. The Columns tab
specifies the column definitions of incoming data. The Advanced tab allows you to change the default
buffering settings for the input link.

Details about Compare stage partitioning are given in the following section. See ″Stage Editors,″ for a
general description of the other tabs.

Partitioning tab
If you are running the Compare stage in parallel you must ensure that the incoming data is suitably
partitioned and sorted to make a comparison sensible.

The Partitioning tab allows you to specify details about how the incoming data is partitioned or collected
before it is compared. It also allows you to specify that the data should be sorted before being operated
on.

Chapter 29. Compare stage 363

By default the stage partitions in Auto mode. This attempts to work out the best partitioning method
depending on execution modes of current and preceding stages and how many nodes are specified in the
Configuration file.

If the Compare stage is operating in sequential mode, it will first collect the data using the default Auto
collection method.

The Partitioning tab allows you to override this default behavior. The exact operation of this tab depends
on:
v Whether the Compare stage is set to execute in parallel or sequential mode.
v Whether the preceding stage in the job is set to execute in parallel or sequential mode.

If the Compare stage is set to execute in parallel, then you can set a partitioning method by selecting
from the Partition type drop-down list. This will override any current partitioning.

If the Compare stage is set to execute in sequential mode, but the preceding stage is executing in parallel,
then you can set a collection method from the Collector type drop-down list. This will override the
default collection method.

The following partitioning methods are available:

v (Auto). WebSphere DataStage attempts to work out the best partitioning method depending on
execution modes of current and preceding stages and how many nodes are specified in the
Configuration file. This is the default partitioning method for the Compare stage, and will ensure that
incoming data is key partitioned and sorted.
v Entire. Each file written to receives the entire data set.
v Hash. The records are hashed into partitions based on the value of a key column or columns selected
from the Available list.
v Modulus. The records are partitioned using a modulus function on the key column selected from the
Available list. This is commonly used to partition on tag fields.
v Random. The records are partitioned randomly, based on the output of a random number generator.
v Round Robin. The records are partitioned on a round robin basis as they enter the stage.
v Same. Preserves the partitioning already in place.
v DB2. Replicates the DB2 partitioning method of a specific DB2 table. Requires extra properties to be
set. Access these properties by clicking the properties button.
v Range. Divides a data set into approximately equal size partitions based on one or more partitioning
keys. Range partitioning is often a preprocessing step to performing a total sort on a data set. Requires
extra properties to be set. Access these properties by clicking the properties button.

The following Collection methods are available:

v (Auto). This is the default collection method for Compare stages. Normally, when you are using Auto
mode, WebSphere DataStage will eagerly read any row from any input partition as it becomes
available. For the Compare stage, WebSphere DataStage will ensure that the data is sorted as it is
collected.
v Ordered. Reads all records from the first partition, then all records from the second partition, and so
on.
v Round Robin. Reads a record from the first input partition, then from the second partition, and so on.
After reaching the last partition, the operator starts over.
v Sort Merge. Reads records in an order based on one or more columns of the record. This requires you
to select a collecting key column from the Available list.

If you are collecting data, the Partitioning tab also allows you to specify that data arriving on the input
link should be sorted before being collected and compared. The sort is always carried out within data

364 Parallel Job Developer Guide

partitions. The sort occurs before the collection. The availability of sorting depends on the partitioning or
collecting method chosen (it is not available for the default auto methods).

Select the check boxes as follows:

v Perform Sort. Select this to specify that data coming in on the link should be sorted. Select the column
or columns to sort on from the Available list.
v Stable. Select this if you want to preserve previously sorted data sets. This is the default.
v Unique. Select this to specify that, if multiple records have identical sorting key values, only one
record is retained. If stable sort is also set, the first record is retained.

If NLS is enabled an additional button opens a dialog box allowing you to select a locale specifying the
collate convention for the sort.

You can also specify sort direction, case sensitivity, whether sorted as ASCII or EBCDIC, and whether null
columns will appear first or last for each column. Where you are using a keyed partitioning method, you
can also specify whether the column is used as a key for sorting, for partitioning, or for both. Select the
column in the Selected list and right-click to invoke the shortcut menu.

Output page
The Output page allows you to specify details about data output from the Compare stage. The Compare
stage can have only one output link.

The General tab allows you to specify an optional description of the output link. The Columns tab
specifies the column definitions of the data. The Advanced tab allows you to change the default buffering
settings for the output link.

See ″Stage Editors,″ for a general description of the tabs.

Chapter 29. Compare stage 365

366 Parallel Job Developer Guide
Chapter 30. Encode Stage
The Encode stage is a processing stage. It encodes a data set using a UNIX encoding command, such as
gzip, that you supply. The stage converts a data set from a sequence of records into a stream of raw
binary data. The companion Decode stage reconverts the data stream to a data set (see Chapter 31,
“Decode stage,” on page 371).

An encoded data set is similar to an ordinary one, and can be written to a data set stage. You cannot use
an encoded data set as an input to stages that performs column-based processing or re-orders rows, but
you can input it to stages such as Copy. You can view information about the data set in the data set
viewer, but not the data itself. You cannot repartition an encoded data set, and you will be warned at
runtime if your job attempts to do that.

As the output is always a single stream, you do not have to define meta data for the output link

The stage editor has three pages:

v Stage Page. This is always present and is used to specify general information about the stage.
v Input Page. This is where you specify the details about the single input set from which you are
selecting records.
v Output Page. This is where you specify details about the processed data being output from the stage.

Must do’s
WebSphere DataStage has many defaults which means that it can be very easy to include Encode stages
in a job. This section specifies the minimum steps to take to get an Encode stage functioning. WebSphere
DataStage provides a versatile user interface, and there are many shortcuts to achieving a particular end,
this section describes the basic method, you will learn where the shortcuts are when you get familiar
with the product.

To use an Encode stage:

v In the Stage Page Properties Tab, specify the UNIX command that will be used to encode the data,
together with any required arguments. The command should expect its input from STDIN and send its
output to STDOUT.

Stage page
The General tab allows you to specify an optional description of the stage. The Properties tab lets you
specify what the stage does. The Advanced tab allows you to specify how the stage executes.

© Copyright IBM Corp. 2006 367

Properties tab
The Properties tab allows you to specify properties which determine what the stage actually does. This
stage only has one property and you must supply a value for this. The property appears in the warning
color (red by default) until you supply a value.

Category/
Property Values Default Mandatory? Repeats? Dependent of
Options/ Command Line N/A Y N N/A
Command Line

Options category
Command line

Specifies the command line used for encoding the data set. The command line must configure the UNIX
command to accept input from standard input and write its results to standard output. The command
must be located in your search path and be accessible by every processing node on which the Encode
stage executes.

Advanced tab
This tab allows you to specify the following:
v Execution Mode. The stage can execute in parallel mode or sequential mode. In parallel mode the
input data is processed by the available nodes as specified in the Configuration file, and by any node
constraints specified on the Advanced tab. In Sequential mode the entire data set is processed by the
conductor node.
v Combinability mode. This is Auto by default, which allows WebSphere DataStage to combine the
operators that underlie parallel stages so that they run in the same process if it is sensible for this type
of stage.
v Preserve partitioning. This is Set by default to request that next stage in the job should attempt to
maintain the partitioning.
v Node pool and resource constraints. Select this option to constrain parallel execution to the node pool
or pools and/or resource pool or pools specified in the grid. The grid allows you to make choices from
drop down lists populated from the Configuration file.
v Node map constraint. Select this option to constrain parallel execution to the nodes in a defined node
map. You can define a node map by typing node numbers into the text box or by clicking the browse
button to open the Available Nodes dialog box and selecting nodes from there. You are effectively
defining a new node pool for this stage (in addition to any node pools defined in the Configuration
file).

Input page
The Input page allows you to specify details about the incoming data sets. The Encode stage can only
have one input link.

The General tab allows you to specify an optional description of the input link. The Partitioning tab
allows you to specify how incoming data is partitioned before being encoded. The Columns tab specifies
the column definitions of incoming data. The Advanced tab allows you to change the default buffering
settings for the input link.

Details about Encode stage partitioning are given in the following section. See ″Stage Editors,″ for a
general description of the other tabs.

368 Parallel Job Developer Guide

Partitioning tab
The Partitioning tab allows you to specify details about how the incoming data is partitioned or collected
before it is encoded. It also allows you to specify that the data should be sorted before being operated on.

By default the stage partitions in Auto mode. This attempts to work out the best partitioning method
depending on execution modes of current and preceding stages and how many nodes are specified in the
Configuration file.

If the Encode stage is operating in sequential mode, it will first collect the data using the default Auto
collection method.

The Partitioning tab allows you to override this default behavior. The exact operation of this tab depends
on:
v Whether the Encode stage is set to execute in parallel or sequential mode.
v Whether the preceding stage in the job is set to execute in parallel or sequential mode.

If the Encode stage is set to execute in parallel, then you can set a partitioning method by selecting from
the Partition type drop-down list. This will override any current partitioning.

If the Encode stage is set to execute in sequential mode, but the preceding stage is executing in parallel,
then you can set a collection method from the Collector type drop-down list. This will override the
default collection method.

The following partitioning methods are available:

v (Auto). WebSphere DataStage attempts to work out the best partitioning method depending on
execution modes of current and preceding stages and how many nodes are specified in the
Configuration file. This is the default partitioning method for the Encode stage.
v Entire. Each file written to receives the entire data set.
v Hash. The records are hashed into partitions based on the value of a key column or columns selected
from the Available list.
v Modulus. The records are partitioned using a modulus function on the key column selected from the
Available list. This is commonly used to partition on tag fields.
v Random. The records are partitioned randomly, based on the output of a random number generator.
v Round Robin. The records are partitioned on a round robin basis as they enter the stage.
v Same. Preserves the partitioning already in place.
v DB2. Replicates the DB2 partitioning method of a specific DB2 table. Requires extra properties to be
set. Access these properties by clicking the properties button.
v Range. Divides a data set into approximately equal size partitions based on one or more partitioning
keys. Range partitioning is often a preprocessing step to performing a total sort on a data set. Requires
extra properties to be set. Access these properties by clicking the properties button.

The following Collection methods are available:

v (Auto). This is the default collection method for Encode stages. Normally, when you are using Auto
mode, WebSphere DataStage will eagerly read any row from any input partition as it becomes
available.
v Ordered. Reads all records from the first partition, then all records from the second partition, and so
on.
v Round Robin. Reads a record from the first input partition, then from the second partition, and so on.
After reaching the last partition, the operator starts over.
v Sort Merge. Reads records in an order based on one or more columns of the record. This requires you
to select a collecting key column from the Available list.

Chapter 30. Encode Stage 369

The Partitioning tab also allows you to specify that data arriving on the input link should be sorted
before being encoded. The sort is always carried out within data partitions. If the stage is partitioning
incoming data the sort occurs after the partitioning. If the stage is collecting data, the sort occurs before
the collection. The availability of sorting depends on the partitioning or collecting method chosen (it is
not available for the default auto methods).

Select the check boxes as follows:

v Perform Sort. Select this to specify that data coming in on the link should be sorted. Select the column
or columns to sort on from the Available list.
v Stable. Select this if you want to preserve previously sorted data sets. This is the default.
v Unique. Select this to specify that, if multiple records have identical sorting key values, only one
record is retained. If stable sort is also set, the first record is retained.

If NLS is enabled an additional button opens a dialog box allowing you to select a locale specifying the
collate convention for the sort.

You can also specify sort direction, case sensitivity, whether sorted as ASCII or EBCDIC, and whether null
columns will appear first or last for each column. Where you are using a keyed partitioning method, you
can also specify whether the column is used as a key for sorting, for partitioning, or for both. Select the
column in the Selected list and right-click to invoke the shortcut menu.

Output page
The Output page allows you to specify details about data output from the Encode stage. The Encode
stage can have only one output link.

The General tab allows you to specify an optional description of the output link. The Columns tab allows
you to specify column definitions for the data (although this is optional for an encode stage). The
Advanced tab allows you to change the default buffering settings for the output link.

See ″Stage Editors,″ for a general description of these tabs.

370 Parallel Job Developer Guide

Chapter 31. Decode stage
The Decode stage is a processing stage. It decodes a data set using a UNIX decoding command, such as
gzip, that you supply. It converts a data stream of raw binary data into a data set. Its companion stage,
Encode, converts a data set from a sequence of records to a stream of raw binary data (see Chapter 30,
“Encode Stage,” on page 367).

As the input is always a single stream, you do not have to define meta data for the input link.

The stage editor has three pages:

v Stage Page. This is always present and is used to specify general information about the stage.
v Input Page. This is where you specify the details about the single input set from which you are
selecting records.
v Output Page. This is where you specify details about the processed data being output from the stage.

Must do’s
WebSphere DataStage has many defaults which means that it can be very easy to include Decode stages
in a job. This section specifies the minimum steps to take to get a Decode stage functioning. WebSphere
DataStage provides a versatile user interface, and there are many shortcuts to achieving a particular end,
this section describes the basic method, you will learn where the shortcuts are when you get familiar
with the product.

To use a Decode stage:

v In the Stage Page Properties Tab, specify the UNIX command that will be used to decode the data,
together with any required arguments. The command should expect its input from STDIN and send its
output to STDOUT.

Stage page
The General tab allows you to specify an optional description of the stage. The Properties tab lets you
specify what the stage does. The Advanced tab allows you to specify how the stage executes.

Properties tab
The Properties tab allows you to specify properties which determine what the stage actually does. This
stage only has one property and you must supply a value for this. The property appears in the warning
color (red by default) until you supply a value.

© Copyright IBM Corp. 2006 371

Category/
Property Values Default Mandatory? Repeats? Dependent of
Options/ Command Line N/A Y N N/A
Command Line

Options category
Command line

Specifies the command line used for decoding the data set. The command line must configure the UNIX
command to accept input from standard input and write its results to standard output. The command
must be located in the search path of your application and be accessible by every processing node on
which the Decode stage executes.

Advanced tab
This tab allows you to specify the following:
v Execution Mode. The stage can execute in parallel mode or sequential mode. In parallel mode the
input data is processed by the available nodes as specified in the Configuration file, and by any node
constraints specified on the Advanced tab. In Sequential mode the entire data set is processed by the
conductor node.
v Combinability mode. This is Auto by default, which allows WebSphere DataStage to combine the
operators that underlie parallel stages so that they run in the same process if it is sensible for this type
of stage.
v Preserve partitioning. This is Propagate by default. It adopts Set or Clear from the previous stage. You
can explicitly select Set or Clear. Select Set to request that next stage in the job should attempt to
maintain the partitioning.
v Node pool and resource constraints. Select this option to constrain parallel execution to the node pool
or pools and/or resource pool or pools specified in the grid. The grid allows you to make choices from
drop down lists populated from the Configuration file.
v Node map constraint. Select this option to constrain parallel execution to the nodes in a defined node
map. You can define a node map by typing node numbers into the text box or by clicking the browse
button to open the Available Nodes dialog box and selecting nodes from there. You are effectively
defining a new node pool for this stage (in addition to any node pools defined in the Configuration
file).

Input page
The Input page allows you to specify details about the incoming data sets. The Decode stage expects a
single incoming data set.

The General tab allows you to specify an optional description of the input link. The Partitioning tab
allows you to specify how incoming data is partitioned before being decoded. The Columns tab specifies
the column definitions of incoming data. The Advanced tab allows you to change the default buffering
settings for the input link.

Details about Compare stage partitioning are given in the following section. See ″Stage Editors,″ for a
general description of the other tabs.

Partitioning tab
The Partitioning tab allows you to specify details about how the incoming data is partitioned or collected
before it is decoded. It also allows you to specify that the data should be sorted before being operated on.

372 Parallel Job Developer Guide

The Decode stage partitions in Same mode and this cannot be overridden.

If the Decode stage is set to execute in sequential mode, but the preceding stage is executing in parallel,
then you can set a collection method from the Collector type drop-down list. This will override the
default collection method.

The following Collection methods are available:

v (Auto). This is the default collection method for Decode stages. Normally, when you are using Auto
mode, WebSphere DataStage will eagerly read any row from any input partition as it becomes
available.
v Ordered. Reads all records from the first partition, then all records from the second partition, and so
on.
v Round Robin. Reads a record from the first input partition, then from the second partition, and so on.
After reaching the last partition, the operator starts over.
v Sort Merge. Reads records in an order based on one or more columns of the record. This requires you
to select a collecting key column from the Available list.

Output page
The Output page allows you to specify details about data output from the Decode stage. The Decode
stage can have only one output link.

The General tab allows you to specify an optional description of the output link. The Columns tab
specifies the column definitions for the decoded data.

See ″Stage Editors,″ for a general description of the tabs.

Chapter 31. Decode stage 373

374 Parallel Job Developer Guide
Chapter 32. Switch stage
The Switch stage is a processing stage. It can have a single input link, up to 128 output links and a single
rejects link.

The Switch stage takes a single data set as input and assigns each input row to an output data set based
on the value of a selector field. The Switch stage performs an operation analogous to a C switch
statement, which causes the flow of control in a C program to branch to one of several cases based on the
value of a selector variable. Rows that satisfy none of the cases are output on the rejects link.

The stage editor has three pages:

v Stage Page. This is always present and is used to specify general information about the stage.
v Input Page. This is where you specify the details about the single input set from which you are
selecting rows.
v Output Page. This is where you specify details about the processed data being output from the stage.

Example
The example Switch stage implements the following switch statement:
switch (selector)
{
case 0: // if selector = 0,
// write record to output data set 0
break;
case 10: // if selector = 10,
// write record to output data set 1
break;
case 12: // if selector = discard value (12)
// skip record

© Copyright IBM Corp. 2006 375

 break;
case default: // if selector is invalid,
// send row down reject link
};

The meta data input to the switch stage is as follows:

Column name SQL Type

select Integer
col1 Char
col2 Char
col3 Char

The column called Select is the selector; the value of this determines which output links the rest of the
row will be output to. The properties of the stage are:

Must do’s
WebSphere DataStage has many defaults which means that it can be very easy to include Switch stages in
a job. This section specifies the minimum steps to take to get a Switch stage functioning. WebSphere
DataStage provides a versatile user interface, and there are many shortcuts to achieving a particular end,
this section describes the basic method, you will learn where the shortcuts are when you get familiar
with the product.

To use a Switch stage:

v In the Stage page Properties Tab, under the Input category choose the Selector mode:
– User-defined Mapping. This is the default, and means that you must provide explicit mappings
from case values to outputs. If you use this mode you specify the switch expression under the
User-defined Mapping category.

376 Parallel Job Developer Guide

 – Auto. This can be used where there are as many distinct selector values as there are output links.
– Hash. The incoming rows are hashed on the selector column modulo the number of output links
and assigned to an output link accordingly.
In all cases you need to use the Selector property to specify the input column that the switch is
performed on. You can also specify whether the column is case sensitive or not. The other properties
depend on which mode you have chosen:
– If you have chosen the User-defined mapping mode, under the User-defined Mapping category
specify the case expression in the case property. Under the Option category, select the If not found
property to specify what action the stage takes if the column value does not correspond to any of
the cases. Choose from Fail to have the job fail, Drop to drop the row, or Output to output it on the
reject link.
– If you have chosen the Auto mode, Under the Option category, select the If not found property to
specify what action the stage takes if the column value does not correspond to any of the cases.
Choose from Fail to have the job fail, Drop to drop the row, or Output to output it on the reject link.
– If you have chose the Hash mode there are no other properties to fill in.
v In the Stage page Link Ordering Tab, specify the order in which the output links are processed.
v In the Output page Mapping Tab check that the input columns are mapping onto the output columns
as you expect. The mapping is carried out according to what you specified in the Properties tab.

Stage page
The General tab allows you to specify an optional description of the stage. The Properties tab lets you
specify what the stage does. The Advanced tab allows you to specify how the stage executes. The Link
Ordering tab allows you to specify what order the output links are processed in. The NLS Locale tab
appears if your have NLS enabled on your system. It allows you to select a locale other than the project
default to determine collating rules.

Properties tab
The Properties tab allows you to specify properties which determine what the stage actually does. Some
of the properties are mandatory, although many have default settings. Properties without default settings
appear in the warning color (red by default) and turn black when you supply a value for them.

The following table gives a quick reference list of the properties and their attributes. A more detailed
description of each property follows.

Category/
Property Values Default Mandatory? Repeats? Dependent of
Input/Selector Input Column N/A Y N N/A
Input/Case True/False True N N Selector
Sensitive
Input/Selector User-defined User-defined Y N N/A
Mode mapping/Auto/ mapping
Hash
User-defined String N/A Y (if Selector Y N/A
Mapping/Case Mode =
User-defined
mapping)
Options/If not Pathname N/A Y (if Column N N/A
found Method = Schema
file)

Chapter 32. Switch stage 377

Category/
Property Values Default Mandatory? Repeats? Dependent of
Options/Discard True/False False N N N/A
Value

Input category
Selector

Specifies the input column that the switch applies to.

Case sensitive

Specifies whether the column is case sensitive or not.

Selector mode

Specifies how you are going to define the case statements for the switch. Choose between:
v User-defined Mapping. This is the default, and means that you must provide explicit mappings from
case values to outputs. If you use this mode you specify the switch expression under the User-defined
Mapping category.
v Auto. This can be used where there are as many distinct selector values as there are output links.
v Hash. The incoming rows are hashed on the selector column modulo the number of output links and
assigned to an output link accordingly.

User-defined mapping category

Case

This property appears if you have chosen a Selector Mode of User-defined Mapping. Specify the case
expression in the case property. It has the following format:
Selector_Value[= Output_Link_Label_Number]

You must specify a selector value for each value of the input column that you want to direct to an output
column. Repeat the Case property to specify multiple values. You can omit the output link label if the
value is intended for the same output link as the case previously specified. For example, the case
statements:
1990=0
1991
1992
1993=1
1994=1

would cause the rows containing the dates 1990, 1991, or 1992 in the selector column to be routed to
output link 0, and the rows containing the dates 1993 to 1994 to be routed to output link 1.

Options category
If not found

Specifies the action to take if a row fails to match any of the case statements. This does not appear if you
choose a Selector Mode of Hash. Otherwise, choose between:
v Fail. Causes the job to fail.
v Drop. Drops the row.
v Output. Routes the row to the Reject link.

378 Parallel Job Developer Guide

Discard value

You can use this property in conjunction with the case property to specify that rows containing certain
values in the selector column will always be discarded. For example, if you defined the following case
statement:
1995=5

and set the Discard Value property to 5, all rows containing 1995 in the selector column would be routed
to link 5 which has been specified as the discard link and so will be dropped.

Advanced tab
This tab allows you to specify the following:
v Execution Mode. The stage can execute in parallel mode or sequential mode. In parallel mode the
input data is processed by the available nodes as specified in the Configuration file, and by any node
constraints specified on the Advanced tab. In Sequential mode the entire data set is processed by the
conductor node.
v Combinability mode. This is Auto by default, which allows WebSphere DataStage to combine the
operators that underlie parallel stages so that they run in the same process if it is sensible for this type
of stage.
v Preserve partitioning. This is Propagate by default. It adopts Set or Clear from the previous stage. You
can explicitly select Set or Clear. Select Set to request that next stage in the job should attempt to
maintain the partitioning.
v Node pool and resource constraints. Select this option to constrain parallel execution to the node pool
or pools and/or resource pool or pools specified in the grid. The grid allows you to make choices from
drop down lists populated from the Configuration file.
v Node map constraint. Select this option to constrain parallel execution to the nodes in a defined node
map. You can define a node map by typing node numbers into the text box or by clicking the browse
button to open the Available Nodes dialog box and selecting nodes from there. You are effectively
defining a new node pool for this stage (in addition to any node pools defined in the Configuration
file).

Link Ordering tab

This tab allows you to specify which output links are associated with which link labels.

NLS Locale tab

This appears if you have NLS enabled on your system. It lets you view the current default collate
convention, and select a different one for this stage if required. You can also use a job parameter to
specify the locale, or browse for a file that defines custom collate rules. The collate convention defines the
order in which characters are collated. The Switch stage uses this when evaluating case statements. Select
a locale from the list, or click the arrow button next to the list to use a job parameter or browse for a
collate file.

Input page
The Input page allows you to specify details about the incoming data sets. The Switch stage expects one
incoming data set.

Chapter 32. Switch stage 379

The General tab allows you to specify an optional description of the input link. The Partitioning tab
allows you to specify how incoming data is partitioned before being switched. The Columns tab specifies
the column definitions of incoming data. The Advanced tab allows you to change the default buffering
settings for the input link.

Details about Switch stage partitioning are given in the following section. See ″Stage Editors,″ for a
general description of the other tabs.

Partitioning tab
The Partitioning tab allows you to specify details about how the incoming data is partitioned or collected
before it is switched. It also allows you to specify that the data should be sorted before being operated
on.

By default the stage partitions in Auto mode. This attempts to work out the best partitioning method
depending on execution modes of current and preceding stages and how many nodes are specified in the
Configuration file.

If the Column Import stage is operating in sequential mode, it will first collect the data using the default
Auto collection method.

The Partitioning tab allows you to override this default behavior. The exact operation of this tab depends
on:
v Whether the Switch stage is set to execute in parallel or sequential mode.
v Whether the preceding stage in the job is set to execute in parallel or sequential mode.

If the Switch stage is set to execute in parallel, then you can set a partitioning method by selecting from
the Partition type drop-down list. This will override any current partitioning.

If the Switch stage is set to execute in sequential mode, but the preceding stage is executing in parallel,
then you can set a collection method from the Collector type drop-down list. This will override the
default collection method.

The following partitioning methods are available:

v (Auto). WebSphere DataStage attempts to work out the best partitioning method depending on
execution modes of current and preceding stages and how many nodes are specified in the
Configuration file. This is the default partitioning method for the Switch stage.
v Entire. Each file written to receives the entire data set.
v Hash. The records are hashed into partitions based on the value of a key column or columns selected
from the Available list.
v Modulus. The records are partitioned using a modulus function on the key column selected from the
Available list. This is commonly used to partition on tag fields.
v Random. The records are partitioned randomly, based on the output of a random number generator.
v Round Robin. The records are partitioned on a round robin basis as they enter the stage.
v Same. Preserves the partitioning already in place.
v DB2. Replicates the DB2 partitioning method of a specific DB2 table. Requires extra properties to be
set. Access these properties by clicking the properties button.
v Range. Divides a data set into approximately equal size partitions based on one or more partitioning
keys. Range partitioning is often a preprocessing step to performing a total sort on a data set. Requires
extra properties to be set. Access these properties by clicking the properties button.

The following Collection methods are available:

380 Parallel Job Developer Guide

v (Auto). This is the default collection method for Switch stages. Normally, when you are using Auto
mode, WebSphere DataStage will eagerly read any row from any input partition as it becomes
available.
v Ordered. Reads all records from the first partition, then all records from the second partition, and so
on.
v Round Robin. Reads a record from the first input partition, then from the second partition, and so on.
After reaching the last partition, the operator starts over.
v Sort Merge. Reads records in an order based on one or more columns of the record. This requires you
to select a collecting key column from the Available list.

The Partitioning tab also allows you to specify that data arriving on the input link should be sorted
before being imported. The sort is always carried out within data partitions. If the stage is partitioning
incoming data the sort occurs after the partitioning. If the stage is collecting data, the sort occurs before
the collection. The availability of sorting depends on the partitioning or collecting method chosen (it is
not available with the default Auto methods).

Select the check boxes as follows:

v Perform Sort. Select this to specify that data coming in on the link should be sorted. Select the column
or columns to sort on from the Available list.
v Stable. Select this if you want to preserve previously sorted data sets. This is the default.
v Unique. Select this to specify that, if multiple records have identical sorting key values, only one
record is retained. If stable sort is also set, the first record is retained.

If NLS is enabled an additional button opens a dialog box allowing you to select a locale specifying the
collate convention for the sort.

You can also specify sort direction, case sensitivity, whether sorted as ASCII or EBCDIC, and whether null
columns will appear first or last for each column. Where you are using a keyed partitioning method, you
can also specify whether the column is used as a key for sorting, for partitioning, or for both. Select the
column in the Selected list and right-click to invoke the shortcut menu.

Output page
The Output page allows you to specify details about data output from the Switch stage. The Switch stage
can have up to 128 output links, and can also have a reject link carrying rows that have been rejected.
Choose the link you are working on from the Output name drop-down list.

The General tab allows you to specify an optional description of the output link. The Columns tab
specifies the column definitions of the data. The Mapping tab allows you to specify the relationship
between the columns being input to the Switch stage and the Output columns. The Advanced tab allows
you to change the default buffering settings for the output links.

Details about Switch stage mapping is given in the following section. See ″Stage Editors,″ for a general
description of the other tabs.

Mapping tab
For the Switch stage the Mapping tab allows you to specify how the output columns are derived.

The left pane shows the columns that have been switched. These are read only and cannot be modified
on this tab.

The right pane shows the output columns for each link.

Chapter 32. Switch stage 381

Reject link
You cannot change the details of a Reject link. The link uses the column definitions for the link rejecting
the data rows.

382 Parallel Job Developer Guide

Chapter 33. FTP Enterprise Stage
The FTP Enterprise stage transfers multiple files in parallel. These are sets of files that are transferred
from one or more FTP servers into WebSphere DataStage or from WebSphere DataStage to one or more
FTP servers. The source or target for the file is identified by a URI (Universal Resource Identifier). The
FTP Enterprise stage invokes an FTP client program and transfers files to or from a remote host using the
FTP Protocol.

Accessing Files from a Remote Host:

Transferring Files from a Local Sequential file to a Remote Host:

When you edit an FTP Enterprise stage, the FTP stage editor appears. This is based on the generic stage
editor.

The stage editor has up to three pages, depending on whether you are accessing or transferring a file:
v Stage Page. This is always present and is used to specify general information about the stage.
v Input Link. This is present when you are accessing files from a remote host. Specify details about the
input link here.
v Output Link. This is present when you are transferring data sets to a file. Specify details about the
output link here.

Restartability
You can specify that the FTP operation runs in restartable mode. To do this you set the stage properties
as follows:
1. Specify a restartable mode of restartable transfer.
2. Specify a unique job id for the transfer
3. Optionally specify a checkpoint directory for the transfer directory (if you do not specify a checkpoint
directory, the current working directory is used)

© Copyright IBM Corp. 2006 383

When you run the job that performs the FTP operation, information about the transfer is written to a
restart directory identified by the job id located in the checkpoint directory prefixed with the string
″pftp_jobid_″. For example, if you specify a job_id of 100 and a checkpoint directory of
/home/bgamsworth/checkpoint the files would be written to /home/bgamsworth/checkpoint/pftp_jobid_100.

If the FTP operation does not succeed, you can rerun the same job with the restartable mode set to restart
transfer or abandon transfer. For a production environment you could build a job sequence that
performed the transfer, then tested whether it was successful. If it was not another job in the seqence
could use an FTP stage with the restart transfer option to attempt the transfer again using the
information in the restart directory. .

For get operations, WebSphere DataStage reinitiates the FTP transfer at the file boundary. The transfer of
the files that failed half way is restarted from the beginning or zero file location. The file URIs that were
transferred completely are not transferred again. Subsequently, the downloaded URIs are imported to the
dataset from the temporary folder path.

If the operation repeatedly fails, you can use the abandon transfer option to abandon the transfer and
clear the temporary restart directory.

Must Do’s
WebSphere DataStage has many defaults, which means that it is easy to include FTP Enterprise stages in
a job. This section specifies the minimum steps required to get an FTP stage functioning. WebSphere
DataStage provides a versatile user interface, with many shortcuts available to achieve a particular end.
This section describes the basic method. You will learn where the shortcuts are when you get familiar
with the product.

The steps required depend on whether you are using the FTP Enterprise stage to access or transfer a file.

Transferring Data to a Remote Host Using the FTP Enterprise Stage

In the Input pageProperties tab:
1. Specify the URI that the file will be put to. You can specify multiple URIs if required. You can specify
an absolute or relative pathname, see ″URI″ for details of syntax.
2. Ensure column meta data has been specified for the files. (You can achieve this via a schema file if
required.)

Accessing Data from a Remote Host Using the FTP Enterprise Stage
In the Output pageProperties tab:
1. Specify the URI that the file will be taken from via a get operation. You can specify multiple URIs if
required. You can also use a wildcard character to retrieve multiple files. You can specify an absolute
or relative pathname, see ″URI″ for details of syntax.
2. Ensure column meta data has been specified for the files. (You can achieve this via a schema file if
required.)

Stage Page
The General tab allows you to specify an optional description of the stage. The Properties tab lets you
specify what the stage does. The Advanced tab allows you to specify how the stage executes. Use the
NLS Map (National Language Support) tab to define a character set map for the FTP Enterprise stage.

384 Parallel Job Developer Guide

Advanced tab
This tab allows you to specify the following:
v Execution Mode. The stage can execute in parallel mode or sequential mode. In parallel mode the
input data is processed by the available nodes as specified in the Configuration file, and by any node
constraints specified on the Advanced tab. In Sequential mode the entire data set is processed by the
conductor node.
v Combinability mode. This is Auto by default, which allows WebSphere DataStage to combine the
operators that underlie parallel stages so that they run in the same process if it is sensible for this type
of stage.
v Preserve partitioning. This is Propagate by default. The stage has a mandatory partitioning method of
Same, this overrides the preserve partitioning flag and so the partitioning of the incoming data is
always preserved.
v Node pool and resource constraints. Select this option to constrain parallel execution to the node pool
or pools and/or resource pool or pools specified in the grid. The grid allows you to make choices from
drop down lists populated from the Configuration file.
v Node map constraint. Select this option to constrain parallel execution to the nodes in a defined node
map. You can define a node map by typing node numbers into the text box or by clicking the browse
button to open the Available Nodes dialog box and selecting nodes from there. You are effectively
defining a new node pool for this stage (in addition to any node pools defined in the Configuration
file).

NLS Map Tab

Use the NLS Map (National Language Support) tab to define a character set map for the FTP Enterprise
stage. This overrides the default character map set for the project or the job. You can specify that the map
be supplied as a job parameter if required. You can also select Allow per-column mapping. You can
specify character set maps for individual columns within the data processed by the FTP Enterprise stage.
An extra property, NLS Map, appears in the Columns grid, but note that only ustring data types allow
you to set an NLS Map value.

Input Page
The Input page allows you to specify details about how the stage transfers files to a remote host using
FTP. The FTP Enterprise stage can have only one input link, but this can write to multiple files.

The General tab allows you to specify an optional description of the input link. The Properties tab allows
you to specify details of exactly what the link does. The Partitioning tab allows you to specify how
incoming data is partitioned before being written to the file or files. The Columns tab specifies the
column definitions of data being written. The Advanced tab allows you to change the default buffering
settings for the input link.

Details about FTP Enterprise stage properties and partitioning are given in the following sections. See
../concepts/c_deeref_Stage_Editors.dita, ″Stage Editors,″ for a general description of the other tabs.

Properties Tab
Use the Properties tab to specify properties, which determine what the stage actually does. The available
properties are displayed in a tree structure. They are divided into categories to help you find your way
around them. All the mandatory properties are included in the tree by default and cannot be removed.
Required properties (i.e. which do not have a default value) are shown in a warning color (red by
default) but change to black when you have set a value.

Chapter 33. FTP Enterprise Stage 385

The following table gives a quick reference list of the properties and their attributes.

Category/
Property Values Default Mandatory? Repeats? Dependent of
Target/ URI Pathname N/A Y Y N/A
Target/URI/ String N/A N N URI
Open command
Connection /ftp Pathname ftp N N N/A
command
Connection/ Encrypted N/A N Y N/A
Password
Connection/ String N/A N Y N/A
User Name
Options/ Force Yes/No No N N N/A
Parallelism
Options/ Yes/No No N N N/A
Overwrite
Options/ Abandon Restartable N Y N/A
Restartable mode Transfer/ Transfer
Restart
Transfer/
Restartable
Transfer
Options/ Pathname N/A N N Restartable Mode
Restartable
Mode/
Checkpointdir
Options/ Integer 1 N N Restartable Mode
Restartable
Mode/ Job Id
Options/ Pathname N/A N N N/A
Schema file
Options/ Binary/ASCII Binary N N N/A
Transfer Type
Transfer FTP/Secure FTP N N N/A
Protocol/ FTP (SFTP)
Transfer Mode

Target Category
Specify URI and, if required, Open command.

URI

Is a pathname connecting the Stage to a target file on a remote host. It has the Open dependent property.
You can repeat this property to specify multiple URIs. You can specify an absolute or a relative
pathname.

The syntax for a relative path is:

ftp://host/path/filename

Where path is the relative path of the user’s home directory.

386 Parallel Job Developer Guide

The syntax for an absolute path is:
ftp://host//path/filename

While connecting to the mainframe system, the syntax for an absolute path is:
ftp://host/\’path.filename\’

The syntax for connecting to the mainframe system through USS (Unix System Services) is:
ftp://host//path/filename

Where path is the absolute path of the user’s home directory.

Open command

Is required if you perform any operation besides navigating to the directory where the file exists. There
can be multiple Open commands. This is a dependent property of URI.

Connection Category
Specify the ftp Command, Password and User Name. Only one ftp command can be specified, but
multiple passwords and user names can be specified.

ftp command

Is an optional command that you can specify if you do not want to use the default ftp command. For
example, you could specify /opt/gnu/bin/wuftp. You can enter the path of the command (on the server)
directly in this field. You can also specify a job parameter if you want to be able to specify the ftp
command at run time.

User Name

Specify the user name for the transfer. You can enter it directly in this field, or you can specify a job
parameter if you want to be able to specify the user name at run time. You can specify multiple user
names. User1 corresponds to URI1 and so on. When the number of users is less than the number of URIs,
the last user name is set for remaining URIs

If no User Name is specified, the FTP Enterprise Stage tries to use .netrc file in the home directory.

Password

Enter the password in this field. You can also specify a job parameter if you want to be able to specify
the password at run time. Specify a password for each user name. Password1 corresponds to URI1. When
the number of passwords is less than the numbers of URIs, the last password is set for the remaining
URIs.

Transfer Protocol

Select the type of FTP service to transfer files between computers. You can choose either FTP or Secure
FTP (SFTP).

FTP

Select this option if you want to transfer files using the standard FTP protocol. This is a nonsecure
protocol. By default FTP enterprise stage uses this protocol to transfer files.

Chapter 33. FTP Enterprise Stage 387

Secure FTP (SFTP)

Select this option if you want to transfer files between computers in a secured channel. Secure FTP (SFTP)
uses the SSH (Secured Shell) protected channel for data transfer between computers over a nonsecure
network such as a TCP/IP network. Before you can use SFTP to transfer files, you should configure the
SSH connection without any pass phrase for RSA authentication.

Options Category
Force Parallelism

You can set either Yes or No. In general, the FTP Enterprise stage tries to start as many processes as
needed to transfer the n files in parallel. However, you can force the parallel transfer of data by
specifying this property to yes. This allows m number of processes at a time where m is the number
specified in WebSphere DataStage configuration file. If m is less than n, then the stage waits to transfer
the first m files and then start the next m until n files are transferred.

When you set Force Parallelism to Yes, you should only give one URI.

Overwrite

Set this option to have any existing files overwritten by this transfer.

Restartable Mode

When you specify a restartable mode of Restartable transfer, WebSphere DataStage creates a directory for
recording information about the transfer in a restart directory. If the transfer fails, you can run an
identical job with the restartable mode property set to Restart transfer, which will reattempt the transfer.
If the transfer repeatedly fails, you can run an identical job with the restartable mode option set to
Abandon transfer, which will delete the restart directory. For more details, see ″Restartability″ .
Restartable mode has the following dependent properties:
v Job Id
Identifies a restartable transfer job. This is used to name the restart directory.
v Checkpoint directory
Optionally specifies a checkpoint directory to contain restart directories. If you do not specify this, the
current working directory is used.

For example, if you specify a job_id of 100 and a checkpoint directory of /home/bgamsworth/checkpoint the
files would be written to /home/bgamsworth/checkpoint/pftp_jobid_100.

Schema file

Contains a schema for storing data. Setting this option overrides any settings on the Columns tab. You
can enter the path name of a schema file, or specify a job parameter, so the schema file name can be
specified at run time.

Transfer Type

Select a data transfer type to transfer files between computers. You can select either the Binary or ASCII
mode of data transfer. The default data transfer mode is binary.

Partitioning Tab
Use the Partitioning tab to specify details about how the incoming data is partitioned or collected before
it is operated on. Use it also to specify whether the data should be sorted before being operated on. By
default, most stages partition in Auto mode. This mode attempts to work out the best partitioning

388 Parallel Job Developer Guide

method depending on execution modes of current and preceding stages and how many nodes are
specified in the Configuration file. If the stage is operating in sequential mode, it will first collect the data
before writing it to the file using the default Auto collection method.

Use the Partitioning tab to override this default behavior. The exact operation of this tab depends on
whether:
v The stage is set to execute in parallel or sequential mode.
v The preceding stage in the job is set to execute in parallel or sequential mode.

If the FTP Enterprise stage is set to execute in parallel, then you can set a partitioning method by
selecting from the Partition type drop-down list. This will override any current partitioning.

If the FTP Enterprise stage is set to execute in sequential mode, but the preceding stage is executing in
parallel, then you can set a collection method from the Collector type drop-down list. This will override
the default auto collection method.

The following partitioning methods are available:

v (Auto). WebSphere DataStage attempts to work out the best partitioning method depending on
execution modes of current and preceding stages and how many nodes are specified in the
Configuration file. This is the default partitioning method for the FTP Enterprise stage.
v Entire. Each file written to receives the entire data set.
v Hash. The records are hashed into partitions based on the value of a key column or columns selected
from the Available list.
v Modulus. The records are partitioned using a modulus function on the key column selected from the
Available list. This is commonly used to partition on tag fields.
v Random. The records are partitioned randomly, based on the output of a random number generator.
v Round Robin. The records are partitioned on a round robin basis as they enter the stage.
v Same. Preserves the partitioning already in place.
v DB2. Replicates the DB2 partitioning method of a specific DB2 table. Requires extra properties to be
set. Access these properties by clicking the properties button.
v Range. Divides a data set into approximately equal size partitions based on one or more partitioning
keys. Range partitioning is often a preprocessing step to performing a total sort on a data set. Requires
extra properties to be set. Access these properties by clicking the properties button.

The following Collection methods are available:

v (Auto). This is the default collection method for the FTP Enterprise stage. Normally, when you are
using Auto mode, WebSphere DataStage will eagerly read any row from any input partition as it
becomes available.
v Ordered. Reads all records from the first partition, then all records from the second partition, and so
on.
v Round Robin. Reads a record from the first input partition, then from the second partition, and so on.
After reaching the last partition, the operator starts over.
v Sort Merge. Reads records in an order based on one or more columns of the record. This requires you
to select a collecting key column from the Available list.

The Partitioning tab also allows you to specify that data arriving on the input link should be sorted
before being written to the file or files. The sort is always carried out within data partitions. If the stage is
partitioning incoming data the sort occurs after the partitioning. If the stage is collecting data, the sort
occurs before the collection. The availability of sorting depends on the partitioning or collecting method
chosen (it is not available with the Auto methods).

Select the check boxes as follows:

Chapter 33. FTP Enterprise Stage 389

v Perform Sort. Select this to specify that data coming in on the link should be sorted. Select the column
or columns to sort on from the Available list.
v Stable. Select this if you want to preserve previously sorted data sets. This is the default.
v Unique. Select this to specify that, if multiple records have identical sorting key values, only one
record is retained. If stable sort is also set, the first record is retained.

If NLS is enabled an additional button opens a dialog box allowing you to select a locale specifying the
collate convention for the sort.
v You can also specify sort direction, case sensitivity, whether sorted as ASCII or EBCDIC, and whether
null columns will appear first or last for each column. Where you are using a keyed partitioning
method, you can also specify whether the column is used as a key for sorting, for partitioning, or for
both. Select the column in the Selected list and right-click to invoke the shortcut menu.

Output Page
The Output page allows you to specify details about how the FTP Enterprise stage transfers one or more
files from a remote host using the FTP protocol. The FTP Enterprise stage can have only one output link,
but this can transfer multiple files.

The General tab allows you to specify an optional description of the output link. The Properties tab
allows you to specify details of exactly what the link does. The Columns tab specifies the column
definitions of the data. The Advanced tab allows you to change the default buffering settings for the
output link.

Details about FTP Enterprise stage properties and formatting are given in the following sections. See
../concepts/c_deeref_Stage_Editors.dita, ″Stage Editors,″ for a general description of the other tabs.

Properties Tab
Use the Properties tab to specify properties, which determine what the stage actually does. The available
properties are displayed in a tree structure. They are divided into categories to help you find your way
around them. All the mandatory properties are included in the tree by default and cannot be removed.
Required properties (i.e. which do not have a default value) are shown in a warning color (red by
default) but change to black when you have set a value.

The following table gives a quick reference list of the properties and their attributes.

Category/Property Values Default Mandatory? Repeats? Dependent of

Source/URI Pathname N/A Y Y N/A
Source/URI/Open String N/A N N URI
Command
Connection/ftp Pathname ftp N N N/A
command
Connection/ Password Encrypted N/A N Y N/A
Connection/ User String N/A N Y N/A
Name
Options/Force Yes/No No N N N/A
Parallelism
Options/Restartable Abandon Restartable N Y N/A
Mode Transfer/Restart Transfer
Transfer/
Restartable
Transfer

390 Parallel Job Developer Guide

Category/Property Values Default Mandatory? Repeats? Dependent of
Options/Restartable Pathname N/A N N Restartable
Mode/ Checkpointdir Mode
Options/Restartable Integer 1 N N Restartable
Mode/ Job Id Mode
Options/Schema file Pathname N/A N N N/A
Options/Transfer Type Binary/ASCII Binary N N N/A
Transfer FTP/Secure FTP FTP N N N/A
ProtocolTransfer Mode (SFTP)

Source Category
Specify URI and, if required, Open command.

URI

Is a pathname connecting the Stage to a source file on a remote host. It has the Open dependent property.
You can repeat this property to specify multiple URIs, or you can use a wildcard in the path to retrieve a
number of files. You can specify an absolute or a relative pathname.

The syntax for a relative path is:

ftp://host/path/filename

Where path is the relative path of the user’s home directory.

The syntax for an absolute path is:

ftp://host//path/filename

While connecting to the main frame system, the syntax for an absolute path is:
ftp://host/\’path.filename\’

The syntax for connecting to the main frame system through USS is:
ftp://host//path/filename

Where path is the absolute path of the user’s home directory.

Open command

Is required if you perform any operation besides navigating to the directory where the file exists. There
can be multiple Open commands. This is a dependent property of URI.

Connection Category
Specify the ftp Command, Password and User Name. Only one ftp command can be specified, but
multiple passwords and user names can be specified.

ftp command

Is an optional command that you can specify if you do not want to use the default ftp command. For
example, you could specify /opt/gnu/bin/wuftp. You can enter the path of the command (on the server)
directly in this field. You can also specify a job parameter if you want to be able to specify the ftp
command at run time.

Chapter 33. FTP Enterprise Stage 391

User Name

Specify the user name for the transfer. You can enter it directly in this field, or you can specify a job
parameter if you want to be able to specify the user name at run time. You can specify multiple user
names. User1 corresponds to URI1 and so on. When the number of users is less than the number of URIs,
the last user name is set for remaining URIs

If no User Name is specified, the FTP Enterprise Stage tries to use .netrc file in the home directory.

Password

Enter the password in this field. You can also specify a job parameter if you want to be able to specify
the password at run time. Specify a password for each user name. Password1 corresponds to URI1. When
the number of passwords is less than the numbers of URIs, the last password is set for the remaining
URIs.

Transfer Protocol

Select the type of FTP service to transfer files between computers. You can choose either FTP or Secure
FTP (SFTP).

FTP

Select this option if you want to transfer files using the standard FTP protocol. This is a nonsecure
protocol. By default FTP Enterprise Stage uses this protocol to transfer files.

Secure FTP (SFTP)

Select this option if you want to transfer the files between computers in a secured channel. Secure FTP
(SFTP) uses the SSH (Secured Shell) protected channel for data transfer between computers over a
non-secure network such as a TCP/IP network. Before you can use SFTP to transfer files, you should
configure the SSH connection without any pass phrase for RSA authentication.

Options Category
Force Parallelism

You can set either Yes or No. In general, the FTP Enterprise stage tries to start as many processes as
needed to transfer the n files in parallel. However, you can force the parallel transfer of data by
specifying this property to yes. This allows m number of processes at a time where m is the number
specified in WebSphere DataStage configuration file. If m is less than n, then the stage waits to transfer
the first m files and then start the next m until n files are transferred.

When you set Force Parallelism to Yes, you should only give one URI.

Restartable Mode

When you specify a restartable mode of Restartable transfer, WebSphere DataStage creates a directory for
recording information about the transfer in a restart directory. If the transfer fails, you can run an
identical job with the restartable mode property set to Restart transfer, which will reattempt the transfer.
If the transfer repeatedly fails, you can run an identical job with the restartable mode option set to
Abandon transfer, which will delete the restart directory. For more details, see ″Restartability″ .

For get operations, WebSphere DataStage reinitiates the FTP transfer at the file boundary. The transfer of
the files that failed half way is restarted from the beginning or zero file location. The file URIs that were
transferred completely are not transferred again. Subsequently, the downloaded URIs are imported to the
dataset from the temporary folder path.

392 Parallel Job Developer Guide

Restartable mode has the following dependent properties:
v Job Id
Identifies a restartable transfer job. This is used to name the restart directory.
v Checkpoint directory
Optionally specifies a checkpoint directory to contain restart directories. If you do not specify this, the
current working directory is used.

For example, if you specify a job_id of 100 and a checkpoint directory of /home/bgamsworth/checkpoint the
files would be written to /home/bgamsworth/checkpoint/pftp_jobid_100.

Schema file

Contains a schema for storing data. Setting this option overrides any settings on the Columns tab. You
can enter the path name of a schema file, or specify a job parameter, so the schema file name can be
specified at run time.

Transfer Type

Select a data transfer type to transfer files between computers. You can select either the Binary or ASCII
mode of data transfer. The default data transfer type is binary.

Chapter 33. FTP Enterprise Stage 393

394 Parallel Job Developer Guide
Chapter 34. Generic stage
The Generic stage is a processing stage. It has any number of input links and any number of output
links.

The Generic stage allows you to call an Orchestrate operator from within a WebSphere DataStage stage
and pass it options as required. See WebSphere DataStage Parallel Job Advanced Developer Guide for more
details about Orchestrate operators.

The stage editor has three pages:

v Stage Page. This is always present and is used to specify general information about the stage.
v Input Page. This is where you specify the details about the input set from which you are selecting
records.
v Output Page. This is where you specify details about the processed data being output from the stage.

Must do’s
WebSphere DataStage has many defaults which means that it can be very easy to include Generic stages
in a job. This section specifies the minimum steps to take to get a Generic stage functioning. WebSphere
DataStage provides a versatile user interface, and there are many shortcuts to achieving a particular end,
this section describes the basic method, you will learn where the shortcuts are when you get familiar
with the product.

To use a Generic stage:

v In the Stage page Properties Tab:
– Specify the name of the Orchestrate operator the stage will call.
– Specify the name of any options the operator requires, and set its value. This can be repeated to
specify multiple options.
v In the Stage page Link Ordering Tab, order your input and output links so they correspond to the
required link number.

© Copyright IBM Corp. 2006 395

Stage page
The General tab allows you to specify an optional description of the stage. The Properties tab lets you
specify what the stage does. The Advanced tab allows you to specify how the stage executes.

Properties tab
The Properties tab allows you to specify properties which determine what the stage actually does. Some
of the properties are mandatory, although many have default settings. Properties without default settings
appear in the warning color (red by default) and turn black when you supply a value for them.

The following table gives a quick reference list of the properties and their attributes. A more detailed
description of each property follows.

Category/
Property Values Default Mandatory? Repeats? Dependent of
Options/Operator Orchestrate N/A Y N N/A
operator
Options/Option String N/A N Y N/A
name
Options/Option String N/A N N Option name
Value

Options category
Operator

Specify the name of the Orchestrate operator the stage will call.

Option name

Specify the name of an option the operator requires. This has a dependent property:
v Option Value
The value the option is to be set to.

Advanced tab
This tab allows you to specify the following:
v Execution Mode. The stage can execute in parallel mode or sequential mode. In parallel mode the
input data is processed by the available nodes as specified in the Configuration file, and by any node
constraints specified on the Advanced tab. In Sequential mode the entire data set is processed by the
conductor node.
v Combinability mode. This is Auto by default, which allows WebSphere DataStage to combine the
operators that underlie parallel stages so that they run in the same process if it is sensible for this type
of stage.
v Preserve partitioning. This is Propagate by default. It adopts Set or Clear from the previous stage. You
can explicitly select Set or Clear. Select Set to request that next stage in the job should attempt to
maintain the partitioning.
v Node pool and resource constraints. Select this option to constrain parallel execution to the node pool
or pools and/or resource pool or pools specified in the grid. The grid allows you to make choices from
drop down lists populated from the Configuration file.
v Node map constraint. Select this option to constrain parallel execution to the nodes in a defined node
map. You can define a node map by typing node numbers into the text box or by clicking the browse

396 Parallel Job Developer Guide

 button to open the Available Nodes dialog box and selecting nodes from there. You are effectively
defining a new node pool for this stage (in addition to any node pools defined in the Configuration
file).

Link Ordering tab

This tab allows you to specify how input and output links correspond to link labels.

To rearrange the links, choose an output link and click the up arrow button or the down arrow button.

Input page
The Input page allows you to specify details about the incoming data sets. The Generic stage can accept
multiple incoming data sets. Select the link whose details you are looking at from the Input name
drop-down list.

The General tab allows you to specify an optional description of the input link. The Partitioning tab
allows you to specify how incoming data is partitioned before being operated on. The Columns tab
specifies the column definitions of incoming data. The Advanced tab allows you to change the default
buffering settings for the input link.

Details about Generic stage partitioning are given in the following section. See ″Stage Editors,″ for a
general description of the other tabs.

Partitioning tab
The Partitioning tab allows you to specify details about how the incoming data is partitioned or collected
before it is operated on. It also allows you to specify that the data should be sorted before being operated
on.

By default the stage partitions in Auto mode. This attempts to work out the best partitioning method
depending on execution modes of current and preceding stages and how many nodes are specified in the
Configuration file.

If the Generic stage is operating in sequential mode, it will first collect the data using the default Auto
collection method.

The Partitioning tab allows you to override this default behavior. The exact operation of this tab depends
on:
v Whether the Generic stage is set to execute in parallel or sequential mode.
v Whether the preceding stage in the job is set to execute in parallel or sequential mode.

If the Generic stage is set to execute in parallel, then you can set a partitioning method by selecting from
the Partition type drop-down list. This will override any current partitioning.

If the Generic stage is set to execute in sequential mode, but the preceding stage is executing in parallel,
then you can set a collection method from the Collector type drop-down list. This will override the
default collection method.

The following partitioning methods are available:

v (Auto). WebSphere DataStage attempts to work out the best partitioning method depending on
execution modes of current and preceding stages and how many nodes are specified in the
Configuration file. This is the default method of the Generic stage.
v Entire. Each file written to receives the entire data set.

Chapter 34. Generic stage 397

v Hash. The records are hashed into partitions based on the value of a key column or columns selected
from the Available list.
v Modulus. The records are partitioned using a modulus function on the key column selected from the
Available list. This is commonly used to partition on tag fields.
v Random. The records are partitioned randomly, based on the output of a random number generator.
v Round Robin. The records are partitioned on a round robin basis as they enter the stage.
v Same. Preserves the partitioning already in place.
v DB2. Replicates the DB2 partitioning method of a specific DB2 table. Requires extra properties to be
set. Access these properties by clicking the properties button.
v Range. Divides a data set into approximately equal size partitions based on one or more partitioning
keys. Range partitioning is often a preprocessing step to performing a total sort on a data set. Requires
extra properties to be set. Access these properties by clicking the properties button.

The following Collection methods are available:

v (Auto). This is the default collection method for Generic stages. Normally, when you are using Auto
mode, WebSphere DataStage will eagerly read any row from any input partition as it becomes
available.
v Ordered. Reads all records from the first partition, then all records from the second partition, and so
on.
v Round Robin. Reads a record from the first input partition, then from the second partition, and so on.
After reaching the last partition, the operator starts over.
v Sort Merge. Reads records in an order based on one or more columns of the record. This requires you
to select a collecting key column from the Available list.

The Partitioning tab also allows you to specify that data arriving on the input link should be sorted
before being operated on. The sort is always carried out within data partitions. If the stage is partitioning
incoming data the sort occurs after the partitioning. If the stage is collecting data, the sort occurs before
the collection. The availability of sorting depends on the partitioning or collecting method chosen (it is
not available for the default auto methods).

Select the check boxes as follows:

v Perform Sort. Select this to specify that data coming in on the link should be sorted. Select the column
or columns to sort on from the Available list.
v Stable. Select this if you want to preserve previously sorted data sets. This is the default.
v Unique. Select this to specify that, if multiple records have identical sorting key values, only one
record is retained. If stable sort is also set, the first record is retained.

If NLS is enabled an additional button opens a dialog box allowing you to select a locale specifying the
collate convention for the sort.

You can also specify sort direction, case sensitivity, whether sorted as ASCII or EBCDIC, and whether null
columns will appear first or last for each column. Where you are using a keyed partitioning method, you
can also specify whether the column is used as a key for sorting, for partitioning, or for both. Select the
column in the Selected list and right-click to invoke the shortcut menu.

Output page
The Output page allows you to specify details about data output from the Generic stage. The Generic
stage can have any number of output links. Select the link whose details you are looking at from the
Output name drop-down list.

398 Parallel Job Developer Guide

The General tab allows you to specify an optional description of the output link. The Columns tab
specifies the column definitions of the data. The Advanced tab allows you to change the default buffering
settings for the output links.

See ″Stage Editors,″ for a general description of these tabs.

Chapter 34. Generic stage 399

400 Parallel Job Developer Guide
Chapter 35. Surrogate Key Generator stage
The Surrogate Key Generator stage is a processing stage that generates surrogate key columns and
maintains the key source.

A surrogate key is a unique primary key that is not derived from the data that it represents, therefore
changes to the data will not change the primary key. In a star schema database, surrogate keys are used
to join a fact table to a dimension table.

The Surrogate Key Generator stage can have a single input link, a single output link, both an input link
and an output link, or no links. Job design depends on the purpose of the stage.

You can use a Surrogate Key Generator stage to perform the following tasks:
v Create or delete the key source before other jobs run
v Update a state file with a range of key values
v Generate surrogate key columns and pass them to the next stage in the job
v View the contents of the state file

Generated keys are unsigned 64-bit integers. The key source can be a state file or a database sequence.

You can use the Surrogate Key Generator stage to update a state file, but not a database sequence.
Sequences must be modified with database tools.

Creating the key source

You can create the surrogate key source by adding a Surrogate Key Generator stage to a job by itself,
with no input or output links.

You must create a key source before you can use it in a job. The key source can be a state file or a
database sequence.

To create the key source:

1. Open the Surrogate Key Generator stage editor.
2. On the Properties tab, define the Key Source properties:
a. Set the Key Source Action property to Create.
b. Type or browse for the source name.
c. Select the source type.
3. If the source type is a database sequence, complete some additional steps on the Properties tab:
a. Define the Database Type properties.
b. Add the Sequence Initial Value property to the Options group, and specify the value to initialize
the sequence.
c. If you want to control the block size for key ranges, add the Sequence Block Size property to the
Options group, set this property to User specified, and specify a value for the block size.
4. Optional: On the Advanced tab, change the processing settings for the stage.
5. Click OK to save your changes and to close the Surrogate Key Generator stage editor.

© Copyright IBM Corp. 2006 401

Deleting the key source
To delete the surrogate key source, design a job that uses a Surrogate Key Generator stage by itself, with
no input or output links.

To delete the key source:

1. Open the Surrogate Key Generator stage editor.
2. On the Properties tab, define the Key Source properties:
a. Set the Key Source Action property to Delete.
b. Type or browse for the source name.
c. Select the source type.
d. If the source type is a database sequence, define the Database Type properties.
3. Optional: On the Advanced tab, change the processing settings for the stage.
4. Click OK to save your changes and to close the Surrogate Key Generator stage editor.

Updating the state file

To update the state file, add a Surrogate Key Generator stage to a job with a single input link from
another stage. If the state file does not exist, you can optionally create it in the same job.

Before you edit the Surrogate Key Generator stage, you must edit the stage on the input link. In the data
input stage, specify details about the data source, such as the table name and connection properties, and
define the column metadata.

You cannot update database sequences. Use database tools to update sequences.

To update a state file:

1. Open the Surrogate Key Generator stage editor.
2. On the Stage page, define the stage properties:
a. Click the Properties tab.
b. Select the input column to update the state file. The input column usually is the surrogate key
column.
c. Set the Key Source Update Action property to Update, or if the state file does not exist and you
want to create it, select Create and Update.
d. Type or browse for the source name.
e. Set the Source Type property to Flat File.
f. Optional: On the Advanced tab, change the processing settings for the stage.
3. Optional: On the Input page, define the input data to the stage:
a. On the Partitioning tab, change the partition settings for the input link.
b. On the Advanced tab, change the buffer settings for the input link.
4. Click OK to save your changes and to close the Surrogate Key Generator stage editor.

Generating surrogate keys

To generate surrogate keys, add a Surrogate Key Generator stage to a job with a single output link to
another stage.

If you want to pass input columns to the next stage in the job, the Surrogate Key Generator stage can
also have an input link.

To generate surrogate keys:

402 Parallel Job Developer Guide

1. Open the Surrogate Key Generator stage editor.
2. On the Stage page, define the stage properties:
a. Click the Properties tab.
b. Type a name for the surrogate key column in the Generated Output Column Name property.
c. Type or browse for the source name.
d. Select the source type.
e. If the source type is a database sequence, define the Database Type properties.
f. If the key source is a flat file, specify how keys are generated:
v To generate keys in sequence from the highest value that was last used, set the Generate Key
from Last Highest Value property to Yes. Any gaps in the key range are ignored.
v To specify a value to initialize the key source, add the File Initial Value property to the Options
group, and specify the start value for key generation.
v To control the block size for key ranges, add the File Block Size property to the Options group,
set this property to User specified, and specify a value for the block size.
g. If there is no input link, add the Number of Records property to the Options group, and specify
how many records to generate.
h. Optional: On the Advanced tab, change the processing settings for the stage.
3. Optional: If the stage has an input link, on the Input page, define the input data:
a. On the Partitioning tab, change the partition settings for the input link.
b. On the Advanced tab, change the buffer settings for the input link.
4. On the Output page, define the output data:
a. On the Mapping tab, map the surrogate key column to the output link. If the stage has an input
link, you can also map input columns to the output link.
b. Optional: On the Advanced tab, change the buffer settings for the output link.
5. Click OK to save your changes and to close the Surrogate Key Generator stage editor.

Chapter 35. Surrogate Key Generator stage 403

404 Parallel Job Developer Guide
Chapter 36. Slowly Changing Dimension stage
The Slowly Changing Dimension (SCD) stage is a processing stage that works within the context of a star
schema database. The SCD stage has a single input link, a single output link, a dimension reference link,
and a dimension update link.

The SCD stage reads source data on the input link, performs a dimension table lookup on the reference
link, and writes data on the output link. The output link can pass data to another SCD stage, to a
different type of processing stage, or to a fact table. The dimension update link is a separate output link
that carries changes to the dimension. You can perform these steps in a single job or a series of jobs,
depending on the number of dimensions in your database and your performance requirements.

SCD stages support both SCD Type 1 and SCD Type 2 processing:
SCD Type 1
Overwrites an attribute in a dimension table.
SCD Type 2
Adds a new row to a dimension table.

Each SCD stage processes a single dimension and performs lookups by using an equality matching
technique. If the dimension is a database table, the stage reads the database to build a lookup table in
memory. If a match is found, the SCD stage updates rows in the dimension table to reflect the changed
data. If a match is not found, the stage creates a new row in the dimension table. All of the columns that
are needed to create a new dimension row must be present in the source data.

Input data to SCD stages must accurately represent the order in which events occurred. You might need
to presort your input data by a sequence number or a date field. If a job has multiple SCD stages, you
must ensure that the sort order of the input data is correct for each stage.

If the SCD stage is running in parallel, the input data must be hash partitioned by key. Hash partitioning
allows all records with the same business key to be handled by the same process. The SCD stage divides
the dimension table across processes by building a separate lookup table for each process.

Job design using a Slowly Changing Dimension stage

Each SCD stage processes a single dimension, but job design is flexible. You can design one or more jobs
to process dimensions, update the dimension table, and load the fact table.
Processing dimensions
You can create a separate job for each dimension, one job for all dimensions, or several jobs, each
of which has several dimensions.
Updating dimensions
You can update the dimension table as the job runs by linking the SCD stage to a database stage,
or you can update the dimension table later by sending dimension changes to a flat file that you
use in a separate job. Actual dimension changes are applied to the lookup table in memory and
are mirrored to the dimension update link, giving you the flexibility to handle a series of changes
to the same dimension row.
Loading the fact table
You can load the fact table as the final step of the job that updates the last dimension, or in a
separate job.

© Copyright IBM Corp. 2006 405

The following figures show a series of jobs, where the first job performs the dimension lookup, the
second job performs the dimension table update, and the third job loads the fact table.

Figure 2. This job performs the dimension lookup.

Figure 3. This job updates the dimension table.

406 Parallel Job Developer Guide

Figure 4. This job loads the fact table.

The job design shown in these figures minimizes the use of database facilities. Job 1 builds a lookup table
in memory for the dimension, so the database connection is active only when the table is being created.
Both the output data and the dimension update records are written to flat files. Job 2 and Job 3 use these
files to update the dimension table and to load the fact table later.

This series of jobs represents a single dimension table. If you have multiple dimensions, each has a Job 1
and a Job 2. The output of the last Job 1 is the input to Job 3.

Another strategy is to combine the first two jobs into a single step, as shown in the following figure:

Figure 5. This job performs the dimension lookup and updates the dimension table.

Here the SCD stage provides the necessary column information to the database stage so that it can
generate the correct INSERT and UPDATE SQL statements to update the dimension table. By contrast, the
design in the first three figures requires you to save your output columns from the SCD stage in Job 1 as
a table definition in the repository. You must then load columns from this table definition into the
database stage in Job 2.

Chapter 36. Slowly Changing Dimension stage 407

Purpose codes in a Slowly Changing Dimension stage
Purpose codes are an attribute of dimension columns in SCD stages. Purpose codes are used to build the
lookup table, to detect dimension changes, and to update the dimension table.

Building the lookup table

The SCD stage uses purpose codes to determine how to build the lookup table for the dimension lookup.
If a dimension has only Type 1 columns, the stage builds the lookup table by using all dimension rows. If
any Type 2 columns exist, the stage builds the lookup table by using only the current rows. If a
dimension has a Current Indicator column, the stage uses the derivation value of this column on the Dim
Update tab to identify the current rows of the dimension table. If a dimension does not have a Current
Indicator column, then the stage uses the Expiration Date column and its derivation value to identify the
current rows. Any dimension columns that are not needed are not used. This technique minimizes the
amount of memory that is required by the lookup table.

Detecting dimension changes

Purpose codes are also used to detect dimension changes. The SCD stage compares Type 1 and Type 2
column values to source column values to determine whether to update an existing row, insert a new
row, or expire a row in the dimension table.

Updating the dimension table

Purpose codes are part of the column metadata that the SCD stage propagates to the dimension update
link. You can send this column metadata to a database stage in the same job, or you can save the
metadata on the Columns tab and load it into a database stage in a different job. When the database
stage uses the auto-generated SQL option to perform inserts and updates, it uses the purpose codes to
generate the correct SQL statements.

For more information, see “Selecting purpose codes” on page 410 and “Purpose code definitions” on
page 410.

Surrogate keys in a Slowly Changing Dimension stage

Surrogate keys are used to join a dimension table to a fact table in a star schema database.

When the SCD stage performs a dimension lookup, it retrieves the value of the existing surrogate key if a
matching record is found. If a match is not found, the stage obtains a new surrogate key value by using
the derivation of the Surrogate Key column on the Dim Update tab. If you want the SCD stage to
generate new surrogate keys by using a key source that you created with a Surrogate Key Generator
stage, you must use the NextSurrogateKey function to derive the Surrogate Key column. If you want to
use your own method to handle surrogate keys, you should derive the Surrogate Key column from a
source column.

You can replace the dimension information in the source data stream with the surrogate key value by
mapping the Surrogate Key column to the output link.

For more information, see “Specifying information about a key source” on page 411 and “Creating
derivations for dimension columns” on page 411.

408 Parallel Job Developer Guide

Editing a Slowly Changing Dimension stage
To edit an SCD stage, you must define how the stage should look up data in the dimension table, obtain
surrogate key values, update the dimension table, and write data to the output link.

Prerequisites

Before you edit the SCD stage, you must edit the stages on the input links:
v In the source stage, specify the file name for the data source and define the column metadata. You
should also verify that the source data is sorted correctly.
v In the dimension reference stage, specify the table name and connection properties for the dimension
table, and define the column metadata.

To edit the SCD stage:

1. Open the SCD stage editor.
2. On the Stage page, define the general stage properties:
a. On the General tab, select the output link. The SCD stage will use the other link to update the
dimension table. By default the first output link that you connect to the SCD stage is set as the
output link.
b. Optional: On the Advanced tab, change the processing settings.
3. On the Input page, define the input data to the stage:
a. Select the reference link in the Input name field.
b. On the Lookup tab, define the match condition to use for the dimension lookup.
c. On the Lookup tab, select the purpose codes for the dimension columns.
d. If you are using a Surrogate Key Generator stage to maintain the key source, specify information
about the key source on the Surrogate Key tab.
e. Optional: On the Advanced tab, change the buffering settings.
f. Optional: On the Partitioning tab, change the partitioning settings. The partitioning mode is set to
Auto by default. The SCD stage always uses the Hash method to partition records, based on the
keys that are defined by the lookup condition.
4. On the Output page, define the output data from the stage:
a. On the Dim Update tab, create column derivations to specify how to detect and apply changes to
dimension records.
b. On the Output Map tab, map data from the input links to the output link.
c. Optional: If you are updating the dimension table in a separate job, save the column definitions
on the Columns tab as a table definition in the repository. You can load the columns from the
saved table definition into the database stage of another job. The database stage will use these
columns definitions and SCD purpose codes to generate the correct INSERT and UPDATE SQL
statements to update the dimension table.
d. Optional: On the Advanced tab, change the buffering settings.
5. Click OK to save your changes and to close the SCD stage editor.

After you edit the SCD stage, you must edit the stages on the output links:
v If you are updating the dimension table in the current job, specify the name and connection properties
for the dimension table, set the Write Method property to Upsert, and set the Upsert Mode property
to Auto-generated Update & Insert. You do not need to define column metadata because the SCD
stage propagates the column definitions from the dimension reference link to the dimension update
link.
v If you are loading the fact table in the current job, specify the table name and connection properties for
the target database, and select any write method. The column metadata is already defined by the
mappings that you specified in the SCD stage.

Chapter 36. Slowly Changing Dimension stage 409

Defining the match condition
The match condition specifies how the SCD stage should perform the dimension lookup.

You must associate at least one pair of columns, but you can define multiple pairs if required. When you
define more than one pair, the SCD stage combines the match conditions. A successful lookup requires all
associated pairs of columns to match.

To define the match condition:

1. On the Input page, select the reference link in the Input name field.
2. Click the Lookup tab.
3. Drag a source column from the left pane to a dimension column in the right pane. A relationship line
is drawn between the two columns to represent the match condition.

Selecting purpose codes

Purpose codes specify how the SCD stage should process dimension data.

Purpose codes apply to columns on the dimension reference link and on the dimension update link.
Select purpose codes according to the type of columns in a dimension:
v If a dimension contains a Type 2 column, you must select a Current Indicator column, an Expiration
Date column, or both. An Effective Date column is optional. You cannot assign Type 2 and Current
Indicator to the same column.
v If a dimension contains only Type 1 columns, no Current Indicator, Effective Date, Expiration Date, or
SK Chain columns are allowed.

To select purpose codes:

1. On the Input page, select the reference link in the Input name field.
2. Click the Lookup tab.
3. In the right pane, select a purpose code for each column. You assign purpose codes in different ways
depending on whether you want to assign one to a single column or to multiple columns:
v For a single column, click the Purpose arrow next to the column to select a purpose code from a
list.
v For multiple columns with the same purpose code, select the columns and click Set purpose code
from the pop-up menu. In the Set Purpose Code window, select the purpose code that you want to
apply to the selected columns.

After you select purpose codes on the Lookup tab, the SCD stage automatically propagates the column
definitions and purpose codes to the Dim Update tab.

Purpose code definitions

The SCD stage provides nine purpose codes to support dimension processing.
(blank)
The column has no SCD purpose. This purpose code is the default.
Surrogate Key
The column is a surrogate key that is used to identify dimension records.
Business Key
The column is a business key that is typically used in the lookup condition.
Type 1
The column is an SCD Type 1 field. SCD Type 1 column values are always current. When changes
occur, the SCD stage overwrites existing values in the dimension table.

410 Parallel Job Developer Guide

Type 2
The column is an SCD Type 2 field. SCD Type 2 column values represent a point in time. When
changes occur, the SCD stage creates a new dimension row.
Current® Indicator (Type 2)
The column is the current record indicator for SCD Type 2 processing. Only one Current Indicator
column is allowed.
Effective Date (Type 2)
The column is the effective date for SCD Type 2 processing. Only one Effective Date column is
allowed.
Expiration Date (Type 2)
The column is the expiration date for SCD Type 2 processing. An Expiration Date column is
required if there is no Current Indicator column, otherwise it is optional.
SK Chain
The column is used to link a record to the previous record or the next record by using the value
of the Surrogate Key column. Only one Surrogate Key column can exist if you have an SK Chain
column.

Specifying information about a key source

If you created a key source with a Surrogate Key Generator stage, you must specify how the SCD stage
should use the source to generate surrogate keys.

The key source can be a flat file or a database sequence. The key source must exist before the job runs. If
the key source is a flat file, the file must be accessible from all nodes that run the SCD stage.

To use the key source:

1. On the Input page, select the reference link in the Input name field.
2. Click the Surrogate Key tab.
3. In the Source type field, select the source type.
4. In the Source name field, type the name of the key source, or click the arrow button to browse for a
file or to insert a job parameter. If the source is a flat file, type the name and fully qualified path of
the state file, such as C:\SKG\ProdDim. If the source is a database sequence, type the name of the
sequence, such as PRODUCT_KEY_SEQ.
5. Provide additional information about the key source according to the type:
v If the source is a flat file, specify information in the Flat File area.
v If the source is a database sequence, specify information in the DB sequence area.

Calls to the key source are made by the NextSurrogateKey function. On the Dim Update tab, create a
derivation that uses the NextSurrogateKey function for the column that has a purpose code of Surrogate
Key. The NextSurrogateKey function returns the value of the next surrogate key when the SCD stage
creates a new dimension row.

Creating derivations for dimension columns

By creating derivations for the dimension columns, you specify how to update the dimension table,
including the values to use for new records and when records should expire.

Every dimension column must have a derivation. Columns with a purpose code of Current Indicator or
Expiration Date must also have an Expire derivation. The following requirements apply:
v Columns with a purpose code of Type 1 or Type 2 must be derived from a source column.
v Columns with a purpose code of Current Indicator or Expiration Date must be derived from a literal
value.

Chapter 36. Slowly Changing Dimension stage 411

v Columns with a purpose code of SK Chain must be derived by using either the PrevSKChain function
or the NextSKChain function.

To create column derivations:

1. On the Output page, select the dimension update link in the Output name field.
2. Click the Dim Update tab.
3. Create column derivations by using any of these methods:
v Drag source columns from the left pane to the Derivation field in the right pane
v Use the column auto-match facility (right-click the link header and select Auto Match)
v Define an expression by using the expression editor (double-click the Derivation or Expire field)
Relationship lines show which dimension columns are derived from source columns, either directly or
as part of an expression.

Mapping data to the output link

Mappings specify how to write data from the input links to the output link.

You can map input data and dimension data to the output link. Dimension data is mapped from the
lookup table in memory, so new rows and changed data are available for output.

To map data to the output link:

1. On the Output page, select the output link in the Output name field.
2. Click the Output Map tab.
3. Create mappings by using any of these methods:
v Drag columns from the left pane to the Derivation field in the right pane
v Use the column auto-match facility (right-click the link header and select Auto Match)
v Define an expression by using the expression editor (double-click the Derivation field)
Relationship lines show which input columns are being mapped to the output link.

Dimension update action

The SCD stage updates the dimension table based on the results of the dimension lookup, plus the
detection of a change in value for at least one SCD column.

Changes to Type 2 columns take precedence over changes to Type 1 columns. The following table
describes how the SCD stage determines the update action for the dimension table:

Lookup result Type of column change Update action

Dimension row not found Not applicable The stage creates a new dimension
row by using all of the column
derivations that are defined for the
dimension update link on the Dim
Update tab.

412 Parallel Job Developer Guide

Lookup result Type of column change Update action
Dimension row found Type 2 column value changed, The stage expires the current
regardless of whether any Type 1 dimension row and creates a new
column value changed row. This maintains the history that
is required for Type 2 processing. To
expire a row, the stage updates only
the columns with a purpose code of
Current Indicator and Expiration
Date by using their Expire
expressions on the Dim Update tab.
To create a new row, the stage
derives all of the columns from the
Derivation expressions on the Dim
Update tab.
Type 1 column value changed, but no The stage updates only the columns
Type 2 column value changed with a purpose code of Type 1 by
using their Derivation expressions on
the Dim Update tab.
No column values changed No updates are needed.

Chapter 36. Slowly Changing Dimension stage 413

414 Parallel Job Developer Guide
Chapter 37. Column Import stage
The Column Import stage is a restructure stage. It can have a single input link, a single output link and a
single rejects link. The complement to this stage is the Column Export stage, described in Chapter 38,
“Column Export stage,” on page 425.

The Column Import stage imports data from a single column and outputs it to one or more columns. You
would typically use it to divide data arriving in a single column into multiple columns. The data would
be fixed-width or delimited in some way to tell the Column Import stage where to make the divisions.
The input column must be a string or binary data, the output columns can be any data type.

You supply an import table definition to specify the target columns and their types. This also determines
the order in which data from the import column is written to output columns. Information about the
format of the incoming column (e.g., how it is delimited) is given in the Format tab of the Output page.
You can optionally save reject records, that is, records whose import was rejected, and write them to a
rejects link.

In addition to importing a column you can also pass other columns straight through the stage. So, for
example, you could pass a key column straight through.

The stage editor has three pages:

v Stage Page. This is always present and is used to specify general information about the stage.
v Input Page. This is where you specify the details about the single input set from which you are
selecting records.
v Output Page. This is where you specify details about the processed data being output from the stage.

Examples
This section gives examples of input and output data from a Column Import stage to give you a better
idea of how the stage works.

© Copyright IBM Corp. 2006 415

In this example the Column Import stage extracts data from 16-byte raw data field into four integer
output fields. The input data set also contains a column which is passed straight through the stage. The
example assumes that the job is running sequentially. The metadata is as follows:

Column name Key SQL type

keycol Yes Char
col_to_import Binary

These are the rows from the input data set:

Keycol col_to_import
a 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
b 01 01 01 01 01 01 01 01 01 01 01 01 01 01 01 01 01
c 02 02 02 02 02 02 02 02 02 02 02 02 02 02 02 02
d 03 03 03 03 03 03 03 03 03 03 03 03 03 03 03 03
e 04 04 04 04 04 04 04 04 04 04 04 04 04 04 04 04
f 05 05 05 05 05 05 05 05 05 05 05 05 05 05 05 05
g 06 06 06 06 06 06 06 06 06 06 06 06 06 06 06 06
h 07 07 07 07 07 07 07 07 07 07 07 07 07 07 07 07
i 08 08 08 08 08 08 08 08 08 08 08 08 08 08 08 08
j 09 09 09 09 09 09 09 09 09 09 09 09 09 09 09 09

The import table definition can either be supplied on the Output Page Columns tab or in a schema file.
For the example, the definition would be:

Column name Key SQL type

keycol Yes Char
col1 Integer
col2 Integer
col3 Integer
col4 Integer

You have to give WebSphere DataStage information about how to treat the imported data to split it into
the required columns. This is done on the Output page Format Tab. For this example, you specify a data
format of binary to ensure that the contents of col_to_import are interpreted as binary integers, and that
the data has a field delimiter of none

416 Parallel Job Developer Guide

 .

The properties of the Column Import stage are set as follows:

The output data set will be:

col1 col2 col3 col4 key

0 0 0 0 a
16843009 16843009 16843009 16843009 b
33686018 33686018 33686018 33686018 c

Chapter 37. Column Import stage 417

col1 col2 col3 col4 key
50529027 50529027 50529027 50529027 d
67372036 67372036 67372036 67372036 e
84215045 84215045 84215045 84215045 f
101058054 101058054 101058054 101058054 g
117901063 117901063 117901063 117901063 h
134744072 134744072 134744072 134744072 i
151587081 151587081 151587081 151587081 j

Must do’s
WebSphere DataStage has many defaults which means that it can be very easy to include Column Import
stages in a job. This section specifies the minimum steps to take to get a Column Import stage
functioning. WebSphere DataStage provides a versatile user interface, and there are many shortcuts to
achieving a particular end, this section describes the basic method, you will learn where the shortcuts are
when you get familiar with the product.

To use a Column Import stage:

v In the Stage page Properties Tab, under the Input category:
– Specify the column that you are importing.
Under the Output category:
– Choose the Column method, this is Explicit by default, meaning you specify explicitly choose output
columns as destinations. The alternative is to specify a schema file.
– If you are using the Explicit method, choose the output column(s) to carry your imported input
column. Repeat the Column to Import property to specify all the columns you need.
– If you are using the Schema File method, specify the schema file that gives the output column
details.
v In the Output page Format Tab specify the format of the column you are importing. This informs
WebSphere DataStage about data format and enables it to divide a single column into multiple
columns.
v In the Output page Mapping Tab check that the input columns are mapping onto the output columns
as you expect. The mapping is carried out according to what you specified in the Properties tab.

Stage page
The General tab allows you to specify an optional description of the stage. The Properties tab lets you
specify what the stage does. The Advanced tab allows you to specify how the stage executes.

Properties tab
The Properties tab allows you to specify properties which determine what the stage actually does. Some
of the properties are mandatory, although many have default settings. Properties without default settings
appear in the warning color (red by default) and turn black when you supply a value for them.

The following table gives a quick reference list of the properties and their attributes. A more detailed
description of each property follows.

418 Parallel Job Developer Guide

Category/
Property Values Default Mandatory? Repeats? Dependent of
Input/Import Input Column N/A Y N N/A
Input Column
Output/Column Explicit/Schema Explicit Y N N/A
Method File
Output/Column Output Column N/A Y (if Column Y N/A
to Import Method =
Explicit)
Output/Schema Pathname N/A Y (if Column N N/A
File Method = Schema
file)
Options/Keep True/False False N N N/A
Input Column
Options/Reject Continue (warn) Continue N N N/A
Mode /Output/Fail

Input category
Import input column

Specifies the name of the column containing the string or binary data to import.

Output category
Column method

Specifies whether the columns to import should be derived from column definitions on the Output page
Columns tab (Explicit) or from a schema file (Schema File).

Column to import

Specifies an output column. The meta data for this column determines the type that the import column
will be converted to. Repeat the property to specify multiple columns. You can use the Column Selection
dialog box to select multiple columns at once if required . You can specify the properties for each column
using the Parallel tab of the Edit Column Meta dialog box (accessible from the shortcut menu on the
columns grid of the output Columns tab). The order of the Columns to Import that you specify should
match the order on the Columns tab.

Schema File

Instead of specifying the source data type details via output column definitions, you can use a schema
file (note, however, that if you have defined columns on the Columns tab, you should ensure these
match the schema file). Type in a pathname or browse for a schema file.

Options category
Keep Input Column

Specifies whether the original input column should be transferred to the output data set unchanged in
addition to being imported and converted. Defaults to False.

Reject mode

The values of this property specify the following actions:

v Fail. The stage fails when it encounters a record whose import is rejected.

Chapter 37. Column Import stage 419

v Output. The stage continues when it encounters a reject record and writes the record to the reject link.
v Continue. The stage is to continue but report failures to the log file.

Advanced tab
This tab allows you to specify the following:
v Execution Mode. The stage can execute in parallel mode or sequential mode. In parallel mode the
input data is processed by the available nodes as specified in the Configuration file, and by any node
constraints specified on the Advanced tab. In Sequential mode the entire data set is processed by the
conductor node.
v Combinability mode. This is Auto by default, which allows WebSphere DataStage to combine the
operators that underlie parallel stages so that they run in the same process if it is sensible for this type
of stage.
v Preserve partitioning. This is Propagate by default. It adopts Set or Clear from the previous stage. You
can explicitly select Set or Clear. Select Set to request that next stage in the job should attempt to
maintain the partitioning.
v Node pool and resource constraints. Select this option to constrain parallel execution to the node pool
or pools and/or resource pool or pools specified in the grid. The grid allows you to make choices from
drop down lists populated from the Configuration file.
v Node map constraint. Select this option to constrain parallel execution to the nodes in a defined node
map. You can define a node map by typing node numbers into the text box or by clicking the browse
button to open the Available Nodes dialog box and selecting nodes from there. You are effectively
defining a new node pool for this stage (in addition to any node pools defined in the Configuration
file).

Input page
The Input page allows you to specify details about the incoming data sets. The Column Import stage
expects one incoming data set.

The General tab allows you to specify an optional description of the input link. The Partitioning tab
allows you to specify how incoming data is partitioned before being imported. The Columns tab specifies
the column definitions of incoming data. The Advanced tab allows you to change the default buffering
settings for the input link.

Details about Column Import stage partitioning are given in the following section. See ″Stage Editors,″ for
a general description of the other tabs.

Partitioning tab
The Partitioning tab allows you to specify details about how the incoming data is partitioned or collected
before it is imported. It also allows you to specify that the data should be sorted before being operated
on.

By default the stage partitions in Auto mode. This attempts to work out the best partitioning method
depending on execution modes of current and preceding stages and how many nodes are specified in the
Configuration file.

If the Column Import stage is operating in sequential mode, it will first collect the data using the default
Auto collection method.

The Partitioning tab allows you to override this default behavior. The exact operation of this tab depends
on:

420 Parallel Job Developer Guide

v Whether the Column Import stage is set to execute in parallel or sequential mode.
v Whether the preceding stage in the job is set to execute in parallel or sequential mode.

If the Column Import stage is set to execute in parallel, then you can set a partitioning method by
selecting from the Partition type drop-down list. This will override any current partitioning.

If the Column Import stage is set to execute in sequential mode, but the preceding stage is executing in
parallel, then you can set a collection method from the Collector type drop-down list. This will override
the default collection method.

The following partitioning methods are available:

v (Auto). WebSphere DataStage attempts to work out the best partitioning method depending on
execution modes of current and preceding stages and how many nodes are specified in the
Configuration file. This is the default partitioning method for the Column Import stage.
v Entire. Each file written to receives the entire data set.
v Hash. The records are hashed into partitions based on the value of a key column or columns selected
from the Available list.
v Modulus. The records are partitioned using a modulus function on the key column selected from the
Available list. This is commonly used to partition on tag fields.
v Random. The records are partitioned randomly, based on the output of a random number generator.
v Round Robin. The records are partitioned on a round robin basis as they enter the stage.
v Same. Preserves the partitioning already in place.
v DB2. Replicates the DB2 partitioning method of a specific DB2 table. Requires extra properties to be
set. Access these properties by clicking the properties button.
v Range. Divides a data set into approximately equal size partitions based on one or more partitioning
keys. Range partitioning is often a preprocessing step to performing a total sort on a data set. Requires
extra properties to be set. Access these properties by clicking the properties button.

The following Collection methods are available:

v (Auto). This is the default collection method for Column Import stages. Normally, when you are using
Auto mode, WebSphere DataStage will eagerly read any row from any input partition as it becomes
available.
v Ordered. Reads all records from the first partition, then all records from the second partition, and so
on.
v Round Robin. Reads a record from the first input partition, then from the second partition, and so on.
After reaching the last partition, the operator starts over.
v Sort Merge. Reads records in an order based on one or more columns of the record. This requires you
to select a collecting key column from the Available list.

The Partitioning tab also allows you to specify that data arriving on the input link should be sorted
before being imported. The sort is always carried out within data partitions. If the stage is partitioning
incoming data the sort occurs after the partitioning. If the stage is collecting data, the sort occurs before
the collection. The availability of sorting depends on the partitioning or collecting method chosen (it is
not available with the default Auto methods).

Select the check boxes as follows:

v Perform Sort. Select this to specify that data coming in on the link should be sorted. Select the column
or columns to sort on from the Available list.
v Stable. Select this if you want to preserve previously sorted data sets. This is the default.
v Unique. Select this to specify that, if multiple records have identical sorting key values, only one
record is retained. If stable sort is also set, the first record is retained.

Chapter 37. Column Import stage 421

If NLS is enabled an additional button opens a dialog box allowing you to select a locale specifying the
collate convention for the sort.

You can also specify sort direction, case sensitivity, whether sorted as ASCII or EBCDIC, and whether null
columns will appear first or last for each column. Where you are using a keyed partitioning method, you
can also specify whether the column is used as a key for sorting, for partitioning, or for both. Select the
column in the Selected list and right-click to invoke the shortcut menu.

Output page
The Output page allows you to specify details about data output from the Column Import stage. The
Column Import stage can have only one output link, but can also have a reject link carrying records that
have been rejected.

The General tab allows you to specify an optional description of the output link. The Format tab allows
you to specify details about how data in the column you are importing is formatted so the stage can
divide it into separate columns. The Columns tab specifies the column definitions of the data. The
Mapping tab allows you to specify the relationship between the columns being input to the Column
Import stage and the Output columns. The Advanced tab allows you to change the default buffering
settings for the output links.

Details about Column Import stage mapping is given in the following section. See ″Stage Editors,″ for a
general description of the other tabs.

Mapping tab
For the Column Import stage the Mapping tab allows you to specify how the output columns are
derived.

The left pane shows the columns the stage is deriving from the single imported column. These are read
only and cannot be modified on this tab.

The right pane shows the output columns for each link.

We recommend that you maintain the automatic mappings of the generated columns when using this
stage.

Mapping tab
For the Column Import stage the Mapping tab allows you to specify how the output columns are
derived.

The left pane shows the columns the stage is deriving from the single imported column. These are read
only and cannot be modified on this tab.

The right pane shows the output columns for each link.

We recommend that you maintain the automatic mappings of the generated columns when using this
stage.

Reject link
You cannot change the details of a Reject link. The link uses the column definitions for the link rejecting
the data records.

422 Parallel Job Developer Guide

Using RCP With Column Import Stages
Runtime column propagation (RCP) allows WebSphere DataStage to be flexible about the columns you
define in a job. If RCP is enabled for a project, you can just define the columns you are interested in
using in a job, but ask WebSphere DataStage to propagate the other columns through the various stages.
So such columns can be extracted from the data source and end up on your data target without explicitly
being operated on in between.

Columns you are importing do not have inherent column definitions, and so WebSphere DataStage
cannot always tell where there are extra columns that need propagating. You can only use RCP on
Column Import stages if you have used the Schema File property (see ″Schema File″ on page Schema
File) to specify a schema which describes all the columns in the column. You need to specify the same
schema file for any similar stages in the job where you want to propagate columns. Stages that will
require a schema file are:
v Sequential File
v File Set
v External Source
v External Target
v Column Import
v Column Export

Chapter 37. Column Import stage 423

424 Parallel Job Developer Guide
Chapter 38. Column Export stage
The Column Export stage is a restructure stage. It can have a single input link, a single output link and a
single rejects link.

The Column Export stage exports data from a number of columns of different data types into a single
column of data type string or binary. It is the complementary stage to Column Import (see Chapter 37,
“Column Import stage,” on page 415).

The input data column definitions determine the order in which the columns are exported to the single
output column. Information about how the single column being exported is delimited is given in the
Formats tab of the Input page. You can optionally save reject records, that is, records whose export was
rejected.

In addition to exporting a column you can also pass other columns straight through the stage. So, for
example, you could pass a key column straight through.

The stage editor has three pages:

v Stage Page. This is always present and is used to specify general information about the stage.
v Input Page. This is where you specify the details about the single input set from which you are
selecting records.
v Output Page. This is where you specify details about the processed data being output from the stage.

Examples
This section gives examples of input and output data from a Column Export stage to give you a better
idea of how the stage works.

In this example the Column Export stage extracts data from three input columns and outputs two of
them in a single column of type string and passes the other through. The example assumes that the job is
running sequentially. The column definitions for the input data set are as follows:

© Copyright IBM Corp. 2006 425

Column name SQL type Length Scale
value Decimal 5 2
SN SmallInt 1
code Char 4

The following are the rows from the input data set:

value SN code
000.00 0 aaaa
001.00 1 bbbb
002.00 2 cccc
003.00 3 dddd
004.00 4 eeee
005.00 5 ffff
006.00 6 gggg
007.00 7 hhhh
008.00 8 iiii
009.00 9 jjjj

The import table definition is supplied on the Output Page Columns tab. For our example, the definition
would be:

Column name SQL type Length Scale

code Char 4
exported_col Char

You have to give WebSphere DataStage information about how to delimit the exported data when it
combines it into a single column. This is done on the Input page Format Tab. For this example, you
specify a data format of text, a Field Delimiter of comma, and a Quote type of double.

426 Parallel Job Developer Guide

 .

The Properties of the Column Export stage are set as follows:

The output data set will be:

exported_co
code
(″20 0 0 0.00″ , ″0″)
aaaa

Chapter 38. Column Export stage 427

(″20 0 0 1.00″ , ″1″)
bbbb
(″20 0 0 2.00″ , ″2″)
cccc
(″20 0 0 3.00″ , ″3″)
dddd
(″20 0 0 4.00″ , ″4″)
eeee
(″20 0 0 5.00″ , ″5″)
ffff
(″20 0 0 6.00″ , ″6″)
gggg
(″20 0 0 7.00″ , ″7″)
hhhh
(″20 0 0 8.00″ , ″8″)
iiii
(″20 0 0 9.00″ , ″9″)
jjjj

Must do’s
WebSphere DataStage has many defaults which means that it can be very easy to include Column Export
stages in a job. This section specifies the minimum steps to take to get a Column Export stage
functioning. WebSphere DataStage provides a versatile user interface, and there are many shortcuts to
achieving a particular end, this section describes the basic method, you will learn where the shortcuts are
when you get familiar with the product.

To use a Column Export stage:

v In the Stage page Partitioning Tab, under the Input category:
– Choose the Column method, this is Explicit by default, meaning you specify explicitly choose input
columns as sources. The alternative is to specify a schema file.
– If you are using the Explicit method, choose the input column(s) to carry your exported input
column. Repeat the Column to Export property to specify all the columns you need.
– If you are using the Schema File method, specify the schema file that gives the output column
details.
Under the Output category:
– Choose the Export Column Type. This is Binary by default, but you can also choose VarChar. This
specifies the format of the column you are exporting to.
– Specify the column you are exporting to in the Export Output Column property.
v In the Input page Format Tab specify the format of the column you are exporting. This informs
WebSphere DataStage about delimiters and enables it to combine multiple columns into a single
column with delimiters.
v In the Output page Mapping Tab check that the input columns are mapping onto the output columns
as you expect. The mapping is carried out according to what you specified in the Properties tab.

Stage page
The General tab allows you to specify an optional description of the stage. The Properties tab lets you
specify what the stage does. The Advanced tab allows you to specify how the stage executes.

428 Parallel Job Developer Guide

Properties tab
The Properties tab allows you to specify properties which determine what the stage actually does. Some
of the properties are mandatory, although many have default settings. Properties without default settings
appear in the warning color (red by default) and turn black when you supply a value for them.

The following table gives a quick reference list of the properties and their attributes. A more detailed
description of each property follows.

Category/
Property Values Default Mandatory? Repeats? Dependent of
Options/Export Output Column N/A Y N N/A
Output Column
Options/Export Binary/ VarChar Binary N N N/A
Column Type
Options/Reject Continue (warn) Continue N N N/A
Mode /Output
Options/Column Input Column N/A N Y N/A
to Export
Options/Schema Pathname N/A N N N/A
File

Options category
Export output column

Specifies the name of the single column to which the input column or columns are exported.

Export column type

Specify either binary or VarChar (string).

Reject mode

The values of this property specify the following actions:

v Output. The stage continues when it encounters a reject record and writes the record to the rejects link.
v Continue(warn). The stage is to continue but report failures to the log file.

Column to export

Specifies an input column the stage extracts data from. The format properties for this column can be set
on the Format tab of the Input page. Repeat the property to specify multiple input columns. You can use
the Column Selection dialog box to select multiple columns at once if required. The order of the Columns
to Export that you specify should match the order on the Columns tab. If it does not, the order on the
Columns tab overrides the order of the properties.

Schema file

Instead of specifying the source data details via input column definitions, you can use a schema file
(note, however, that if you have defined columns on the Columns tab, you should ensure these match the
schema file). Type in a pathname or browse for a schema file.

Chapter 38. Column Export stage 429

Advanced tab
This tab allows you to specify the following:
v Execution Mode. The stage can execute in parallel mode or sequential mode. In parallel mode the
input data is processed by the available nodes as specified in the Configuration file, and by any node
constraints specified on the Advanced tab. In Sequential mode the entire data set is processed by the
conductor node.
v Combinability mode. This is Auto by default, which allows WebSphere DataStage to combine the
operators that underlie parallel stages so that they run in the same process if it is sensible for this type
of stage.
v Preserve partitioning. This is Propagate by default. It adopts Set or Clear from the previous stage. You
can explicitly select Set or Clear. Select Set to request that next stage in the job should attempt to
maintain the partitioning.
v Node pool and resource constraints. Select this option to constrain parallel execution to the node pool
or pools and/or resource pool or pools specified in the grid. The grid allows you to make choices from
drop down lists populated from the Configuration file.
v Node map constraint. Select this option to constrain parallel execution to the nodes in a defined node
map. You can define a node map by typing node numbers into the text box or by clicking the browse
button to open the Available Nodes dialog box and selecting nodes from there. You are effectively
defining a new node pool for this stage (in addition to any node pools defined in the Configuration
file).

Input page
The Input page allows you to specify details about the incoming data sets. The Column Export stage
expects one incoming data set.

The General tab allows you to specify an optional description of the input link. The Partitioning tab
allows you to specify how incoming data is partitioned before being exported. The Format tab allows you
to specify details how data in the column you are exporting will be formatted. The Columns tab specifies
the column definitions of incoming data. The Advanced tab allows you to change the default buffering
settings for the input link.

Details about Column Export stage partitioning are given in the following section. See ″Stage Editors,″ for
a general description of the other tabs.

Partitioning tab
The Partitioning tab allows you to specify details about how the incoming data is partitioned or collected
before it is exported. It also allows you to specify that the data should be sorted before being operated
on.

By default the stage partitions in Auto mode. This attempts to work out the best partitioning method
depending on execution modes of current and preceding stages and how many nodes are specified in the
Configuration file.

If the Column Export stage is operating in sequential mode, it will first collect the data using the default
Auto collection method.

The Partitioning tab allows you to override this default behavior. The exact operation of this tab depends
on:
v Whether the Column Export stage is set to execute in parallel or sequential mode.
v Whether the preceding stage in the job is set to execute in parallel or sequential mode.

430 Parallel Job Developer Guide

If the Column Export stage is set to execute in parallel, then you can set a partitioning method by
selecting from the Partition type drop-down list. This will override any current partitioning.

If the Column Export stage is set to execute in sequential mode, but the preceding stage is executing in
parallel, then you can set a collection method from the Collector type drop-down list. This will override
the default collection method.

The following partitioning methods are available:

v (Auto). WebSphere DataStage attempts to work out the best partitioning method depending on
execution modes of current and preceding stages and how many nodes are specified in the
Configuration file. This is the default partitioning method for the Column Export stage.
v Entire. Each file written to receives the entire data set.
v Hash. The records are hashed into partitions based on the value of a key column or columns selected
from the Available list.
v Modulus. The records are partitioned using a modulus function on the key column selected from the
Available list. This is commonly used to partition on tag columns.
v Random. The records are partitioned randomly, based on the output of a random number generator.
v Round Robin. The records are partitioned on a round robin basis as they enter the stage.
v Same. Preserves the partitioning already in place.
v DB2. Replicates the DB2 partitioning method of a specific DB2 table. Requires extra properties to be
set. Access these properties by clicking the properties button.
v Range. Divides a data set into approximately equal size partitions based on one or more partitioning
keys. Range partitioning is often a preprocessing step to performing a total sort on a data set. Requires
extra properties to be set. Access these properties by clicking the properties button.

The following Collection methods are available:

v (Auto). This is the default collection method for Column Export stages. Normally, when you are using
Auto mode, WebSphere DataStage will eagerly read any row from any input partition as it becomes
available.
v Ordered. Reads all records from the first partition, then all records from the second partition, and so
on.
v Round Robin. Reads a record from the first input partition, then from the second partition, and so on.
After reaching the last partition, the operator starts over.
v Sort Merge. Reads records in an order based on one or more columns of the record. This requires you
to select a collecting key column from the Available list.

The Partitioning tab also allows you to specify that data arriving on the input link should be sorted
before being exported. The sort is always carried out within data partitions. If the stage is partitioning
incoming data the sort occurs after the partitioning. If the stage is collecting data, the sort occurs before
the collection. The availability of sorting depends on the partitioning or collecting method chosen (it is
not available for the default Auto methods).

Select the check boxes as follows:

v Perform Sort. Select this to specify that data coming in on the link should be sorted. Select the column
or columns to sort on from the Available list.
v Stable. Select this if you want to preserve previously sorted data sets. This is the default.
v Unique. Select this to specify that, if multiple records have identical sorting key values, only one
record is retained. If stable sort is also set, the first record is retained.

If NLS is enabled an additional button opens a dialog box allowing you to select a locale specifying the
collate convention for the sort.

Chapter 38. Column Export stage 431

You can also specify sort direction, case sensitivity, whether sorted as ASCII or EBCDIC, and whether null
columns will appear first or last for each column. Where you are using a keyed partitioning method, you
can also specify whether the column is used as a key for sorting, for partitioning, or for both. Select the
column in the Selected list and right-click to invoke the shortcut menu.

Format tab
The Format tab allows you to supply information about the format of the column you are exporting. You
use it in the same way as you would to describe the format of a flat file you were writing. The tab has a
similar format to the Properties tab.

Select a property type from the main tree then add the properties you want to set to the tree structure by
clicking on them in the Available properties to add window. You can then set a value for that property
in the Property Value box. Pop up help for each of the available properties appears if you over the mouse
pointer over it.

This description uses the terms ″record″ and ″row″ and ″field″ and ″column″ interchangeably.

The following sections list the Property types and properties available for each type.

Record level

These properties define details about how data records are formatted in the flat file. Where you can enter
a character, this can usually be an ASCII character or a multi-byte Unicode character (if you have NLS
enabled). The available properties are:

Fill char

Specify an ASCII character or a value in the range 0 to 255. You can also choose Space or Null from a
drop-down list. This character is used to fill any gaps in a written record caused by column positioning
properties. Set to 0 by default (which is the NULL character). For example, to set it to space you could
also type in the space character or enter 32. Note that this value is restricted to one byte, so you cannot
specify a multi-byte Unicode character.

Final delimiter string

Specify a string to be written after the last column of a record in place of the column delimiter. Enter one
or more characters, this precedes the record delimiter if one is used. Mutually exclusive with Final
delimiter, which is the default. For example, if you set Delimiter to comma and Final delimiter string to `,
` (comma space - you do not need to enter the inverted commas) all fields are delimited by a comma,
except the final field, which is delimited by a comma followed by an ASCII space character.

Final delimiter

Specify a single character to be written after the last column of a record in place of the field delimiter.
Type a character or select one of whitespace, end, none, null, tab, or comma. See the following diagram
for an illustration.
v whitespace. The last column of each record will not include any trailing white spaces found at the end
of the record.
v end. The last column of each record does not include the field delimiter. This is the default setting.
v none. The last column of each record does not have a delimiter; used for fixed-width fields.
v null. The last column of each record is delimited by the ASCII null character.
v comma. The last column of each record is delimited by the ASCII comma character.

432 Parallel Job Developer Guide

v tab. The last column of each record is delimited by the ASCII tab character.
record delimiter

Field , Field , Field , Last field nl

Final delimiter = end

field delimiter

Field , Field , Field , Last field , nl

Final delimiter = comma

When writing, a space is now inserted after every field except the last in the record. Previously, a space
was inserted after every field including the last. (If you want to revert to the pre-release 7.5 behavior of
inserting a space after the last field, set the APT_FINAL_DELIM_COMPATIBLE environment variable.

Intact

The intact property specifies an identifier of a partial schema. A partial schema specifies that only the
column(s) named in the schema can be modified by the stage. All other columns in the row are passed
through unmodified. The file containing the partial schema is specified in the Schema File property on
the Properties tab. This property has a dependent property, Check intact, but this is not relevant to input
links.

Record delimiter string

Specify a string to be written at the end of each record. Enter one or more characters. This is mutually
exclusive with Record delimiter, which is the default, record type and record prefix.

Record delimiter

Specify a single character to be written at the end of each record. Type a character or select one of the
following:
v UNIX Newline (the default)
v null

(To implement a DOS newline, use the Record delimiter string property set to ″\R\N″ or chooseFormat
as → DOS line terminator from the shortcut menu.)

Note: Record delimiter is mutually exclusive with Record delimiter string, Record prefix, and Record
type.

Record length

Select Fixed where fixed length fields are being written. WebSphere DataStage calculates the appropriate
length for the record. Alternatively specify the length of fixed records as number of bytes. This is not
used by default (default files are comma-delimited). The record is padded to the specified length with
either zeros or the fill character if one has been specified.

Record Prefix

Chapter 38. Column Export stage 433

Specifies that a variable-length record is prefixed by a 1-, 2-, or 4-byte length prefix. It is set to 1 by
default. This is mutually exclusive with Record delimiter, which is the default, and record delimiter string
and record type.

Record type

Specifies that data consists of variable-length blocked records (varying) or implicit records (implicit). If
you choose the implicit property, data is written as a stream with no explicit record boundaries. The end
of the record is inferred when all of the columns defined by the schema have been parsed. The varying
property allows you to specify one of the following IBM blocked or spanned formats: V, VB, VS, VBS, or
VR.

This property is mutually exclusive with Record length, Record delimiter, Record delimiter string, and
Record prefix and by default is not used.

Field defaults

Defines default properties for columns written to the file or files. These are applied to all columns
written, but can be overridden for individual columns from the Columns tab using the Edit Column
Metadata dialog box. Where you can enter a character, this can usually be an ASCII character or a
multi-byte Unicode character (if you have NLS enabled). The available properties are:
v Actual field length. Specifies the number of bytes to fill with the Fill character when a field is
identified as null. When WebSphere DataStage identifies a null field, it will write a field of this length
full of Fill characters. This is mutually exclusive with Null field value.
v Delimiter. Specifies the trailing delimiter of all fields in the record. Type an ASCII character or select
one of whitespace, end, none, null, comma, or tab.
– whitespace. Whitespace characters at the end of a column are ignored, i.e., are not treated as part of
the column.
– end. The end of a field is taken as the delimiter, i.e., there is no separate delimiter. This is not the
same as a setting of `None’ which is used for fields with fixed-width columns.
– none. No delimiter (used for fixed-width).
– null. ASCII Null character is used.
– comma. ASCII comma character is used.
– tab. ASCII tab character is used.
v Delimiter string. Specify a string to be written at the end of each field. Enter one or more characters.
This is mutually exclusive with Delimiter, which is the default. For example, specifying `, ` (comma
space - you do not need to enter the inverted commas) would have each field delimited by `, ` unless
overridden for individual fields.
v Null field length. The length in bytes of a variable-length field that contains a null. When a
variable-length field is written, WebSphere DataStage writes a length value of null field length if the
field contains a null. This property is mutually exclusive with null field value.
v Null field value. Specifies the value written to null field if the source is set to null. Can be a number,
string, or C-type literal escape character. For example, you can represent a byte value by \ooo, where
each o is an octal digit 0 - 7 and the first o is < 4, or by \xhh, where each h is a hexadecimal digit 0 - F.
You must use this form to encode non-printable byte values.
This property is mutually exclusive with Null field length and Actual length. For a fixed width data
representation, you can use Pad char (from the general section of Type defaults) to specify a repeated
trailing character if the value you specify is shorter than the fixed width of the field.
v Prefix bytes. Specifies that each column in the data file is prefixed by 1, 2, or 4 bytes containing, as a
binary value, either the column’s length or the tag value for a tagged field.

434 Parallel Job Developer Guide

 You can use this option with variable-length fields. Variable-length fields can be either delimited by a
character or preceded by a 1-, 2-, or 4-byte prefix containing the field length. WebSphere DataStage
inserts the prefix before each field.
This property is mutually exclusive with the Delimiter, Quote, and Final Delimiter properties, which
are used by default.
v Print field. This property is not relevant for input links.
v Quote. Specifies that variable length fields are enclosed in single quotes, double quotes, or another
character or pair of characters. Choose Single or Double, or enter a character. This is set to double
quotes by default.
When writing, WebSphere DataStage inserts the leading quote character, the data, and a trailing quote
character. Quote characters are not counted as part of a field’s length.
v Vector prefix. For fields that are variable length vectors, specifies a 1-, 2-, or 4-byte prefix containing
the number of elements in the vector. You can override this default prefix for individual vectors.
Variable-length vectors must use either a prefix on the vector or a link to another field in order to
specify the number of elements in the vector. If the variable length vector has a prefix, you use this
property to indicate the prefix length. WebSphere DataStage inserts the element count as a prefix of
each variable-length vector field. By default, the prefix length is assumed to be one byte.

Type defaults

These are properties that apply to all columns of a specific data type unless specifically overridden at the
column level. They are divided into a number of subgroups according to data type.

General

These properties apply to several data types (unless overridden at column level):
v Byte order. Specifies how multiple byte data types (except string and raw data types) are ordered.
Choose from:
– little-endian. The high byte is on the right.
– big-endian. The high byte is on the left.
– native-endian. As defined by the native format of the machine. This is the default.
v Data Format. Specifies the data representation format of a field. Applies to fields of all data types
except string, ustring, and raw and to record, subrec or tagged fields containing at least one field that
is neither string nor raw. Choose from:
– binary
– text (the default)
A setting of binary has different meanings when applied to different data types:
– For decimals, binary means packed.
– For other numerical data types, binary means ″not text″.
– For dates, binary is equivalent to specifying the julian property for the date field.
– For time, binary is equivalent to midnight_seconds.
– For timestamp, binary specifies that the first integer contains a Julian day count for the date portion
of the timestamp and the second integer specifies the time portion of the timestamp as the number
of seconds from midnight. A binary timestamp specifies that two 32-but integers are written.
By default data is formatted as text, as follows:
– For the date data type, text specifies that the data to be written contains a text-based date in the
form %yyyy-%mm-%dd or in the default date format if you have defined a new one on an NLS
system (see WebSphere DataStage NLS Guide).

Chapter 38. Column Export stage 435

 – For the decimal data type: a field represents a decimal in a string format with a leading space or ’-’
followed by decimal digits with an embedded decimal point if the scale is not zero. The destination
string format is: [+ | -]ddd.[ddd] and any precision and scale arguments are ignored.
– For numeric fields (int8, int16, int32, uint8, uint16, uint32, sfloat, and dfloat): WebSphere DataStage
assumes that numeric fields are represented as text.
– For the time data type: text specifies that the field represents time in the text-based form
%hh:%nn:%ss or in the default date format if you have defined a new one on an NLS system (see
WebSphere DataStage NLS Guide).
– For the timestamp data type: text specifies a text-based timestamp in the form %yyyy-%mm-%dd
%hh:%nn:%ss or in the default date format if you have defined a new one on an NLS system (see
WebSphere DataStage NLS Guide).
v Field max width. The maximum number of bytes in a column represented as a string. Enter a number.
This is useful where you are storing numbers as text. If you are using a fixed-width character set, you
can calculate the length exactly. If you are using variable-length character set, calculate an adequate
maximum width for your fields. Applies to fields of all data types except date, time, timestamp, and
raw; and record, subrec, or tagged if they contain at least one field of this type.
v Field width. The number of bytes in a field represented as a string. Enter a number. This is useful
where you are storing numbers as text. If you are using a fixed-width charset, you can calculate the
number of bytes exactly. If it’s a variable length encoding, base your calculation on the width and
frequency of your variable-width characters. Applies to fields of all data types except date, time,
timestamp, and raw; and record, subrec, or tagged if they contain at least one field of this type.
If you specify neither field width nor field max width, numeric fields written as text have the
following number of bytes as their maximum width:
– 8-bit signed or unsigned integers: 4 bytes
– 16-bit signed or unsigned integers: 6 bytes
– 32-bit signed or unsigned integers: 11 bytes
– 64-bit signed or unsigned integers: 21 bytes
– single-precision float: 14 bytes (sign, digit, decimal point, 7 fraction, ″E″, sign, 2 exponent)
– double-precision float: 24 bytes (sign, digit, decimal point, 16 fraction, ″E″, sign, 3 exponent)
v Pad char. Specifies the pad character used when strings or numeric values are written to an external
string representation. Enter a character (single-byte for strings, can be multi-byte for ustrings) or choose
null or space. The pad character is used when the external string representation is larger than required
to hold the written field. In this case, the external string is filled with the pad character to its full
length. Space is the default. Applies to string, ustring, and numeric data types and record, subrec, or
tagged types if they contain at least one field of this type.
v Character set. Specifies the character set. Choose from ASCII or EBCDIC. The default is ASCII. Applies
to all data types except raw and ustring and record, subrec, or tagged containing no fields other than
raw or ustring.

String

These properties are applied to columns with a string data type, unless overridden at column level.
v Export EBCDIC as ASCII. Select this to specify that EBCDIC characters are written as ASCII
characters. Applies to fields of the string data type and record, subrec, or tagged fields if they contain
at least one field of this type.
v Import ASCII as EBCDIC. Not relevant for input links.
For ASCII-EBCDIC and EBCDIC-ASCII conversion tables, see WebSphere DataStage Developer’s Help.

Decimal

These properties are applied to columns with a decimal data type unless overridden at column level.

436 Parallel Job Developer Guide

v Allow all zeros. Specifies whether to treat a packed decimal column containing all zeros (which is
normally illegal) as a valid representation of zero. Select Yes or No. The default is No.
v Decimal separator. Specify the ASCII character that acts as the decimal separator (period by default).
v Packed. Select an option to specify what the decimal columns contain, choose from:
– Yes to specify that the decimal columns contain data in packed decimal format (the default). This
has the following sub-properties:
Check. Select Yes to verify that data is packed, or No to not verify.
Signed. Select Yes to use the existing sign when writing decimal columns. Select No to write a
positive sign (0xf) regardless of the columns’ actual sign value.
– No (separate) to specify that they contain unpacked decimal with a separate sign byte. This has the
following sub-property:
Sign Position. Choose leading or trailing as appropriate.
– No (zoned) to specify that they contain an unpacked decimal in either ASCII or EBCDIC text. This
has the following sub-property:
Sign Position. Choose leading or trailing as appropriate.
– No (overpunch) to specify that the field has a leading or end byte that contains a character which
specifies both the numeric value of that byte and whether the number as a whole is negatively or
positively signed. This has the following sub-property:
Sign Position. Choose leading or trailing as appropriate.
v Precision. Specifies the precision where a decimal column is written in text format. Enter a number.
When a decimal is written to a string representation, WebSphere DataStage uses the precision and scale
defined for the source decimal field to determine the length of the destination string. The precision and
scale properties override this default. When they are defined, WebSphere DataStage truncates or pads
the source decimal to fit the size of the destination string. If you have also specified the field width
property, WebSphere DataStage truncates or pads the source decimal to fit the size specified by field
width.
v Rounding. Specifies how to round a decimal column when writing it. Choose from:
– up (ceiling). Truncate source column towards positive infinity. This mode corresponds to the IEEE
754 Round Up mode. For example, 1.4 becomes 2, -1.6 becomes -1.
– down (floor). Truncate source column towards negative infinity. This mode corresponds to the IEEE
754 Round Down mode. For example, 1.6 becomes 1, -1.4 becomes -2.
– nearest value. Round the source column towards the nearest representable value. This mode
corresponds to the COBOL ROUNDED mode. For example, 1.4 becomes 1, 1.5 becomes 2, -1.4
becomes -1, -1.5 becomes -2.
– truncate towards zero. This is the default. Discard fractional digits to the right of the right-most
fractional digit supported by the destination, regardless of sign. For example, if the destination is an
integer, all fractional digits are truncated. If the destination is another decimal with a smaller scale,
truncate to the scale size of the destination decimal. This mode corresponds to the COBOL
INTEGER-PART function. Using this method 1.6 becomes 1, -1.6 becomes -1.
v Scale. Specifies how to round a source decimal when its precision and scale are greater than those of
the destination. By default, when the WebSphere DataStage writes a source decimal to a string
representation, it uses the precision and scale defined for the source decimal field to determine the
length of the destination string. You can override the default by means of the precision and scale
properties. When you do, WebSphere DataStage truncates or pads the source decimal to fit the size of
the destination string. If you have also specified the field width property, WebSphere DataStage
truncates or pads the source decimal to fit the size specified by field width.

Numeric

These properties apply to integer and float fields unless overridden at column level.

Chapter 38. Column Export stage 437

v C_format. Perform non-default conversion of data from integer or floating-point data to a string. This
property specifies a C-language format string used for writing integer or floating point strings. This is
passed to sprintf(). For example, specifying a C-format of %x and a field width of 8 ensures that
integers are written as 8-byte hexadecimal strings.
v In_format. This property is not relevant for input links..
v Out_format. Format string used for conversion of data from integer or floating-point data to a string.
This is passed to sprintf(). By default, WebSphere DataStage invokes the C sprintf() function to convert a
numeric field formatted as either integer or floating point data to a string. If this function does not
output data in a satisfactory format, you can specify the out_format property to pass formatting
arguments to sprintf().

Date

These properties are applied to columns with a date data type unless overridden at column level. All of
these are incompatible with a Data Format setting of Text.
v Days since. Dates are written as a signed integer containing the number of days since the specified
date. Enter a date in the form %yyyy-%mm-%dd or in the default date format if you have defined a
new one on an NLS system (see WebSphere DataStage NLS Guide).
v Format string. The string format of a date. By default this is %yyyy-%mm-%dd. For details about the
format, see .
v Is Julian. Select this to specify that dates are written as a numeric value containing the Julian day. A
Julian day specifies the date as the number of days from 4713 BCE January 1, 12:00 hours (noon) GMT.

Time

These properties are applied to columns with a time data type unless overridden at column level. All of
these are incompatible with a Data Format setting of Text.
v Format string. Specifies the format of columns representing time as a string. For details about the
format, see “Time formats” on page 33
v Is midnight seconds. Select this to specify that times are written as a binary 32-bit integer containing
the number of seconds elapsed from the previous midnight.

Timestamp

These properties are applied to columns with a timestamp data type unless overridden at column level.
v Format string. Specifies the format of a column representing a timestamp as a string. Defaults to
%yyyy-%mm-%dd %hh:%nn:%ss. The format combines the format for date strings and time strings. See
“Date formats” on page 30 and “Time formats” on page 33.

Output page
The Output page allows you to specify details about data output from the Column Export stage. The
Column Export stage can have only one output link, but can also have a reject link carrying records that
have been rejected.

The General tab allows you to specify an optional description of the output link. The Columns tab
specifies the column definitions of the data. The Mapping tab allows you to specify the relationship
between the columns being input to the Column Export stage and the Output columns. The Advanced
tab allows you to change the default buffering settings for the output links.

Details about Column Export stage mapping is given in the following section. See ″Stage Editors,″ for a
general description of the other tabs.

438 Parallel Job Developer Guide

Mapping tab
For the Column Export stage the Mapping tab allows you to specify how the output columns are
derived, i.e., what input columns map onto them or how they are generated.

The left pane shows the input columns plus the composite column that the stage exports the specified
input columns to. These are read only and cannot be modified on this tab.

The right pane shows the output columns for each link. This has a Derivations field where you can
specify how the column is derived.You can fill it in by dragging input columns over, or by using the
Auto-match facility.

The remaining columns are all being exported to comp_col, which is the specified Export Column. You
could also pass the original columns through the stage, if required.

Reject link
You cannot change the details of a Reject link. The link uses the column definitions for the link rejecting
the data rows. Rows will be rejected if they do not match the expected schema.

Using RCP with Column Export stages

Runtime column propagation (RCP) allows WebSphere DataStage to be flexible about the columns you
define in a job. If RCP is enabled for a project, you can just define the columns you are interested in
using in a job, but ask WebSphere DataStage to propagate the other columns through the various stages.
So such columns can be extracted from the data source and end up on your data target without explicitly
being operated on in between.

You can only use RCP on Column Export stages if you have used the Schema File property (see ″Schema
File″ ) to specify a schema which describes all the columns in the column. You need to specify the same
schema file for any similar stages in the job where you want to propagate columns. Stages that will
require a schema file are:
v Sequential File
v File Set
v External Source
v External Target
v Column Import
v Column Export

Chapter 38. Column Export stage 439

440 Parallel Job Developer Guide
Chapter 39. Make Subrecord stage
The Make Subrecord stage is a restructure stage. It can have a single input link and a single output link.

The Make Subrecord stage combines specified vectors in an input data set into a vector of subrecords
whose columns have the names and data types of the original vectors. You specify the vector columns to
be made into a vector of subrecords and the name of the new subrecord. See ″Complex Data Types″ for
an explanation of vectors and subrecords.
Vector 1
Column 1 0 1 2 3

Vector 2
Column 2 0 1 2 3 4

input data
Vector 3
Column 3 0 1 2 3

Vector 4
Column 4 0 1 2

Column 1 Subrec Subrec Subrec Subrec Subrec

output data
0 vector1.0 0 vector1.1 0 vector1.2 0 vector1.3 0 pad
1 vector2.0 1 vector2.1 1 vector2.2 1 vector2.3 1 vector2.4
2 vector3.0 2 vector3.1 2 vector3.2 2 vector3.3 2 pad
3 vector4.0 3 vector4.1 3 vector4.2 3 pad 3 pad

Shows how four separate columns are combined into a single subrecord

The Split Subrecord stage performs the inverse operation. See ″Split Subrecord Stage.″

The length of the subrecord vector created by this operator equals the length of the longest vector column
from which it is created. If a variable-length vector column was used in subrecord creation, the subrecord
vector is also of variable length.

Vectors that are smaller than the largest combined vector are padded with default values: NULL for
nullable columns and the corresponding type-dependent value for non-nullable columns. When the Make
Subrecord stage encounters mismatched vector lengths, it warns you by writing to the job log.

You can also use the stage to make a simple subrecord rather than a vector of subrecords. If your input
columns are simple data types rather than vectors, they will be used to build a vector of subrecords of
length 1 - effectively a simple subrecord.

© Copyright IBM Corp. 2006 441

 Column 1 Keycol

Column 2 Colname1

input data

Column 3 Colname2

Column 4 Colname3

Column 5 Colname4

Column 1 Subrec
output data
Keycol
Colname1
Colname2
Colname3
Colname4

The stage editor has three pages:

v Stage Page. This is always present and is used to specify general information about the stage.
v Input Page. This is where you specify the details about the single input set from which you are
selecting records.
v Output Page. This is where you specify details about the processed data being output from the stage.

Examples
This section gives examples of input and output data from a Make Subrecord stage to give you a better
idea of how the stage works.

In this example the Make Subrecord stage extracts data from four input columns, three of which carry
vectors. The data is output in two columns, one carrying the vectors in a subrecord, and the non-vector
column being passed through the stage. The example assumes that the job is running sequentially. The
column definitions for the input data set are as follows

442 Parallel Job Developer Guide

Column name SQL type
key Char
acol Integer
bcol Char
ccol Char

The following are the rows from the input data set (superscripts represents the vector index):

Key acol bcol ccol

0 1 2 3 0 1 2
row A 12 13 4 64 Wills wombat bill william D00 1

row B 2206142213 Robin0Dally1Rob2RD3 G0A1

row C 7600152223 Beth0Betany1Bethany2Bets3 B071
row D 406181203 Heathcliff0HC1Hchop2Horror3 A011
row E 20416283 Chaz0Swot1Chazlet2Twerp3 C0H1
row F 180815283 kayser0Cuddles1KB2Ibn Kayeed3 M011
row G 1201016213 Jayne0Jane1J2JD3 F021
row H 1200162433 Ann0Anne1AK2AJK3 H0E1
0 1 2 3 0 1 2 3 0
row I 3 0 7 82 Kath Cath Catherine Katy H1
row J 500172023 upert0Rupe1Woopert2puss3 B0C1

The stage outputs the subrecord it builds from the input data in a single column called parent. The
column called key will be output separately. The output column definitions are as follows:

Column name SQL type

key Char
parent Char

The Properties of the Make Subrecord stage are set as follows:

Chapter 39. Make Subrecord stage 443

The output data set will be:

Key Parent
0 1 2 3
row A 12 13 4 64
Will wombat bill William
D 0 pad pad
B 22 6 4 21
Robin Dally Rob RD
G A pad pad
C 76 0 52 2
Beth Betany Bethany Bets
B 7 pad pad
D 4 6 81 0
Heathcliff HC Hchop Horror
A 1 pad pad
E 2 4 6 8
Chaz Swot Chazlet Twerp
C H pad pad
F 18 8 5 8
Kayser Cuddles KB Ibn Kayeed
M 1 pad pad
G 12 10 6 43
Jayne Jane J JD

444 Parallel Job Developer Guide

 Key Parent
F 2 pad pad
H 12 0 6 43
Ann Anne AK AJK
H E pad pad
I 3 0 7 82
Kath Cath Catherine Katy
C H pad pad
J 5 0 7 02
Rupert Rupe Woopert puss
B C pad pad

Must do’s
WebSphere DataStage has many defaults which means that it can be very easy to include Make
Subrecord stages in a job. This section specifies the minimum steps to take to get a Make Subrecord stage
functioning. WebSphere DataStage provides a versatile user interface, and there are many shortcuts to
achieving a particular end, this section describes the basic method, you will learn where the shortcuts are
when you get familiar with the product.

To use a Make Subrecord stage:

v In the Outputs Stage Properties Tab, under the Input category:
– Specify the vector column to combine into the subrecord, repeat the property to specify multiple
vector columns.
Under the Output category:
– Specify the Subrecord output column.

Stage page
The General tab allows you to specify an optional description of the stage. The Properties tab lets you
specify what the stage does. The Advanced tab allows you to specify how the stage executes.

Properties tab
The Properties tab allows you to specify properties that determine what the stage actually does. Some of
the properties are mandatory, although many have default settings. Properties without default settings
appear in the warning color (red by default) and turn black when you supply a value for them.

The following table gives a quick reference list of the properties and their attributes. A more detailed
description of each property follows.

Category/
Property Values Default Mandatory? Repeats? Dependent of
Options/ Output Column N/A Y N N/A
Subrecord Output
Column
Options/Vector Input Column N/A N Y Key
Column for
Subrecord

Chapter 39. Make Subrecord stage 445

Category/
Property Values Default Mandatory? Repeats? Dependent of
Options/Disable True/False False N N N/A
Warning of
Column Padding

Input category
Subrecord output column

Specify the name of the subrecord into which you want to combine the columns specified by the Vector
Column for Subrecord property.

Output category
Vector column for subrecord

Specify the name of the column to include in the subrecord. You can specify multiple columns to be
combined into a subrecord. For each column, specify the property followed by the name of the column to
include. You can use the Column Selection dialog box to select multiple columns at once if required.

Options category
Disable warning of column padding

When the stage combines vectors of unequal length, it pads columns and displays a message to this
effect. Optionally specify this property to disable display of the message.

Advanced tab
This tab allows you to specify the following:
v Execution Mode. The stage can execute in parallel mode or sequential mode. In parallel mode the
input data is processed by the available nodes as specified in the Configuration file, and by any node
constraints specified on the Advanced tab. In Sequential mode the entire data set is processed by the
conductor node.
v Combinability mode. This is Auto by default, which allows WebSphere DataStage to combine the
operators that underlie parallel stages so that they run in the same process if it is sensible for this type
of stage.
v Preserve partitioning. This is Propagate by default. It adopts Set or Clear from the previous stage. You
can explicitly select Set or Clear. Select Set to request that next stage in the job should attempt to
maintain the partitioning.
v Node pool and resource constraints. Select this option to constrain parallel execution to the node pool
or pools and/or resource pool or pools specified in the grid. The grid allows you to make choices from
drop down lists populated from the Configuration file.
v Node map constraint. Select this option to constrain parallel execution to the nodes in a defined node
map. You can define a node map by typing node numbers into the text box or by clicking the browse
button to open the Available Nodes dialog box and selecting nodes from there. You are effectively
defining a new node pool for this stage (in addition to any node pools defined in the Configuration
file).

Input page
The Input page allows you to specify details about the incoming data sets. The Make Subrecord stage
expects one incoming data set.

446 Parallel Job Developer Guide

The General tab allows you to specify an optional description of the input link. The Partitioning tab
allows you to specify how incoming data is partitioned before being converted. The Columns tab
specifies the column definitions of incoming data. The Advanced tab allows you to change the default
buffering settings for the input link.

Details about Make Subrecord stage partitioning are given in the following section. See ″Stage Editors,″
for a general description of the other tabs.

Partitioning tab
The Partitioning tab allows you to specify details about how the incoming data is partitioned or collected
before it is converted. It also allows you to specify that the data should be sorted before being operated
on.

By default the stage partitions in Auto mode.

If the Make Subrecord stage is operating in sequential mode, it will first collect the data using the default
Auto collection method.

The Partitioning tab allows you to override this default behavior. The exact operation of this tab depends
on:
v Whether the Make Subrecord stage is set to execute in parallel or sequential mode.
v Whether the preceding stage in the job is set to execute in parallel or sequential mode.

If the Make Subrecord stage is set to execute in parallel, then you can set a partitioning method by
selecting from the Partition type drop-down list. This will override any current partitioning.

If the Make Subrecord stage is set to execute in sequential mode, but the preceding stage is executing in
parallel, then you can set a collection method from the Collector type drop-down list. This will override
the default collection method.

The following partitioning methods are available:

v (Auto). WebSphere DataStage attempts to work out the best partitioning method depending on
execution modes of current and preceding stages and how many nodes are specified in the
Configuration file. This is the default method of the Make Subrecord stage.
v Entire. Each file written to receives the entire data set.
v Hash. The records are hashed into partitions based on the value of a key column or columns selected
from the Available list.
v Modulus. The records are partitioned using a modulus function on the key column selected from the
Available list. This is commonly used to partition on tag columns.
v Random. The records are partitioned randomly, based on the output of a random number generator.
v Round Robin. The records are partitioned on a round robin basis as they enter the stage.
v Same. Preserves the partitioning already in place. This is the default partitioning method for the Make
Subrecord stage.
v DB2. Replicates the DB2 partitioning method of a specific DB2 table. Requires extra properties to be
set. Access these properties by clicking the properties button.
v Range. Divides a data set into approximately equal size partitions based on one or more partitioning
keys. Range partitioning is often a preprocessing step to performing a total sort on a data set. Requires
extra properties to be set. Access these properties by clicking the properties button.

The following Collection methods are available:

Chapter 39. Make Subrecord stage 447

v (Auto). This is the default collection method for Make Subrecord stages. Normally, when you are using
Auto mode, WebSphere DataStage will eagerly read any row from any input partition as it becomes
available.
v Ordered. Reads all records from the first partition, then all records from the second partition, and so
on.
v Round Robin. Reads a record from the first input partition, then from the second partition, and so on.
After reaching the last partition, the operator starts over.
v Sort Merge. Reads records in an order based on one or more columns of the record. This requires you
to select a collecting key column from the Available list.

The Partitioning tab also allows you to specify that data arriving on the input link should be sorted
before being converted. The sort is always carried out within data partitions. If the stage is partitioning
incoming data the sort occurs after the partitioning. If the stage is collecting data, the sort occurs before
the collection. The availability of sorting depends on the partitioning or collecting method chosen (it is
not available for the default for the default Auto methods).

Select the check boxes as follows:

v Perform Sort. Select this to specify that data coming in on the link should be sorted. Select the column
or columns to sort on from the Available list.
v Stable. Select this if you want to preserve previously sorted data sets. This is the default.
v Unique. Select this to specify that, if multiple records have identical sorting key values, only one
record is retained. If stable sort is also set, the first record is retained.

If NLS is enabled an additional button opens a dialog box allowing you to select a locale specifying the
collate convention for the sort.

You can also specify sort direction, case sensitivity, whether sorted as ASCII or EBCDIC, and whether null
columns will appear first or last for each column. Where you are using a keyed partitioning method, you
can also specify whether the column is used as a key for sorting, for partitioning, or for both. Select the
column in the Selected list and right-click to invoke the shortcut menu.

Output page
The Output page allows you to specify details about data output from the Make Subrecord stage. The
Make Subrecord stage can have only one output link.

The General tab allows you to specify an optional description of the output link. The Columns tab
specifies the column definitions of the data. The Advanced tab allows you to change the default buffering
settings for the output link.

See ″Stage Editors,″ for a general description of the tabs.

448 Parallel Job Developer Guide

Chapter 40. Split Subrecord Stage
The Split Subrecord stage separates an input subrecord field into a set of top-level vector columns. It can
have a single input link and a single output link.

The stage creates one new vector column for each element of the original subrecord. That is, each
top-level vector column that is created has the same number of elements as the subrecord from which it
was created. The stage outputs columns of the same name and data type as those of the columns that

Column 1 Subrec Subrec Subrec Subrec Subrec

input data
0 vector1.0 0 vector1.1 0 vector1.2 0 vector1.3 0 pad
1 vector2.0 1 vector2.1 1 vector2.2 1 vector2.3 1 vector2.4
2 vector3.0 2 vector3.1 2 vector3.2 2 vector3.3 2 pad
3 vector4.0 3 vector4.1 3 vector4.2 3 pad 3 pad

Vector 1
Column 1 0 1 2 3

output data Vector 2

Column 2 0 1 2 3 4

Vector 3
Column 3 0 1 2 3

Vector 4
Column 4 0 1 2
comprise the subrecord.

The Make Subrecord stage performs the inverse operation (see, ″Make Subrecord Stage.″)

The stage editor has three pages:

v Stage Page. This is always present and is used to specify general information about the stage.
v Input Page. This is where you specify the details about the single input set from which you are
selecting records.

© Copyright IBM Corp. 2006 449

v Output Page. This is where you specify details about the processed data being output from the stage.

Examples
This section gives examples of input and output data from a Split Subrecord stage to give you a better
idea of how the stage works.

In this example the Split Subrecord stage extracts data from a subrecord containing three vectors. The
data is output in fours column, three carrying the vectors from the subrecord, plus another column which
is passed through the stage. The example assumes that the job is running sequentially. The column
definitions for the input data set are as follows:

Column name SQL type

key Char
parent Char

The following are the rows from the input data set (superscripts represents the vector index):

Key Parent
0 1 2 3
row A 12 13 4 64
Will wombat bill William
D 0 pad pad
B 22 6 4 21
Robin Dally Rob RD
G A pad pad
C 76 0 52 2
Beth Betany Bethany Bets
B 7 pad pad
D 4 6 81 0
Heathcliff HC Hchop Horror
A 1 pad pad
E 2 4 6 8
Chaz Swot Chazlet Twerp
C H pad pad
F 18 8 5 8
Kayser Cuddles KB Ibn Kayeed
M 1 pad pad
G 12 10 6 43
Jayne Jane J JD
F 2 pad pad
H 12 0 6 43
Ann Anne AK AJK
H E pad pad
I 3 0 7 82

450 Parallel Job Developer Guide

 Key Parent
Kath Cath Catherine Katy
C H pad pad
J 5 0 7 02
Rupert Rupe Woopert puss
B C pad pad

The stage outputs the data it extracts from the subrecord in three separate columns each carrying a
vector. The column called key will be output separately. The output column definitions are as follows:

Column name SQL type

key Char
acol Integer
bcol Char
ccol Char

The Subrecord column property is set to ’parent’ in the Properties tab.

The output data set will be (superscripts represents the vector index):

Key acol bcol ccol

0 1 2 3 0 1 2
row A 12 13 4 64 Wills wombat bill william D00 1

row B 2206142213 Robin0Dally1Rob2RD3 G0A1

row C 7600152223 Beth0Betany1Bethany2Bets3 B071
row D 406181203 Heathcliff0HC1Hchop2Horror3 A011
row E 20416283 Chaz0Swot1Chazlet2Twerp3 C0H1
row F 180815283 kayser0Cuddles1KB2Ibn Kayeed3 M011
row G 1201016213 Jayne0Jane1J2JD3 F021
row H 1200162433 Ann0Anne1AK2AJK3 H0E1
row I 300172823 Kath0Cath1Catherine2Katy3 0
H1
row J 500172023 Rupert0Rupe1Woopert2puss3 B0C1

Must do’s
WebSphere DataStage has many defaults which means that it can be very easy to include Split Subrecord
stages in a job. This section specifies the minimum steps to take to get a Split Subrecord stage
functioning. WebSphere DataStage provides a versatile user interface, and there are many shortcuts to
achieving a particular end, this section describes the basic method, you will learn where the shortcuts are
when you get familiar with the product.

To use a Split Subrecord stage:

v In the Outputs Stage Properties Tab, under the Input category:
– Specify the subrecord column that the stage will extract vectors from.

Chapter 40. Split Subrecord Stage 451

Stage page
The General tab allows you to specify an optional description of the stage. The Properties tab lets you
specify what the stage does. The Advanced tab allows you to specify how the stage executes.

Properties tab
The Properties tab allows you to specify properties which determine what the stage actually does. The
Split Subrecord only has one property, and you must supply a value for this.

The following table gives a quick reference list of the properties and their attributes. A more detailed
description of each property follows.

Category/
Property Values Default Mandatory? Repeats? Dependent of
Options/ Input Column N/A Y N N/A
Subrecord
Column

Options category
Subrecord column

Specifies the name of the vector whose elements you want to promote to a set of similarly named
top-level columns.

Advanced tab
This tab allows you to specify the following:
v Execution Mode. The stage can execute in parallel mode or sequential mode. In parallel mode the
input data is processed by the available nodes as specified in the Configuration file, and by any node
constraints specified on the Advanced tab. In Sequential mode the entire data set is processed by the
conductor node.
v Combinability mode. This is Auto by default, which allows WebSphere DataStage to combine the
operators that underlie parallel stages so that they run in the same process if it is sensible for this type
of stage.
v Preserve partitioning. This is Propagate by default. It adopts Set or Clear from the previous stage. You
can explicitly select Set or Clear. Select Set to request that next stage in the job should attempt to
maintain the partitioning.
v Node pool and resource constraints. Select this option to constrain parallel execution to the node pool
or pools and/or resource pool or pools specified in the grid. The grid allows you to make choices from
drop down lists populated from the Configuration file.
v Node map constraint. Select this option to constrain parallel execution to the nodes in a defined node
map. You can define a node map by typing node numbers into the text box or by clicking the browse
button to open the Available Nodes dialog box and selecting nodes from there. You are effectively
defining a new node pool for this stage (in addition to any node pools defined in the Configuration
file).

Input page
The Input page allows you to specify details about the incoming data sets. There can be only one input to
the Split Subrecord stage.

452 Parallel Job Developer Guide

The General tab allows you to specify an optional description of the input link. The Partitioning tab
allows you to specify how incoming data is partitioned before being converted. The Columns tab
specifies the column definitions of incoming data. The Advanced tab allows you to change the default
buffering settings for the input link.

Details about Split Subrecord stage partitioning are given in the following section. See ″Stage Editors,″ for
a general description of the other tabs.

Partitioning tab
The Partitioning tab allows you to specify details about how the incoming data is partitioned or collected
before it is converted. It also allows you to specify that the data should be sorted before being operated
on.

By default the stage partitions in Auto mode. This attempts to work out the best partitioning method
depending on execution modes of current and preceding stages and how many nodes are specified in the
Configuration file.

If the Split Subrecord stage is operating in sequential mode, it will first collect the data using the default
Auto collection method.

The Partitioning tab allows you to override this default behavior. The exact operation of this tab depends
on:
v Whether the Split Subrecord stage is set to execute in parallel or sequential mode.
v Whether the preceding stage in the job is set to execute in parallel or sequential mode.

If the Split Subrecord stage is set to execute in parallel, then you can set a partitioning method by
selecting from the Partition type drop-down list. This will override any current partitioning.

If the Split Subrecord stage is set to execute in sequential mode, but the preceding stage is executing in
parallel, then you can set a collection method from the Collector type drop-down list. This will override
the default collection method.

The following partitioning methods are available:

v (Auto). WebSphere DataStage attempts to work out the best partitioning method depending on
execution modes of current and preceding stages and how many nodes are specified in the
Configuration file. This is the default partitioning method for the Split Subrecord stage.
v Entire. Each file written to receives the entire data set.
v Hash. The records are hashed into partitions based on the value of a key column or columns selected
from the Available list.
v Modulus. The records are partitioned using a modulus function on the key column selected from the
Available list. This is commonly used to partition on tag fields.
v Random. The records are partitioned randomly, based on the output of a random number generator.
v Round Robin. The records are partitioned on a round robin basis as they enter the stage.
v Same. Preserves the partitioning already in place.
v DB2. Replicates the DB2 partitioning method of a specific DB2 table. Requires extra properties to be
set. Access these properties by clicking the properties button.
v Range. Divides a data set into approximately equal size partitions based on one or more partitioning
keys. Range partitioning is often a preprocessing step to performing a total sort on a data set. Requires
extra properties to be set. Access these properties by clicking the properties button.

The following Collection methods are available:

Chapter 40. Split Subrecord Stage 453

v (Auto). This is the default collection method for Split Subrecord stages. Normally, when you are using
Auto mode, WebSphere DataStage will eagerly read any row from any input partition as it becomes
available.
v Ordered. Reads all records from the first partition, then all records from the second partition, and so
on.
v Round Robin. Reads a record from the first input partition, then from the second partition, and so on.
After reaching the last partition, the operator starts over.
v Sort Merge. Reads records in an order based on one or more columns of the record. This requires you
to select a collecting key column from the Available list.

The Partitioning tab also allows you to specify that data arriving on the input link should be sorted
before being converted. The sort is always carried out within data partitions. If the stage is partitioning
incoming data the sort occurs after the partitioning. If the stage is collecting data, the sort occurs before
the collection. The availability of sorting depends on the partitioning or collecting method chosen (it is
not available for the default Auto methods).

Select the check boxes as follows:

v Perform Sort. Select this to specify that data coming in on the link should be sorted. Select the column
or columns to sort on from the Available list.
v Stable. Select this if you want to preserve previously sorted data sets. This is the default.
v Unique. Select this to specify that, if multiple records have identical sorting key values, only one
record is retained. If stable sort is also set, the first record is retained.

If NLS is enabled an additional button opens a dialog box allowing you to select a locale specifying the
collate convention for the sort.

You can also specify sort direction, case sensitivity, whether sorted as ASCII or EBCDIC, and whether null
columns will appear first or last for each column. Where you are using a keyed partitioning method, you
can also specify whether the column is used as a key for sorting, for partitioning, or for both. Select the
column in the Selected list and right-click to invoke the shortcut menu.

Output page
The Output page allows you to specify details about data output from the Split Subrecord stage. The
Split Subrecord stage can have only one output link.

The General tab allows you to specify an optional description of the output link. The Columns tab
specifies the column definitions of the data. The Advanced tab allows you to change the default buffering
settings for the output link.

See ″Stage Editors,″ for a general description of these tabs.

454 Parallel Job Developer Guide

Chapter 41. Combine Records stage
The Combine Records stage is restructure stage. It can have a single input link and a single output link.

The Combine Records stage combines records (i.e., rows), in which particular key-column values are
identical, into vectors of subrecords. As input, the stage takes a data set in which one or more columns
are chosen as keys. All adjacent records whose key columns contain the same value are gathered into the
same record as subrecords.
Column 1 Keycol

Column 2 Colname1

input data

Column 3 Colname2

Column 4 Colname3

Column 5 Colname4

All elements
share same
value of Keycol

Column 1 Subrec Subrec Subrec Subrec Subrec

output data
Keycol Keycol Keycol Keycol Keycol
Colname1 Colname1 Colname1 Colname1 Colname1
Colname2 Colname2 Colname2 Colname2 Colname2
Colname3 Colname3 Colname3 Colname3 Colname3
Colname4 Colname4 Colname4 Colname4 Colname4

The data set input to the Combine Records stage must be key partitioned and sorted. This ensures that
rows with the same key column values are located in the same partition and will be processed by the
same node. Choosing the (auto) partitioning method will ensure that partitioning and sorting is done. If
sorting and partitioning are carried out on separate stages before the Combine Records stage, WebSphere
DataStage in auto mode will detect this and not repartition (alternatively you could explicitly specify the
Same partitioning method).

© Copyright IBM Corp. 2006 455

The stage editor has three pages:
v Stage Page. This is always present and is used to specify general information about the stage.
v Input Page. This is where you specify the details about the single input set from which you are
selecting records.
v Output Page. This is where you specify details about the processed data being output from the stage.

Examples
This section gives examples of input and output data from a Combine Records stage to give you a better
idea of how the stage works.

Example 1
This example assumes that the job is running sequentially. The column definitions for the input data set
are as follows:

Column name Key SQL type

keycol Yes Char
col1 TinyInt
col2 Time
col3 Dat

The following are some rows from the input data set:

col1 col2 col3 col4

row 1 00:11:01 1960-01-02 A
row 3 08:45:54 1946-09-15 A
row 1 12:59:00 1955-12-22 B
row 2 07:33:04 1950-03-10 B
row 2 12:00:00 1967-02-06 B
row 2 07:37:04 1950-03-10 B
row 3 07:56:03 1977-04-14 B
row 3 09:58:02 1960-05-18 B
row 1 11:43:02 1980-06-03 C
row 2 01:30:01 1985-07-07 C
row 2 11:30:01 1985-07-07 C
row 3 10:28:02 1992-11-23 C
row 3 12:27:00 1929-08-11 C
row 3 06:33:03 1999-10-19 C
row 3 11:18:22 1992-11-23 C

Once combined by the stage, each group of rows will be output in a single column called supercool. This
contains the keycoll, col1, col2, and col3 columns. (If you do not take advantage of the runtime column
propagation feature, you would have to set up the subrecord using the Edit Column Meta Data dialog
box to set a level number for each of the columns the subrecord column contains.)

456 Parallel Job Developer Guide

Level number Column name Key SQL type
subreccol Char
02 keycol Char Yes
02 col1 TinyInt
02 col2 Time
02 col3 Date

The Properties of the stage are set as follows:

The Output data set will be:

subreccol
vector index col1 col2 col3 Keycol
row 0 1 00:11:01 1960-01-02 A
1 3 08:45:54 1946-09-15 A
row 0 1 12:59:00 1955-12-22 B
1 2 07:33:04 1950-03-10 B
2 2 12:00:00 1967-02-06 B
3 2 07:37:04 1950-03-10 B
4 3 07:56:03 1977-04-14 B
5 3 09:58:02 1960-05-18 B
row 0 1 11:43:02 1980-06-03 C
1 2 01:30:01 1985-07-07 C
2 2 11:30:01 1985-07-07 C
3 3 10:28:02 1992-11-23 C

Chapter 41. Combine Records stage 457

 subreccol
vector index col1 col2 col3 Keycol
4 3 12:27:00 1929-08-11 C
5 3 06:33:03 1999-10-19 C
6 3 11:18:22 1992-11-23 C

Example 2
This example shows a more complex structure that can be derived using the Top Level Keys Property.
This can be set to True to indicate that key columns should be left as top level columns and not included
in the subrecord.This example assumes that the job is running sequentially. The same column definition
are used, except both col1 and keycol are defined as keys.

Column name Key SQL type

keycol Yes Char
col1 Yes TinyInt
col2 Time
col3 Dat

The same input data set is used:

col1 col2 col3 col4

row 1 00:11:01 1960-01-02 A
row 3 08:45:54 1946-09-15 A
row 1 12:59:00 1955-12-22 B
row 2 07:33:04 1950-03-10 B
row 2 12:00:00 1967-02-06 B
row 2 07:37:04 1950-03-10 B
row 3 07:56:03 1977-04-14 B
row 3 09:58:02 1960-05-18 B
row 1 11:43:02 1980-06-03 C
row 2 01:30:01 1985-07-07 C
row 2 11:30:01 1985-07-07 C
row 3 10:28:02 1992-11-23 C
row 3 12:27:00 1929-08-11 C
row 3 06:33:03 1999-10-19 C
row 3 11:18:22 1992-11-23 C

The Output column definitions have two separate columns defined for the keys, as well as the column
carrying the subrecords:

Level number Column name Key SQL type

subreccol Char
02 keycol Char Yes

458 Parallel Job Developer Guide

Level number Column name Key SQL type
02 col1 TinyInt Yes
02 col2 Time
02 col3 Date

The properties of the stage are set as follows:

The Output data set will be:

Keycol col1 subreccol

vector index col2 col3
row A 1 0 00:11:01 1960-01-02
row A 3 0 08:45:54 1946-09-15
row B 1 0 12:59:00 1955-12-22
row B 2 0 07:33:04 1950-03-10
1 12:00:00 1967-02-06
2 07:37:04 1950-03-10
row B 3 0 07:56:03 1977-04-14
1 09:58:02 1960-05-18
row C 1 0 11:43:02 1980-06-03
row C 2 0 01:30:01 1985-07-07
1 11:30:01 1985-07-07
row C 3 0 10:28:02 1992-11-23
1 12:27:00 1929-08-11
2 06:33:03 1999-10-19

Chapter 41. Combine Records stage 459

 Keycol col1 subreccol
vector index col2 col3
3 11:18:22 1992-11-23

Must do’s
WebSphere DataStage has many defaults which means that it can be very easy to include Combine
Records stages in a job. This section specifies the minimum steps to take to get a Combine Records stage
functioning. WebSphere DataStage provides a versatile user interface, and there are many shortcuts to
achieving a particular end, this section describes the basic method, you will learn where the shortcuts are
when you get familiar with the product.

To use a Combine Records stage:

v In the Stage page Properties Tab, under the Output category:
– Specify the output column to carry the vector of subrecords in the Subrecord Output Column.
Under the Combine Keys category:
– Specify the key column. Repeat the property to specify a composite key. All adjacent rows sharing
the same value of the keys will be combined into a single row using the vector of subrecords
structure.

Stage page
The General tab allows you to specify an optional description of the stage. The Properties tab lets you
specify what the stage does. The Advanced tab allows you to specify how the stage executes. The NLS
Locale tab appears if your have NLS enabled on your system. It allows you to select a locale other than
the project default to determine collating rules.

Properties tab
The Properties tab allows you to specify properties which determine what the stage actually does. Some
of the properties are mandatory, although many have default settings. Properties without default settings
appear in the warning color (red by default) and turn black when you supply a value for them.

The following table gives a quick reference list of the properties and their attributes. A more detailed
description of each property follows.

Category/
Property Values Default Mandatory? Repeats? Dependent of
Options/ Output Column N/A Y N N/A
Subrecord Output
Column
Options/Key Input Column N/A Y Y N/A
Options/Case True/False True N N Key
Sensitive
Options/Top True/False False N N N/A
Level Keys

Outputs category
Subrecord output column

Specify the name of the subrecord that the Combine Records stage creates.
460 Parallel Job Developer Guide
Combine keys category
Key

Specify one or more columns. You can use the Column Selection dialog box to select multiple columns at
once if required. All records whose key columns contain identical values are gathered into the same
record as subrecords. If the Top Level Keys property is set to False, each column becomes the element of
a subrecord.

If the Top Level Keys property is set to True, the key column appears as a top-level column in the output
record as opposed to in the subrecord. All non-key columns belonging to input records with that key
column appear as elements of a subrecord in that key column’s output record. Key has the following
dependent property:
v Case Sensitive
Use this to property to specify whether each key is case sensitive or not. It is set to True by default; for
example, the values ″CASE″ and ″case″ would not be judged equivalent.

Options category
Top level keys

Specify whether to leave keys as top-level columns or have them put into the subrecord. False by default.

Advanced tab
This tab allows you to specify the following:
v Execution Mode. The stage can execute in parallel mode or sequential mode. In parallel mode the
input data is processed by the available nodes as specified in the Configuration file, and by any node
constraints specified on the Advanced tab. In Sequential mode the entire data set is processed by the
conductor node.
v Combinability mode. This is Auto by default, which allows WebSphere DataStage to combine the
operators that underlie parallel stages so that they run in the same process if it is sensible for this type
of stage.
v Preserve partitioning. This is Propagate by default. It adopts Set or Clear from the previous stage. You
can explicitly select Set or Clear. Select Set to request that next stage in the job should attempt to
maintain the partitioning.
v Node pool and resource constraints. Select this option to constrain parallel execution to the node pool
or pools and/or resource pools or pools specified in the grid. The grid allows you to make choices
from drop down lists populated from the Configuration file.
v Node map constraint. Select this option to constrain parallel execution to the nodes in a defined node
map. You can define a node map by typing node numbers into the text box or by clicking the browse
button to open the Available Nodes dialog box and selecting nodes from there. You are effectively
defining a new node pool for this stage (in addition to any node pools defined in the Configuration
file).

NLS Locale tab

This appears if you have NLS enabled on your system. It lets you view the current default collate
convention, and select a different one for this stage if required. You can also use a job parameter to
specify the locale, or browse for a file that defines custom collate rules. The collate convention defines the
order in which characters are collated. The Combine Records stage uses this when it is determining the
sort order for key columns. Select a locale from the list, or click the arrow button next to the list to use a
job parameter or browse for a collate file.

Chapter 41. Combine Records stage 461

Input page
The Input page allows you to specify details about the incoming data sets. The Combine Records stage
expects one incoming data set.

The General tab allows you to specify an optional description of the input link. The Partitioning tab
allows you to specify how incoming data is partitioned before being converted. The Columns tab
specifies the column definitions of incoming data. The Advanced tab allows you to change the default
buffering settings for the input link.

Details about Combine Records stage partitioning are given in the following section. See ″Stage Editors,″
for a general description of the other tabs.

Partitioning tab
The Partitioning tab allows you to specify details about how the incoming data is partitioned or collected
before it is converted. It also allows you to specify that the data should be sorted before being operated
on.

By default the stage partitions in Auto mode. This attempts to work out the best partitioning method
depending on execution modes of current and preceding stages and how many nodes are specified in the
Configuration file.Auto mode ensures that data being input to the Combine Records stage is hash
partitioned and sorted.

If the Combine Records stage is operating in sequential mode, it will first collect the data using the
default Auto collection method.

The Partitioning tab allows you to override this default behavior. The exact operation of this tab depends
on:
v Whether the Combine Records stage is set to execute in parallel or sequential mode.
v Whether the preceding stage in the job is set to execute in parallel or sequential mode.

If the Combine Records stage is set to execute in parallel, then you can set a partitioning method by
selecting from the Partition type drop-down list. This will override any current partitioning.

If the Combine Records stage is set to execute in sequential mode, but the preceding stage is executing in
parallel, then you can set a collection method from the Collector type drop-down list. This will override
the default collection method.

The following partitioning methods are available:

v (Auto). WebSphere DataStage attempts to work out the best partitioning method depending on
execution modes of current and preceding stages and how many nodes are specified in the
Configuration file. This is the default partitioning method for the Combine Records stage.
v Entire. Each file written to receives the entire data set.
v Hash. The records are hashed into partitions based on the value of a key column or columns selected
from the Available list.
v Modulus. The records are partitioned using a modulus function on the key column selected from the
Available list. This is commonly used to partition on tag fields.
v Random. The records are partitioned randomly, based on the output of a random number generator.
v Round Robin. The records are partitioned on a round robin basis as they enter the stage.
v Same. Preserves the partitioning already in place.
v DB2. Replicates the DB2 partitioning method of a specific DB2 table. Requires extra properties to be
set. Access these properties by clicking the properties button.

462 Parallel Job Developer Guide

v Range. Divides a data set into approximately equal size partitions based on one or more partitioning
keys. Range partitioning is often a preprocessing step to performing a total sort on a data set. Requires
extra properties to be set. Access these properties by clicking the properties button.

The following Collection methods are available:

v (Auto). This is the default collection method for Combine Records stages. Normally, when you are
using Auto mode, WebSphere DataStage will eagerly read any row from any input partition as it
becomes available. In the case of a Combine Records stage, Auto will also ensure that the collected
data is sorted.
v Ordered. Reads all records from the first partition, then all records from the second partition, and so
on.
v Round Robin. Reads a record from the first input partition, then from the second partition, and so on.
After reaching the last partition, the operator starts over.
v Sort Merge. Reads records in an order based on one or more columns of the record. This requires you
to select a collecting key column from the Available list.

The Partitioning tab also allows you to specify that data arriving on the input link should be sorted
before being converted. The sort is always carried out within data partitions. If the stage is partitioning
incoming data the sort occurs after the partitioning. If the stage is collecting data, the sort occurs before
the collection. The availability of sorting depends on the partitioning or collecting method chosen (it is
not available with the default auto methods).

Select the check boxes as follows:

v Perform Sort. Select this to specify that data coming in on the link should be sorted. Select the column
or columns to sort on from the Available list.
v Stable. Select this if you want to preserve previously sorted data sets. This is the default.
v Unique. Select this to specify that, if multiple records have identical sorting key values, only one
record is retained. If stable sort is also set, the first record is retained.

If NLS is enabled an additional button opens a dialog box allowing you to select a locale specifying the
collate convention for the sort.

You can also specify sort direction, case sensitivity, whether sorted as ASCII or EBCDIC, and whether null
columns will appear first or last for each column. Where you are using a keyed partitioning method, you
can also specify whether the column is used as a key for sorting, for partitioning, or for both. Select the
column in the Selected list and right-click to invoke the shortcut menu.

Output page
The Output page allows you to specify details about data output from the Combine Records stage. The
Combine Records stage can have only one output link.

The General tab allows you to specify an optional description of the output link. The Columns tab
specifies the column definitions of the data. The Advanced tab allows you to change the default buffering
settings for the output link.

See ″Stage Editors,″ for a general description of the tabs.

Chapter 41. Combine Records stage 463

464 Parallel Job Developer Guide
Chapter 42. Promote Subrecord sStage
The Promote Subrecord stage is a restructure stage. It can have a single input link and a single output
link.

The Promote Subrecord stage promotes the columns of an input subrecord to top-level columns. The
number of output columns equals the number of subrecord elements. The data types of the input
subrecord columns determine those of the corresponding top-level columns.

Column 1 Parent (subrecord)

Colname1
input data
Colname2
Colname3
Colname4

Column 1 Colname1

Column 2 Colname2

output data

Column 3 Colname3

Column 4 Colname4

The stage can also promote the columns in vectors of subrecords, in which case it acts as the inverse of
the Combine Subrecord stage (see Chapter 46, “Tail stage,” on page 497).

© Copyright IBM Corp. 2006 465

 Column 1 Subrec Subrec Subrec Subrec Subrec
input data
Keycol Keycol Keycol Keycol Keycol
Colname1 Colname1 Colname1 Colname1 Colname1
Colname2 Colname2 Colname2 Colname2 Colname2
Colname3 Colname3 Colname3 Colname3 Colname3
Colname4 Colname4 Colname4 Colname4 Colname4

Column 1 Keycol

output data
Column 2 Colname1

Column 3 Colname2

Column 4 Colname3

Column 5 Colname4

The Combine Records stage performs the inverse operation.

The stage editor has three pages:

v Stage Page. This is always present and is used to specify general information about the stage.
v Input Page. This is where you specify the details about the single input set from which you are
selecting records.
v Output Page. This is where you specify details about the processed data being output from the stage.

Examples
This section gives examples of input and output data from a Promote Subrecord stage to give you a
better idea of how the stage works.

Example 1
In this example the Promote Subrecord stage promotes the records of a simple subrecord to top level
columns. It extracts data from a single column containing a subrecord. The data is output in four
columns, each carrying a column from the subrecord. The example assumes that the job is running
sequentially. The column definition for the input data set contains a definition of a single column called
subrec.

466 Parallel Job Developer Guide

The following are the rows from the input data set:

subrec
subrecord column
name col1 col2 col3 col4
row 1 AAD Thurs No
row 2 ABD Thurs No
row 3 CAD Weds Yes
row 4 CCC Mon Yes
5 BDD Mon Yes
6 DAK Fri No
7 MDB Tues Yes

The stage outputs the data it extracts from the subrecord in four separate columns of appropriate type.
The output column definitions are as follows:

Column name SQL type

col1 TinyInt
col2 Char
col3 Char
col4 Char

The Subrecord Column property on the Properties tab of the Promote Subrecord stage is set to ’subrec’.

The output data set will be:

Col1 Col2 Col3 Col4

row 1 AAD Thurs No
row 2 ABD Thurs No
row 3 CAD Weds Yes
row 4 CCC Mon Yes

Example 2
This example shows how the Promote Subrecord would operate on an aggregated vector of subrecords,
as would be produced by the Combine Records stage. It assumes that the job is running sequentially. The
column definition for the input data set contains a definition of a single column called subrec.

The following are some rows from the input data set:

subreccol
vector index col1 col2 col3 Keycol
row 0 1 00:11:01 1960-01-02 A
1 3 08:45:54 1946-09-15 A
row 0 1 12:59:00 1955-12-22 B
1 2 07:33:04 1950-03-10 B

Chapter 42. Promote Subrecord sStage 467

 subreccol
vector index col1 col2 col3 Keycol
2 2 12:00:00 1967-02-06 B
3 2 07:37:04 1950-03-10 B
4 3 07:56:03 1977-04-14 B
5 3 09:58:02 1960-05-18 B
row 0 1 11:43:02 1980-06-03 C
1 2 01:30:01 1985-07-07 C
2 2 11:30:01 1985-07-07 C
3 3 10:28:02 1992-11-23 C
4 3 12:27:00 1929-08-11 C
5 3 06:33:03 1999-10-19 C
6 3 11:18:22 1992-11-23 C

Once the columns in the subrecords have been promoted the data will be output in four columns as
follows:

Column name Key SQL type

keycol Yes Char
col1 TinyInt
col2 Time
col3 Dat

The Subrecord Column property on the Properties tab of the Promote Subrecord stage is set to ’subrec’.

The Output data set will be:

col1 col2 col3 col4

row 1 00:11:01 1960-01-02 A
row 3 08:45:54 1946-09-15 A
row 1 12:59:00 1955-12-22 B
row 2 07:33:04 1950-03-10 B
row 2 12:00:00 1967-02-06 B
row 2 07:37:04 1950-03-10 B
row 3 07:56:03 1977-04-14 B
row 3 09:58:02 1960-05-18 B
row 1 11:43:02 1980-06-03 C
row 2 01:30:01 1985-07-07 C
row 2 11:30:01 1985-07-07 C
row 3 10:28:02 1992-11-23 C
row 3 12:27:00 1929-08-11 C
row 3 06:33:03 1999-10-19 C
row 3 11:18:22 1992-11-23 C

468 Parallel Job Developer Guide

Must do’s
WebSphere DataStage has many defaults which means that it can be very easy to include Promote
Subrecord stages in a job. This section specifies the minimum steps to take to get a Promote Subrecord
stage functioning. WebSphere DataStage provides a versatile user interface, and there are many shortcuts
to achieving a particular end, this section describes the basic method, you will learn where the shortcuts
are when you get familiar with the product.

To use a Promote Subrecord stage:

v In the Outputs Stage Properties Tab, under the Input category:
– Specify the subrecord column that the stage will promote subrecords from.

Stage page
The General tab allows you to specify an optional description of the stage. The Properties tab lets you
specify what the stage does. The Advanced tab allows you to specify how the stage executes.

Properties tab
The Promote Subrecord Stage has one property:

Category/
Property Values Default Mandatory? Repeats? Dependent of
Options/ Input Column N/A Y N N/A
Subrecord
Column

Options category
Subrecord column

Specifies the name of the subrecord whose elements will be promoted to top-level records.

Advanced tab
This tab allows you to specify the following:
v Execution Mode. The stage can execute in parallel mode or sequential mode. In parallel mode the
input data is processed by the available nodes as specified in the Configuration file, and by any node
constraints specified on the Advanced tab. In Sequential mode the entire data set is processed by the
conductor node.
v Combinability mode. This is Auto by default, which allows WebSphere DataStage to combine the
operators that underlie parallel stages so that they run in the same process if it is sensible for this type
of stage.
v Preserve partitioning. This is Propagate by default. It adopts Set or Clear from the previous stage. You
can explicitly select Set or Clear. Select Set to request that next stage in the job should attempt to
maintain the partitioning.
v Node pool and resource constraints. Select this option to constrain parallel execution to the node pool
or pools and/or resource pool or pools specified in the grid. The grid allows you to make choices from
drop down lists populated from the Configuration file.
v Node map constraint. Select this option to constrain parallel execution to the nodes in a defined node
map. You can define a node map by typing node numbers into the text box or by clicking the browse

Chapter 42. Promote Subrecord sStage 469

 button to open the Available Nodes dialog box and selecting nodes from there. You are effectively
defining a new node pool for this stage (in addition to any node pools defined in the Configuration
file).

Input page
The Input page allows you to specify details about the incoming data sets. The Promote Subrecord stage
expects one incoming data set.

The General tab allows you to specify an optional description of the input link. The Partitioning tab
allows you to specify how incoming data is partitioned before being converted. The Columns tab
specifies the column definitions of incoming data. The Advanced tab allows you to change the default
buffering settings for the input link.

Details about Promote Subrecord stage partitioning are given in the following section. See ″Stage Editors,″
for a general description of the other tabs.

Partitioning tab
The Partitioning tab allows you to specify details about how the incoming data is partitioned or collected
before it is converted. It also allows you to specify that the data should be sorted before being operated
on.

By default the stage partitions in Auto mode. This attempts to work out the best partitioning method
depending on execution modes of current and preceding stages and how many nodes are specified in the
Configuration file.

If the Promote Subrecord stage is operating in sequential mode, it will first collect the data using the
default Auto collection method.

The Partitioning tab allows you to override this default behavior. The exact operation of this tab depends
on:
v Whether the Promote Subrecord stage is set to execute in parallel or sequential mode.
v Whether the preceding stage in the job is set to execute in parallel or sequential mode.

If the Promote Subrecord stage is set to execute in parallel, then you can set a partitioning method by
selecting from the Partition type drop-down list. This will override any current partitioning.

If the Promote Subrecord stage is set to execute in sequential mode, but the preceding stage is executing
in parallel, then you can set a collection method from the Collector type drop-down list. This will
override the default collection method.

The following partitioning methods are available:

v (Auto). WebSphere DataStage attempts to work out the best partitioning method depending on
execution modes of current and preceding stages and how many nodes are specified in the
Configuration file. This is the default method for the Promote Subrecord stage.
v Entire. Each file written to receives the entire data set.
v Hash. The records are hashed into partitions based on the value of a key column or columns selected
from the Available list.
v Modulus. The records are partitioned using a modulus function on the key column selected from the
Available list. This is commonly used to partition on tag fields.
v Random. The records are partitioned randomly, based on the output of a random number generator.
v Round Robin. The records are partitioned on a round robin basis as they enter the stage.

470 Parallel Job Developer Guide

v Same. Preserves the partitioning already in place. This is the default partitioning method for the
Promote Subrecord stage.
v DB2. Replicates the DB2 partitioning method of a specific DB2 table. Requires extra properties to be
set. Access these properties by clicking the properties button.
v Range. Divides a data set into approximately equal size partitions based on one or more partitioning
keys. Range partitioning is often a preprocessing step to performing a total sort on a data set. Requires
extra properties to be set. Access these properties by clicking the properties button.

The following Collection methods are available:

v (Auto). This is the default collection method for Promote Subrecord stages. Normally, when you are
using Auto mode, WebSphere DataStage will eagerly read any row from any input partition as it
becomes available.
v Ordered. Reads all records from the first partition, then all records from the second partition, and so
on.
v Round Robin. Reads a record from the first input partition, then from the second partition, and so on.
After reaching the last partition, the operator starts over.
v Sort Merge. Reads records in an order based on one or more columns of the record. This requires you
to select a collecting key column from the Available list.

The Partitioning tab also allows you to specify that data arriving on the input link should be sorted
before being converted. The sort is always carried out within data partitions. If the stage is partitioning
incoming data the sort occurs after the partitioning. If the stage is collecting data, the sort occurs before
the collection. The availability of sorting depends on the partitioning methods chosen (it is not available
with the default auto methods).

Select the check boxes as follows:

v Perform Sort. Select this to specify that data coming in on the link should be sorted. Select the column
or columns to sort on from the Available list.
v Stable. Select this if you want to preserve previously sorted data sets. This is the default.
v Unique. Select this to specify that, if multiple records have identical sorting key values, only one
record is retained. If stable sort is also set, the first record is retained.

If NLS is enabled an additional button opens a dialog box allowing you to select a locale specifying the
collate convention for the sort.

You can also specify sort direction, case sensitivity, whether sorted as ASCII or EBCDIC, and whether null
columns will appear first or last for each column. Where you are using a keyed partitioning method, you
can also specify whether the column is used as a key for sorting, for partitioning, or for both. Select the
column in the Selected list and right-click to invoke the shortcut menu.

Output page
The Output page allows you to specify details about data output from the Promote Subrecord stage. The
Promote Subrecord stage can have only one output link.

The General tab allows you to specify an optional description of the output link. The Columns tab
specifies the column definitions of the data. The Advanced tab allows you to change the default buffering
settings for the output link.

See ″Stage Editors,″ for a general description of the tabs.

Chapter 42. Promote Subrecord sStage 471

472 Parallel Job Developer Guide
Chapter 43. Make Vector stage
The Make Vector stage is an active stage. It can have a single input link and a single output link.

The Make Vector stage combines specified columns of an input data record into a vector of columns. The
stage has the following requirements:
v The input columns must form a numeric sequence, and must all be of the same type.
v The numbers must increase by one.
v The columns must be named column_name0 to column_namen, where column_name starts the name
of a column and 0 and n are the first and last of its consecutive numbers.
v The columns do not have to be in consecutive order.

All these columns are combined into a vector of the same length as the number of columns (n+1). The
vector is called column_name. Any input columns that do not have a name of that form will not be
included in the vector but will be output as top level columns.

Column 1 Col0

Column 2 Col1
input data

Column 3 Col2

Column 4 Col3

Column 5 Col4

output data Column 1 Col0 Col1 Col2 Col3 Col4

The Split Vector stage performs the inverse operation. See ″Split Vector Stage.″

The stage editor has three pages:

v Stage Page. This is always present and is used to specify general information about the stage.

© Copyright IBM Corp. 2006 473

v Input Page. This is where you specify the details about the single input set from which you are
selecting records.
v Output Page. This is where you specify details about the processed data being output from the stage.

Examples
This section gives examples of input and output data from a Make Vector stage to give you a better idea
of how the stage works.

Example 1
In this example, all the input data will be included in the output vector. The example assumes that the
job is running sequentially. The column definitions for the input data set are in the following table. Note
the columns all have the same type and names in the form column_nameN.:

Column name SQL type

col0 TinyInt
col1 TinyInt
col2 TinyInt
col3 TinyInt
col4 TinyInt

The following are some rows from the input data set:

col0 col1 col2 col3 col4

row 3 6 2 9 9
row 3 2 7 2 4
row 7 8 8 5 3
row 4 8 7 1 6
row 1 6 2 5 1
row 0 1 6 7 8
row 9 9 6 4 2
row 0 8 4 4 3
row 1 7 2 5 3
row 7 9 4 7 8

The stage outputs the vectors it builds from the input data in a single column called col. You do not have
to explicitly define the output column name, WebSphere DataStage will do this for you as the job runs,
but you may wish to do so to make the job more understandable.

The Column’s Common Partial Name property is set to ’col’ in the Properties tab.

The output data set will be:

col
Vector index 0 1 2 3 4
row 3 6 2 9 9
row 3 2 7 2 4

474 Parallel Job Developer Guide

 col
Vector index 0 1 2 3 4
row 7 8 8 5 3
row 4 8 7 1 6
row 1 6 2 5 1
row 0 1 6 7 8
row 9 9 6 4 2
row 0 8 4 4 3
row 1 7 2 5 3
row 7 9 4 7 8

Example 2
In this example, there are additional columns as well as the ones that will be included in the vector. The
example assumes that the job is running sequentially. The column definitions for the input data set are
show below, note the additional columns called name and code:

Column name SQL type

name Char
code Char
col0 TinyInt
col1 TinyInt
col2 TinyInt
col3 TinyInt
col4 TinyInt

The following are some rows from the input data set:

Name Code col0 col1 col2 col3 col4

row Will D070 3 6 2 9 9
row Robin GA36 3 2 7 2 4
row Beth B777 7 8 8 5 3
row Heathcliff A100 4 8 7 1 6
row Chaz CH01 1 6 2 5 1
row Kayser CH02 0 1 6 7 8
row Jayne M122 9 9 6 4 2
row Ann F234 0 8 4 4 3
row Kath HE45 1 7 2 5 3
row Rupert BC11 7 9 4 7 8

The stage outputs the vectors it builds from the input data in a single column called column_name. The
two other columns are output separately. You do not have to explicitly define the output column names,
WebSphere DataStage will do this for you as the job runs, but you may wish to do so to make the job
more understandable.

Chapter 43. Make Vector stage 475

Column name SQL type
name Char
code Char
col Char

The Column’s Common Partial Name property is set to ’col’ in the Properties tab

The output data set will be:

col
Vector index 0 1 2 3 4
row Will D070 3 6 2 9 9
row Robin GA36 3 2 7 2 4
row Beth B777 7 8 8 5 3
row Heathcliff A100 4 8 7 1 6
row Chaz CH01 1 6 2 5 1
row Kayser CH02 0 1 6 7 8
row Jayne M122 9 9 6 4 2
row Ann F234 0 8 4 4 3
row Kath HE45 1 7 2 5 3
row Rupert BC11 7 9 4 7 8

Must do’s
WebSphere DataStage has many defaults which means that it can be very easy to include Make Vector
stages in a job. This section specifies the minimum steps to take to get a Make Vector stage functioning.
WebSphere DataStage provides a versatile user interface, and there are many shortcuts to achieving a
particular end, this section describes the basic method, you will learn where the shortcuts are when you
get familiar with the product.

To use a Make Vector stage:

v In the Stage Page Properties Tab:
– Specify the Column’s Common Partial Name, this is the column_name part that is shared by all the
columns in the input data set, which will be the name of the output column containing the vector.

Stage page
The General tab allows you to specify an optional description of the stage. The Properties tab lets you
specify what the stage does. The Advanced tab allows you to specify how the stage executes.

476 Parallel Job Developer Guide

Properties tab
The Make Vector stage has one property:

Category/
Property Values Default Mandatory? Repeats? Dependent of
Options/ Name N/A Y N N/A
Column’s
Common Partial
Name

Options category
Column’s common partial name

Specifies the beginning column_name of the series of consecutively numbered columns column_name0 to
column_namen to be combined into a vector called column_name.

Advanced tab
This tab allows you to specify the following:
v Execution Mode. The stage can execute in parallel mode or sequential mode. In parallel mode the
input data is processed by the available nodes as specified in the Configuration file, and by any node
constraints specified on the Advanced tab. In Sequential mode the entire data set is processed by the
conductor node.
v Combinability mode. This is Auto by default, which allows WebSphere DataStage to combine the
operators that underlie parallel stages so that they run in the same process if it is sensible for this type
of stage.
v Preserve partitioning. This is Propagate by default. It adopts Set or Clear from the previous stage. You
can explicitly select Set or Clear. Select Set to request that next stage in the job should attempt to
maintain the partitioning.
v Node pool and resource constraints. Select this option to constrain parallel execution to the node pool
or pools and/or resource pool or pools specified in the grid. The grid allows you to make choices from
drop down lists populated from the Configuration file.
v Node map constraint. Select this option to constrain parallel execution to the nodes in a defined node
map. You can define a node map by typing node numbers into the text box or by clicking the browse
button to open the Available Nodes dialog box and selecting nodes from there. You are effectively
defining a new node pool for this stage (in addition to any node pools defined in the Configuration
file).

Input page
The Input page allows you to specify details about the incoming data sets. The Make Vector stage expects
one incoming data set.

The General tab allows you to specify an optional description of the input link. The Partitioning tab
allows you to specify how incoming data is partitioned before being converted. The Columns tab
specifies the column definitions of incoming data. The Advanced tab allows you to change the default
buffering settings for the input link.

Details about Make Vector stage partitioning are given in the following section. See ″Stage Editors,″ for a
general description of the other tabs.

Chapter 43. Make Vector stage 477

Partitioning tab
The Partitioning tab allows you to specify details about how the incoming data is partitioned or collected
before it is converted. It also allows you to specify that the data should be sorted before being operated
on.

By default the stage partitions in Auto mode.

If the Make Vector stage is operating in sequential mode, it will first collect the data using the default
Auto collection method.

The Partitioning tab allows you to override this default behavior. The exact operation of this tab depends
on:
v Whether the Make Vector stage is set to execute in parallel or sequential mode.
v Whether the preceding stage in the job is set to execute in parallel or sequential mode.

If the Make Vector stage is set to execute in parallel, then you can set a partitioning method by selecting
from the Partition type drop-down list. This will override any current partitioning.

If the Make Vector stage is set to execute in sequential mode, but the preceding stage is executing in
parallel, then you can set a collection method from the Collector type drop-down list. This will override
the default collection method.

The following partitioning methods are available:

v (Auto). WebSphere DataStage attempts to work out the best partitioning method depending on
execution modes of current and preceding stages and how many nodes are specified in the
Configuration file. This is the default partitioning method.
v Entire. Each file written to receives the entire data set.
v Hash. The records are hashed into partitions based on the value of a key column or columns selected
from the Available list.
v Modulus. The records are partitioned using a modulus function on the key column selected from the
Available list. This is commonly used to partition on tag fields.
v Random. The records are partitioned randomly, based on the output of a random number generator.
v Round Robin. The records are partitioned on a round robin basis as they enter the stage.
v Same. Preserves the partitioning already in place. This is the default partitioning method for the Make
Vector stage.
v DB2. Replicates the DB2 partitioning method of a specific DB2 table. Requires extra properties to be
set. Access these properties by clicking the properties button.
v Range. Divides a data set into approximately equal size partitions based on one or more partitioning
keys. Range partitioning is often a preprocessing step to performing a total sort on a data set. Requires
extra properties to be set. Access these properties by clicking the properties button.

The following Collection methods are available:

v (Auto). This is the default collection method for Make Vector stages. Normally, when you are using
Auto mode, WebSphere DataStage will eagerly read any row from any input partition as it becomes
available.
v Ordered. Reads all records from the first partition, then all records from the second partition, and so
on.
v Round Robin. Reads a record from the first input partition, then from the second partition, and so on.
After reaching the last partition, the operator starts over.
v Sort Merge. Reads records in an order based on one or more columns of the record. This requires you
to select a collecting key column from the Available list.

478 Parallel Job Developer Guide

The Partitioning tab also allows you to specify that data arriving on the input link should be sorted
before being converted. The sort is always carried out within data partitions. If the stage is partitioning
incoming data the sort occurs after the partitioning. If the stage is collecting data, the sort occurs before
the collection. The availability of sorting depends on the partitioning or collecting method chosen (it is
not available with the default Auto methods).

Select the check boxes as follows:

v Perform Sort. Select this to specify that data coming in on the link should be sorted. Select the column
or columns to sort on from the Available list.
v Stable. Select this if you want to preserve previously sorted data sets. This is the default.
v Unique. Select this to specify that, if multiple records have identical sorting key values, only one
record is retained. If stable sort is also set, the first record is retained.

If NLS is enabled an additional button opens a dialog box allowing you to select a locale specifying the
collate convention for the sort.

You can also specify sort direction, case sensitivity, whether sorted as ASCII or EBCDIC, and whether null
columns will appear first or last for each column. Where you are using a keyed partitioning method, you
can also specify whether the column is used as a key for sorting, for partitioning, or for both. Select the
column in the Selected list and right-click to invoke the shortcut menu.

Output page
The Output page allows you to specify details about data output from the Make Vector stage. The Make
Vector stage can have only one output link.

The General tab allows you to specify an optional description of the output link. The Columns tab
specifies the column definitions of the data. The Advanced tab allows you to change the default buffering
settings for the output link.

See ″Stage Editors,″ for a general description of the tabs.

Chapter 43. Make Vector stage 479

480 Parallel Job Developer Guide
Chapter 44. Split Vector Stage
The Split Vector stage is a restructure stage. It can have a single input link and a single output link.

The Split Vector stage promotes the elements of a fixed-length vector to a set of similarly named top-level
columns. The stage creates columns of the format name0 to namen, where name is the original vector’s
name and 0 and n are the first and last elements of the vector.

input data Column 1 Col0 Col1 Col2 Col3 Col4

Column 1 Col0

Column 2 Col1

output data
Column 3 Col2

Column 4 Col3

Column 5 Col4

The Make Vector stage performs the inverse operation (see Chapter 43, “Make Vector stage,” on page
473).

The stage editor has three pages:

v Stage Page. This is always present and is used to specify general information about the stage.
v Input Page. This is where you specify the details about the single input set from which you are
selecting records.
v Output Page. This is where you specify details about the processed data being output from the stage.

Examples
This section gives examples of input and output data from a Split Vector stage to give you a better idea
of how the stage works.

© Copyright IBM Corp. 2006 481

Example 1
In this example the input data comprises a single column carrying a vector. The example assumes that
the job is running sequentially. The input data set has a single column called ’col’..

The following are some rows from the input data set:

col
Vector index 0 1 2 3 4
row 3 6 2 9 9
row 3 2 7 2 4
row 7 8 8 5 3
row 4 8 7 1 6
row 1 6 2 5 1
row 0 1 6 7 8
row 9 9 6 4 2
row 0 8 4 4 3
row 1 7 2 5 3
row 7 9 4 7 8

The stage splits the columns it extracts from the vector into separate columns called column_nameN. You
do not have to explicitly define the output column names, WebSphere DataStage will do this for you as
the job runs, but you may wish to do so to make the job more understandable.

Column name SQL type

col0 TinyInt
col1 TinyInt
col2 TinyInt
col3 TinyInt
col4 TinyInt

The Vector Column property in the Properties tab is set to ’col’.

The output data set will be:

col0 col1 col2 col3 col4

row 3 6 2 9 9
row 3 2 7 2 4
row 7 8 8 5 3
row 4 8 7 1 6
row 1 6 2 5 1
row 0 1 6 7 8
row 9 9 6 4 2
row 0 8 4 4 3
row 1 7 2 5 3

482 Parallel Job Developer Guide

 col0 col1 col2 col3 col4
row 7 9 4 7 8

Example 2
In this example, there are additional columns as well as the ones containing the vector. The example
assumes that the job is running sequentially. The column definitions for the input data set are as follows,
note the additional columns called name and code:

Column name SQL type

name Char
code Char
col Char

The following are some rows from the input data set:

col
Vector index 0 1 2 3 4
row Will D070 3 6 2 9 9
row Robin GA36 3 2 7 2 4
row Beth B777 7 8 8 5 3
row Heathcliff A100 4 8 7 1 6
row Chaz CH01 1 6 2 5 1
row Kayser CH02 0 1 6 7 8
row Jayne M122 9 9 6 4 2
row Ann F234 0 8 4 4 3
row Kath HE45 1 7 2 5 3
row Rupert BC11 7 9 4 7 8

The stage splits the columns it extracts from the vector into separate columns called column_nameN. You
do not have to explicitly define the output column names, WebSphere DataStage will do this for you as
the job runs, but you may wish to do so to make the job more understandable.

Column name SQL type

name Char
code Char
col0 TinyInt
col1 TinyInt
col2 TinyInt
col3 TinyInt
col4 TinyInt

The Vector Column property in the Properties tab is set to ’col’.

Chapter 44. Split Vector Stage 483

The output data set will be:

Name Code col0 col1 col2 col3 col4

row Will D070 3 6 2 9 9
row Robin GA36 3 2 7 2 4
row Beth B777 7 8 8 5 3
row Heathcliff A100 4 8 7 1 6
row Chaz CH01 1 6 2 5 1
row Kayser CH02 0 1 6 7 8
row Jayne M122 9 9 6 4 2
row Ann F234 0 8 4 4 3
row Kath HE45 1 7 2 5 3
row Rupert BC11 7 9 4 7 8

Must do’s
WebSphere DataStage has many defaults which means that it can be very easy to include Split Vector
stages in a job. This section specifies the minimum steps to take to get a Split Vector stage functioning.
WebSphere DataStage provides a versatile user interface, and there are many shortcuts to achieving a
particular end, this section describes the basic method, you will learn where the shortcuts are when you
get familiar with the product.

To use a Split Vector stage:

v In the Stage Page Properties Tab:
– Specify the name of the input column carrying the vector to be split.

Stage page
The General tab allows you to specify an optional description of the stage. The Properties tab lets you
specify what the stage does. The Advanced tab allows you to specify how the stage executes.

Properties tab
The Split Vector stage has one property:

Category/
Property Values Default Mandatory? Repeats? Dependent of
Options/Vector Name N/A Y N N/A
Column

Options category
Vector column

Specifies the name of the vector whose elements you want to promote to a set of similarly named
top-level columns.

Advanced tab
This tab allows you to specify the following:

484 Parallel Job Developer Guide

v Execution Mode. The stage can execute in parallel mode or sequential mode. In parallel mode the
input data is processed by the available nodes as specified in the Configuration file, and by any node
constraints specified on the Advanced tab. In Sequential mode the entire data set is processed by the
conductor node.
v Combinability mode. This is Auto by default, which allows WebSphere DataStage to combine the
operators that underlie parallel stages so that they run in the same process if it is sensible for this type
of stage.
v Preserve partitioning. This is Propagate by default. It adopts Set or Clear from the previous stage. You
can explicitly select Set or Clear. Select Set to request that next stage in the job should attempt to
maintain the partitioning.
v Node pool and resource constraints. Select this option to constrain parallel execution to the node pool
or pools and/or resource pool or pools specified in the grid. The grid allows you to make choices from
drop down lists populated from the Configuration file.
v Node map constraint. Select this option to constrain parallel execution to the nodes in a defined node
map. You can define a node map by typing node numbers into the text box or by clicking the browse
button to open the Available Nodes dialog box and selecting nodes from there. You are effectively
defining a new node pool for this stage (in addition to any node pools defined in the Configuration
file).

Input page
The Input page allows you to specify details about the incoming data sets. There can be only one input to
the Split Vector stage.

The General tab allows you to specify an optional description of the input link. The Partitioning tab
allows you to specify how incoming data is partitioned before being converted. The Columns tab
specifies the column definitions of incoming data. The Advanced tab allows you to change the default
buffering settings for the input link.

Details about Split Vector stage partitioning are given in the following section. See ″Stage Editors,″ for a
general description of the other tabs.

Partitioning tab
The Partitioning tab allows you to specify details about how the incoming data is partitioned or collected
before it is converted. It also allows you to specify that the data should be sorted before being operated
on.

By default the stage partitions in Auto mode. This attempts to work out the best partitioning method
depending on execution modes of current and preceding stages and how many nodes are specified in the
Configuration file.

If the Split Vector stage is operating in sequential mode, it will first collect the data using the default
Auto collection method.

The Partitioning tab allows you to override this default behavior. The exact operation of this tab depends
on:
v Whether the Split Vector stage is set to execute in parallel or sequential mode.
v Whether the preceding stage in the job is set to execute in parallel or sequential mode.

If the Split Vector stage is set to execute in parallel, then you can set a partitioning method by selecting
from the Partition type drop-down list. This will override any current partitioning.

Chapter 44. Split Vector Stage 485

If the Split Vector stage is set to execute in sequential mode, but the preceding stage is executing in
parallel, then you can set a collection method from the Collector type drop-down list. This will override
the default collection method.

The following partitioning methods are available:

v (Auto). WebSphere DataStage attempts to work out the best partitioning method depending on
execution modes of current and preceding stages and how many nodes are specified in the
Configuration file. This is the default partitioning method for the Split Vector stage.
v Entire. Each file written to receives the entire data set.
v Hash. The records are hashed into partitions based on the value of a key column or columns selected
from the Available list.
v Modulus. The records are partitioned using a modulus function on the key column selected from the
Available list. This is commonly used to partition on tag fields.
v Random. The records are partitioned randomly, based on the output of a random number generator.
v Round Robin. The records are partitioned on a round robin basis as they enter the stage.
v Same. Preserves the partitioning already in place.
v DB2. Replicates the DB2 partitioning method of a specific DB2 table. Requires extra properties to be
set. Access these properties by clicking the properties button.
v Range. Divides a data set into approximately equal size partitions based on one or more partitioning
keys. Range partitioning is often a preprocessing step to performing a total sort on a data set. Requires
extra properties to be set. Access these properties by clicking the properties button.

The following Collection methods are available:

v (Auto). This is the default collection method for Split Vector stages. Normally, when you are using
Auto mode, WebSphere DataStage will eagerly read any row from any input partition as it becomes
available.
v Ordered. Reads all records from the first partition, then all records from the second partition, and so
on.
v Round Robin. Reads a record from the first input partition, then from the second partition, and so on.
After reaching the last partition, the operator starts over.
v Sort Merge. Reads records in an order based on one or more columns of the record. This requires you
to select a collecting key column from the Available list.

The Partitioning tab also allows you to specify that data arriving on the input link should be sorted
before being converted. The sort is always carried out within data partitions. If the stage is partitioning
incoming data the sort occurs after the partitioning. If the stage is collecting data, the sort occurs before
the collection. The availability of sorting depends on the partitioning or collecting method chosen (it is
not available with the default Auto methods).

Select the check boxes as follows:

v Perform Sort. Select this to specify that data coming in on the link should be sorted. Select the column
or columns to sort on from the Available list.
v Stable. Select this if you want to preserve previously sorted data sets. This is the default.
v Unique. Select this to specify that, if multiple records have identical sorting key values, only one
record is retained. If stable sort is also set, the first record is retained.

If NLS is enabled an additional button opens a dialog box allowing you to select a locale specifying the
collate convention for the sort.

You can also specify sort direction, case sensitivity, whether sorted as ASCII or EBCDIC, and whether null
columns will appear first or last for each column. Where you are using a keyed partitioning method, you

486 Parallel Job Developer Guide

can also specify whether the column is used as a key for sorting, for partitioning, or for both. Select the
column in the Selected list and right-click to invoke the shortcut menu.

Output page
The Output page allows you to specify details about data output from the Split Vector stage. The Split
Vector stage can have only one output link.

The General tab allows you to specify an optional description of the output link. The Columns tab
specifies the column definitions of the data. The Advanced tab allows you to change the default buffering
settings for the output link.

See ″Stage Editors,″ for a general description of the tabs.

Chapter 44. Split Vector Stage 487

488 Parallel Job Developer Guide
Chapter 45. Head stage
The Head Stage is a Development/Debug stage. It can have a single input link and a single output link.
It is one of a number of stages that WebSphere DataStage provides to help you sample data, see also:
v Tail stage, Chapter 46, “Tail stage,” on page 497.
v Sample stage, Chapter 47, “Sample stage,” on page 503.
v Peek stage, Chapter 48, “Peek stage,” on page 513.

The Head Stage selects the first N rows from each partition of an input data set and copies the selected
rows to an output data set. You determine which rows are copied by setting properties which allow you
to specify:
v The number of rows to copy
v The partition from which the rows are copied
v The location of the rows to copy
v The number of rows to skip before the copying operation begins

This stage is helpful in testing and debugging applications with large data sets. For example, the Partition
property lets you see data from a single partition to determine if the data is being partitioned as you
want it to be. The Skip property lets you access a certain portion of a data set.

The stage editor has three pages:

v Stage Page. This is always present and is used to specify general information about the stage.
v Input Page. This is where you specify the details about the single input set from which you are
selecting records.
v Output Page. This is where you specify details about the processed data being output from the stage.

Examples

Head stage default behavior

The input data set comprises data from the Global customer billing information, which has previously
been hash-partititioned into four partitions. We accept the default setting to sample ten rows from the
start of each partition.

After the job is run we get a data set comprising four partitions each containing ten rows. Here is a
sample of partition 0 as input to the Head stage, and partition 0 in its entirety as output by the stage:
"GC20442"," A VALIDER","Bp 18","9/30/1988 "
"GC26211","# 7112 GREENWAY PHOENIX W & S ","16012 N 32ND ST","3/2/1994 "
"GC25543","# 7114 PHOENIZ AZ W & S DC ONL","3622 S 30TH ST","1/7/1994 "
"GC20665","*","Avenue Charles Bedaux ZI du Me","6/6/1989 "

© Copyright IBM Corp. 2006 489

"GC21586","*","HELLABRUNNERSTR. 1 ","2/21/1990 "
"GC22708","*","6/8 HIGH STREET ","8/6/1991 "
"GC22728","*","Industrial Est. ","8/13/1991 "
"GC23880","*","14021 HARGRAVE ROAD","11/11/1992"
"GC23823","*","817 S BEELINE HWY","10/28/1992"
"GC21052","* Atlantik Elektronik","SCHILLENBERGWEG 10 ","8/5/1989 "
"GC22163"," CASH ONLY"," ","10/23/1990"
"GC22468"," CASH ONLY","DO NOT MAIL ","3/28/1991 "
"GC21201"," NICHT BENUTZEN"," ","8/5/1989 "
"GC21667"," NICHT BENUTZEN","HENKESTR. 66-72 ","4/19/1990 "
"GC25731","(1500) ALVIN KITCHEN RENOVATIO","1500 HEIGHTS RD","2/16/1994 "
"GC29303","00012 LOT 38 SUPERSTITION","4249 S PONY RIDER TRL","2/12/1996 "
"GC29321","00013-LOT 41-SUPERSTITION VS","4285 S PONY RIDER TRL","2/16/1996 "
"GC28923","00021-LOT 18 SUPESTITION VIS","4214 S STRONG BOX RD","11/15/1995"
"GC29438","00024-LOT 94-FAIRWAY FOOTHILL","16811 S CENTRAL AVE","4/12/1996 "
"GC27930","00028-LOT 58-REPUBLIC HOMES","5849 E NORA ST","6/20/1995 "
"GC20700"," NE PAS UTILISER","11 Rue De Cambrai","7/7/1989 "
"GC20730"," NE PAS UTILISER","1 Rue De Germont","8/3/1989 "
"GC25503","# 7113 MESA AZ W & S DC","132 E BASELINE RD","12/14/1993"
"GC25673","# 7117 TOLLESON AZ W & S DC","8145 WEST HARRISON ST","2/14/1994 "
"GC27133","#0923 SALISBURY PLUMBING HSI","2211 SOUTH MAIN STREET","10/5/1994 "
"GC29857","#0949 ROTO ROOTER MANASSAS HSI","10404 MORIAS CT","9/3/1996 "
"GC25872","(802) ALVIN KITCHEN RENOVATION","802 S JOHNSON ST","2/23/1994 "
"GC26877","***CASH SALES***","","8/22/1994 "
"GC20641","**Alcatel ","50 Avenue Du Président Wilson","5/15/1989 "
"GC21053","**BECHSTEIN WILLI GMBH","Steinkirchring 16 ","8/5/1989 "
"GC22423"," DO NOT USE","Birmingham Road ","3/28/1991 "
"GC22531"," DO NOT USE","DO NOT MAIL ","5/10/1991 "
"GC22845"," DO NOT USE"," ","10/11/1991"
"GC23084"," DO NOT USE","","4/6/1992 "
"GC23106"," DO NOT USE","21100 LASSEN STREET","4/17/1992 "
"GC23483"," DO NOT USE","PO BOX 402473","9/25/1992 "
"GC23941"," DO NOT USE","DO NOT MAIL","11/19/1992"
"GC25597","# 7116 TUCSON AZ W & S DC","4571 S ALVERNON WAY","1/24/1994 "
"GC26143","# 7440 GlobalCo SUPPLY INC","PO BOX 40","3/1/1994 "
"GC26128","# 7763 GlobalCo SUPPLY CO","6750 WEST LOOP SOUTH SUITE 900","3/1/1994 "
"GC20442"," A VALIDER","Bp 18","9/30/1988 "
"GC26211","# 7112 GREENWAY PHOENIX W & S ","16012 N 32ND ST","3/2/1994 "
"GC25543","# 7114 PHOENIZ AZ W & S DC ONL","3622 S 30TH ST","1/7/1994 "
"GC20665","*","Avenue Charles Bedaux ZI du Me","6/6/1989 "
"GC21586","*","HELLABRUNNERSTR. 1 ","2/21/1990 "
"GC22708","*","6/8 HIGH STREET ","8/6/1991 "
"GC22728","*","Industrial Est. ","8/13/1991 "
"GC23880","*","14021 HARGRAVE ROAD","11/11/1992"
"GC23823","*","817 S BEELINE HWY","10/28/1992"
"GC21052","* Atlantik Elektronik","SCHILLENBERGWEG 10 ","8/5/1989 "

Skipping Data
In this example we are using the same data, but this time we are only interested in partition 0, and are
skipping the first 100 rows before we take our ten rows. The Head stage properties are set as follows:

490 Parallel Job Developer Guide

Here is the data set output by the stage:
"GC27057","HEARTLAND","47TH NE NEAR CEMETERY RD","9/30/1994 "
"GC26441","HEARTLAND HOMES","849 SOUTH MAIL","4/6/1994 "
"GC13820","HECTOR","","3/12/1979 "
"GC21467","HEIMAG GMBH "," ","11/16/1989"
"GC21442","HEKUS "," ","10/31/1989"
"GC25904","HELI-ARC FABRICATION & WEL","1825 S WW WHITE RD","2/23/1994 "
"GC14233","HENDRICKS LANDSCAPE CONTRACTOR","1940 E PRESIDIO","12/31/1979"
"GC10055","HENKELS & MCCOY INC","985 JOLLY R","11/18/1983"
"GC11144","HERITAGE POINT PARCEL C","83RD AVE & LOWER BUCKEYE RD","8/31/1983 "
"GC23286","HERITAGE SQUARE SNOHOMISH JOB","1101 2ND STREET","7/21/1992 "
"GC10151","HERNANDEZ & MEDINA","PO BOX 90367","9/1/1983 "

Must do’s
WebSphere DataStage has many defaults which means that it can be very easy to include Head stages in
a job. This section specifies the minimum steps to take to get a Head stage functioning. WebSphere
DataStage provides a versatile user interface, and there are many shortcuts to achieving a particular end,
this section describes the basic method, you will learn where the shortcuts are when you get familiar
with the product.

To use a Head stage:

v In the Stage page Properties Tab, under the Rows category:
– Specify the number of rows per partition that you want to copy from the source data set to the
target data set. This defaults to ten.
You can also:
– Specify that the stage should skip the first N rows per partition.
– Specify that the stage will output all rows in a partition after the skip.
– Specify that the stage should output every Nth row.
Under the Partitions category:
– Specify that the stage will only output rows from the selected partitions.

Chapter 45. Head stage 491

v In the Output Page Mapping Tab, specify how the headed data maps onto your output columns.

Stage page
The General tab allows you to specify an optional description of the stage. The Properties tab lets you
specify what the stage does. The Advanced tab allows you to specify how the stage executes.

Properties tab
The Properties tab allows you to specify properties which determine what the stage actually does. Some
of the properties are mandatory, although many have default settings. Properties without default settings
appear in the warning color (red by default) and turn black when you supply a value for them.

The following table gives a quick reference list of the properties and their attributes. A more detailed
description of each property follows.

Category/
Property Values Default Mandatory? Repeats? Dependent of
Rows/All Rows True/False False N N N/A
Rows/Number of Count 10 N N N/A
Rows (per
Partition)
Rows/Period (per Number N/A N N N/A
Partition)
Rows/Skip (per Number N/A N N N/A
Partition)
Partitions/All Partition Number N/A N Y N/A
Partitions
Partitions/ Number N/A Y (if All Partitions Y N/A
Partition Number = False)

Rows category
All rows

Copy all input rows to the output data set. You can skip rows before Head performs its copy operation
by using the Skip property. The Number of Rows property is not needed if All Rows is true.

Number of rows (per partition)

Specify the number of rows to copy from each partition of the input data set to the output data set. The
default value is 10. The Number of Rows property is not needed if All Rows is true.

Period (per partition)

Copy every Pth record in a partition, where P is the period. You can start the copy operation after records
have been skipped by using the Skip property. P must equal or be greater than 1.

Skip (per Partition)

Ignore the first number of rows of each partition of the input data set, where number is the number of
rows to skip. The default skip count is 0.

492 Parallel Job Developer Guide

Partitions category
All partitions

If False, copy records only from the indicated partition, specified by number. By default, the operator
copies rows from all partitions.

Partition number

Specifies particular partitions to perform the Head operation on. You can specify the Partition Number
property multiple times to specify multiple partition numbers.

Advanced tab
This tab allows you to specify the following:
v Execution Mode. The stage can execute in parallel mode or sequential mode. In parallel mode the
input data is processed by the available nodes as specified in the Configuration file, and by any node
constraints specified on the Advanced tab. In Sequential mode the entire data set is processed by the
conductor node.
v Combinability mode. This is Auto by default, which allows WebSphere DataStage to combine the
operators that underlie parallel stages so that they run in the same process if it is sensible for this type
of stage.
v Preserve partitioning. This is Propagate by default. It adopts Set or Clear from the previous stage. You
can explicitly select Set or Clear. Select Set to request that next stage in the job should attempt to
maintain the partitioning.
v Node pool and resource constraints. Select this option to constrain parallel execution to the node pool
or pools and/or resource pool or pools specified in the grid. The grid allows you to make choices from
drop down lists populated from the Configuration file.
v Node map constraint. Select this option to constrain parallel execution to the nodes in a defined node
map. You can define a node map by typing node numbers into the text box or by clicking the browse
button to open the Available Nodes dialog box and selecting nodes from there. You are effectively
defining a new node pool for this stage (in addition to any node pools defined in the Configuration
file).

Input page
The Input page allows you to specify details about the incoming data sets. The Head stage expects one
input.

The General tab allows you to specify an optional description of the input link. The Partitioning tab
allows you to specify how incoming data is partitioned before being headed. The Columns tab specifies
the column definitions of incoming data. The Advanced tab allows you to change the default buffering
settings for the input link.

Details about Head stage partitioning are given in the following section. See ″Stage Editors,″ for a general
description of the other tabs.

Partitioning tab
The Partitioning tab allows you to specify details about how the incoming data is partitioned or collected
before it is headed. It also allows you to specify that the data should be sorted before being operated on.

By default the stage partitions in Auto mode. This attempts to work out the best partitioning method
depending on execution modes of current and preceding stages, and how many nodes are specified in the
Configuration file.

Chapter 45. Head stage 493

If the Head stage is operating in sequential mode, it will first collect the data using the default Auto
collection method.

The Partitioning tab allows you to override this default behavior. The exact operation of this tab depends
on:
v Whether the Head stage is set to execute in parallel or sequential mode.
v Whether the preceding stage in the job is set to execute in parallel or sequential mode.

If the Head stage is set to execute in parallel, then you can set a partitioning method by selecting from
the Partition type drop-down list. This will override any current partitioning.

If the Head stage is set to execute in sequential mode, but the preceding stage is executing in parallel,
then you can set a collection method from the Collector type drop-down list. This will override the
default collection method.

The following partitioning methods are available:

v (Auto). WebSphere DataStage attempts to work out the best partitioning method depending on
execution modes of current and preceding stages, and how many nodes are specified in the
Configuration file. This is the default partitioning method for the Head stage.
v Entire. Each file written to receives the entire data set.
v Hash. The records are hashed into partitions based on the value of a key column or columns selected
from the Available list.
v Modulus. The records are partitioned using a modulus function on the key column selected from the
Available list. This is commonly used to partition on tag fields.
v Random. The records are partitioned randomly, based on the output of a random number generator.
v Round Robin. The records are partitioned on a round robin basis as they enter the stage.
v Same. Preserves the partitioning already in place.
v DB2. Replicates the DB2 partitioning method of a specific DB2 table. Requires extra properties to be
set. Access these properties by clicking the properties button.
v Range. Divides a data set into approximately equal size partitions based on one or more partitioning
keys. Range partitioning is often a preprocessing step to performing a total sort on a data set. Requires
extra properties to be set. Access these properties by clicking the properties button.

The following Collection methods are available:

v (Auto). This is the default collection method for Head stages. Normally, when you are using Auto
mode, WebSphere DataStage will eagerly read any row from any input partition as it becomes
available.
v Ordered. Reads all records from the first partition, then all records from the second partition, and so
on.
v Round Robin. Reads a record from the first input partition, then from the second partition, and so on.
After reaching the last partition, the operator starts over.
v Sort Merge. Reads records in an order based on one or more columns of the record. This requires you
to select a collecting key column from the Available list.

The Partitioning tab also allows you to specify that data arriving on the input link should be sorted
before being headed. The sort is always carried out within data partitions. If the stage is partitioning
incoming data the sort occurs after the partitioning. If the stage is collecting data, the sort occurs before
the collection. The availability of sorting depends on the partitioning or collecting method chosen (it is
not available for the default auto methods).

Select the check boxes as follows:

494 Parallel Job Developer Guide

v Perform Sort. Select this to specify that data coming in on the link should be sorted. Select the column
or columns to sort on from the Available list.
v Stable. Select this if you want to preserve previously sorted data sets. This is the default.
v Unique. Select this to specify that, if multiple records have identical sorting key values, only one
record is retained. If stable sort is also set, the first record is retained.

If NLS is enabled an additional button opens a dialog box allowing you to select a locale specifying the
collate convention for the sort.

You can also specify sort direction, case sensitivity, whether sorted as ASCII or EBCDIC, and whether null
columns will appear first or last for each column. Where you are using a keyed partitioning method, you
can also specify whether the column is used as a key for sorting, for partitioning, or for both. Select the
column in the Selected list and right-click to invoke the shortcut menu.

Output page
The Output page allows you to specify details about data output from the Head stage. The Head stage
can have only one output link.

The General tab allows you to specify an optional description of the output link. The Columns tab
specifies the column definitions of the data. The Mapping tab allows you to specify the relationship
between the columns being input to the Head stage and the Output columns. The Advanced tab allows
you to change the default buffering settings for the output link.

Details about Head stage mapping is given in the following section. See ″Stage Editors,″ for a general
description of the other tabs.

Mapping tab
For the Head stage the Mapping tab allows you to specify how the output columns are derived, i.e., what
input columns map onto them or how they are generated.

The left pane shows the input columns and/or the generated columns. These are read only and cannot be
modified on this tab.

The right pane shows the output columns for each link. This has a Derivations field where you can
specify how the column is derived. You can fill it in by dragging input columns over, or by using the
Auto-match facility.

Chapter 45. Head stage 495

496 Parallel Job Developer Guide
Chapter 46. Tail stage
The Tail Stage is a Development/Debug stage. It can have a single input link and a single output link. It
is one of a number of stages that WebSphere DataStage provides to help you sample data, see also:
v Head stage, Chapter 45, “Head stage,” on page 489.
v Sample stage, Chapter 47, “Sample stage,” on page 503.
v Peek stage, Chapter 48, “Peek stage,” on page 513.

The Tail Stage selects the last N records from each partition of an input data set and copies the selected
records to an output data set. You determine which records are copied by setting properties which allow
you to specify:
v The number of records to copy
v The partition from which the records are copied

This stage is helpful in testing and debugging applications with large data sets. For example, the Partition
property lets you see data from a single partition to determine if the data is being partitioned as you
want it to be. The Skip property lets you access a certain portion of a data set.

The stage editor has three pages:

v Stage Page. This is always present and is used to specify general information about the stage.
v Input Page. This is where you specify the details about the single input set from which you are
selecting records.
v Output Page. This is where you specify details about the processed data being output from the stage.

Examples
We accept the default setting to sample ten rows from the end of each partition.The input data set
comprises data from the Global customer billing information, which has previously been
hash-partititioned into four partitions. We accept the default setting to sample ten rows from the end of
each partition.

After the job is run we get a data set comprising four partitions each containing ten rows. Here is a
sample of partition 0 as input to the Tail stage, and partition 0 in its entirety as output by the stage:
"GC22593","ifm Electronic Ltd ","EASTLEIGH ","6/5/1991 "
"GC22998","ifm Electronic Ltd ","6/8 HIGH STREET ","2/7/1992 "
"GC20828","protectic ","31 Place Des Corolles","8/5/1989 "
"GC20910","protectic ","207 Cours Du Médoc","8/5/1989 "
"GC16187","southwest underground","596 w tarpon blvd","3/8/1985 "
"GC13583","ZURN INDUSTRIES","3033 NW 25TH BLVD","7/31/1978 "
"GC13546","ZURN INDUSTRIES INC","3033 NORTHWEST 25TH AVENUE","7/11/1978 "
"GC21204","Zilog Europe INC. "," ","8/5/1989 "

© Copyright IBM Corp. 2006 497

"GC22026","ifm Electronic Ltd ","EASTLEIGH ","7/12/1990 "
"GC22103","ifm Electronic Ltd ","EASTLEIGH ","9/6/1990 "
"GC21235","volkswagen ag ","AM BRINK 10 ","8/16/1989 "
"GC10172","XTRA LITE LIGHTING INC","207-21ST AVENUE SOUTH","8/31/1983 "
"GC23534","YAVAPAI CNTY COTTONWOOD ANNEX ","10 SOUTH ST","9/25/1992 "
"GC16305","YOE HIGH SCHOOL ADD & RENOVATI","400 E 10TH ST","9/9/1985 "
"GC16261","YOUNGVILLE-WAKE FOREST MHP","","6/4/1985 "
"GC27114","ZECCHETTI USA","685 MAIN ST SUITE A","10/3/1994 "
"GC15610","ZEP MANUFACTURING COMPANY","9203 KING PALM DR STE D","9/23/1983 "
"GC28226","ZEUS INDUSTRIAL PRODUCTS INC","PO BOX 298","8/9/1995 "
"GC26383","ZOT’S WATTS","","3/30/1994 "
"GC24291","ZURICH CORP SUPERANNUATIO","5650 SLOUGH STRABE GEBÄU 47","2/22/1993 "
"GC22551","d ","AIRPORT WAY LUTON ","5/22/1991 "
"GC22919","d ","Horsforth ","12/2/1991 "
"GC15583","george davis","orlando plumbing employee","10/3/1983 "
"GC20800","masterline ","2 Rue Auguste Comte","8/3/1989 "
"GC20865","masterline ","41-45 Boulevard Romain Rolland","8/5/1989 "
"GC20935","sinfor ","24 Rue Henri Barbusse","8/5/1989 "
"GC20996","sinfor ","60 Rue De Prony","8/5/1989 "
"GC20819","sysicom ","523 Terrasse De L Agora","8/5/1989 "
"GC20979","sysicom ","26 Quai Claude Bernard","8/5/1989 "
"GC22184","d ","351-353 Lea Bridge Road ","11/9/1990 "
"GC20994","soprate ","Keltenring 12","8/5/1989 "
"GC20199","sydelis ","Tour Franklin","2/11/1988 "
"GC20284","sydelis ","6 Boulevard De L’Hérault","4/19/1988 "
"GC20179","dataverse ","38-40 Rue Du Général Leclerc","1/29/1988 "
"GC20566","dataverse ","4 Avenue Du 8 Mai 1945","2/16/1989 "
"GC20821","dataverse ","38-40 Rue Du Général Leclerc","8/5/1989 "
"GC20841","groupe PPR : Pinault Printemps","17 Rue Des Martyrs","8/5/1989 "
"GC20791","groupe PPR : Pinault Printemps","92 Avenue Du General De Gaulle","8/3/1989 "
"GC20162","soprate ","189-193 Boulevard Malesherbes","1/22/1988 "
"GC20103","soprate ","Keltenring 12","11/22/1987"
"GC20994","soprate ","Keltenring 12","8/5/1989 "
"GC20199","sydelis ","Tour Franklin","2/11/1988 "
"GC20284","sydelis ","6 Boulevard De L’Hérault","4/19/1988 "
"GC20179","dataverse ","38-40 Rue Du Général Leclerc","1/29/1988 "
"GC20566","dataverse ","4 Avenue Du 8 Mai 1945","2/16/1989 "
"GC20821","dataverse ","38-40 Rue Du Général Leclerc","8/5/1989 "
"GC20841","groupe PPR : Pinault Printemps","17 Rue Des Martyrs","8/5/1989 "
"GC20791","groupe PPR : Pinault Printemps","92 Avenue Du General De Gaulle","8/3/1989 "
"GC20162","soprate ","189-193 Boulevard Malesherbes","1/22/1988 "
"GC20103","soprate ","Keltenring 12","11/22/1987"

Must do’s
WebSphere DataStage has many defaults which means that it can be very easy to include Tail stages in a
job. This section specifies the minimum steps to take to get a Tail stage functioning. WebSphere DataStage
provides a versatile user interface, and there are many shortcuts to achieving a particular end, this section
describes the basic method, you will learn where the shortcuts are when you get familiar with the
product.

To use a Tail stage:

v In the Stage page Properties Tab, under the Rows category:
– Specify the number of rows per partition that you want to copy from the source data set to the
target data set. This defaults to ten.
Under the Partitions category:
– Specify that the stage will only output rows from the selected partitions.
v In the Output Page Mapping Tab, specify how the tailed data maps onto your output columns.

498 Parallel Job Developer Guide

Stage page
The General tab allows you to specify an optional description of the stage. The Properties tab lets you
specify what the stage does. The Advanced tab allows you to specify how the stage executes.

Properties tab
The Properties tab allows you to specify properties which determine what the stage actually does. Some
of the properties are mandatory, although many have default settings. Properties without default settings
appear in the warning color (red by default) and turn black when you supply a value for them.

The following table gives a quick reference list of the properties and their attributes. A more detailed
description of each property follows.

Category/
Property Values Default Mandatory? Repeats? Dependent of
Rows/Number of Count 10 N N Key
Rows (per
Partition)
Partitions/All Partition Number N/A N Y N/A
Partitions
Partitions/ Number N/A Y (if All Partitions Y N/A
Partition Number = False)

Rows category
Number of rows (per partition)

Specify the number of rows to copy from each partition of the input data set to the output data set. The
default value is 10.

Partitions category
All partitions

If False, copy records only from the indicated partition, specified by number. By default, the operator
copies records from all partitions.

Partition number

Specifies particular partitions to perform the Tail operation on. You can specify the Partition Number
property multiple times to specify multiple partition numbers.

Advanced tab
This tab allows you to specify the following:
v Execution Mode. The stage can execute in parallel mode or sequential mode. In parallel mode the
input data is processed by the available nodes as specified in the Configuration file, and by any node
constraints specified on the Advanced tab. In Sequential mode the entire data set is processed by the
conductor node.
v Combinability mode. This is Auto by default, which allows WebSphere DataStage to combine the
operators that underlie parallel stages so that they run in the same process if it is sensible for this type
of stage.

Chapter 46. Tail stage 499

v Preserve partitioning. This is Propagate by default. It adopts Set or Clear from the previous stage. You
can explicitly select Set or Clear. Select Set to request that next stage in the job should attempt to
maintain the partitioning.
v Node pool and resource constraints. Select this option to constrain parallel execution to the node pool
or pools and/or resource pool or pools specified in the grid. The grid allows you to make choices from
drop down lists populated from the Configuration file.
v Node map constraint. Select this option to constrain parallel execution to the nodes in a defined node
map. You can define a node map by typing node numbers into the text box or by clicking the browse
button to open the Available Nodes dialog box and selecting nodes from there. You are effectively
defining a new node pool for this stage (in addition to any node pools defined in the Configuration
file).

Input page
The Input page allows you to specify details about the incoming data sets. The Tail stage expects one
input.

The General tab allows you to specify an optional description of the input link. The Partitioning tab
allows you to specify how incoming data is partitioned before being tailed. The Columns tab specifies the
column definitions of incoming data. The Advanced tab allows you to change the default buffering
settings for the input link.

Details about Tail stage partitioning are given in the following section. See ″Stage Editors,″ for a general
description of the other tabs.

Partitioning tab
The Partitioning tab allows you to specify details about how the incoming data is partitioned or collected
before it is tailed. It also allows you to specify that the data should be sorted before being operated on.

By default the stage partitions in Auto mode. This attempts to work out the best partitioning method
depending on execution modes of current and preceding stages and how many nodes are specified in the
Configuration file. If the Preserve Partitioning option has been set on the previous stage in the job, this
stage will warn if it cannot preserve the partitioning of the incoming data.

If the Tail stage is operating in sequential mode, it will first collect the data using the default Auto
collection method.

The Partitioning tab allows you to override this default behavior. The exact operation of this tab depends
on:
v Whether the Tail stage is set to execute in parallel or sequential mode.
v Whether the preceding stage in the job is set to execute in parallel or sequential mode.

If the Tail stage is set to execute in parallel, then you can set a partitioning method by selecting from the
Partition type drop-down list. This will override any current partitioning.

If the Tail stage is set to execute in sequential mode, but the preceding stage is executing in parallel, then
you can set a collection method from the Collector type drop-down list. This will override the default
collection method.

The following partitioning methods are available:

v (Auto). WebSphere DataStage attempts to work out the best partitioning method depending on
execution modes of current and preceding stages and how many nodes are specified in the
Configuration file. This is the default partitioning method for the Tail stage.

500 Parallel Job Developer Guide

v Entire. Each file written to receives the entire data set.
v Hash. The records are hashed into partitions based on the value of a key column or columns selected
from the Available list.
v Modulus. The records are partitioned using a modulus function on the key column selected from the
Available list. This is commonly used to partition on tag fields.
v Random. The records are partitioned randomly, based on the output of a random number generator.
v Round Robin. The records are partitioned on a round robin basis as they enter the stage.
v Same. Preserves the partitioning already in place.
v DB2. Replicates the DB2 partitioning method of a specific DB2 table. Requires extra properties to be
set. Access these properties by clicking the properties button.
v Range. Divides a data set into approximately equal size partitions based on one or more partitioning
keys. Range partitioning is often a preprocessing step to performing a total sort on a data set. Requires
extra properties to be set. Access these properties by clicking the properties button.

The following Collection methods are available:

v (Auto). This is the default collection method for Tail stages. Normally, when you are using Auto mode,
WebSphere DataStage will eagerly read any row from any input partition as it becomes available.
v Ordered. Reads all records from the first partition, then all records from the second partition, and so
on.
v Round Robin. Reads a record from the first input partition, then from the second partition, and so on.
After reaching the last partition, the operator starts over.
v Sort Merge. Reads records in an order based on one or more columns of the record. This requires you
to select a collecting key column from the Available list.

The Partitioning tab also allows you to specify that data arriving on the input link should be sorted
before being tailed. The sort is always carried out within data partitions. If the stage is partitioning
incoming data the sort occurs after the partitioning. If the stage is collecting data, the sort occurs before
the collection. The availability of sorting depends on the partitioning method chosen.

Select the check boxes as follows:

v Perform Sort. Select this to specify that data coming in on the link should be sorted. Select the column
or columns to sort on from the Available list.
v Stable. Select this if you want to preserve previously sorted data sets. This is the default.
v Unique. Select this to specify that, if multiple records have identical sorting key values, only one
record is retained. If stable sort is also set, the first record is retained.

If NLS is enabled an additional button opens a dialog box allowing you to select a locale specifying the
collate convention for the sort.

You can also specify sort direction, case sensitivity, whether sorted as ASCII or EBCDIC, and whether null
columns will appear first or last for each column. Where you are using a keyed partitioning method, you
can also specify whether the column is used as a key for sorting, for partitioning, or for both. Select the
column in the Selected list and right-click to invoke the shortcut menu.

Output page
The Output page allows you to specify details about data output from the Tail stage. The Tail stage can
have only one output link.

The General tab allows you to specify an optional description of the output link. The Columns tab
specifies the column definitions of the data. The Mapping tab allows you to specify the relationship

Chapter 46. Tail stage 501

between the columns being input to the Tail stage and the Output columns. The Advanced tab allows
you to change the default buffering settings for the output link.

Details about Tail stage mapping is given in the following section. See ″Stage Editors,″ for a general
description of the other tabs.

Mapping tab
For the Tail stage the Mapping tab allows you to specify how the output columns are derived, i.e., what
input columns map onto them or how they are generated.

The left pane shows the input columns and/or the generated columns. These are read only and cannot be
modified on this tab.

The right pane shows the output columns for each link. This has a Derivations field where you can
specify how the column is derived. You can fill it in by dragging input columns over, or by using the
Auto-match facility.

502 Parallel Job Developer Guide

Chapter 47. Sample stage
The Sample stage is a Development/Debug stage. It can have a single input link and any number of
output links when operationg in percent mode, or a single input and single output link when operating
in period mode. It is one of a number of stages that WebSphere DataStage provides to help you sample
data, see also:
v Head stage, Chapter 45, “Head stage,” on page 489.
v Tail stage, Chapter 46, “Tail stage,” on page 497.
v Peek stage, Chapter 48, “Peek stage,” on page 513.

The Sample stage samples an input data set. It operates in two modes. In Percent mode, it extracts rows,
selecting them by means of a random number generator, and writes a given percentage of these to each
output data set. You specify the number of output data sets, the percentage written to each, and a seed
value to start the random number generator. You can reproduce a given distribution by repeating the
same number of outputs, the percentage, and the seed value

In Period mode, it extracts every Nth row from each partition, where N is the period, which you supply.
In this case all rows will be output to a single data set, so the stage used in this mode can only have a

© Copyright IBM Corp. 2006 503

single output link

For both modes you can specify the maximum number of rows that you want to sample from each
partition.

The stage editor has three pages:

v Stage Page. This is always present and is used to specify general information about the stage.
v Input Page. This is where you specify details about the data set being Sampled.
v Output Page. This is where you specify details about the Sampled data being output from the stage.

Examples

Sampling in percent mode

Our input data set comprises billing information about GlobalCo’s customers, which has previously been
hash-partititioned into four partitions. We are going to take three samples, one of 10%, one of 15%, and
one of 20%, and write these to three different files.

In the Stage page Properties tab we specify which percentages are written to which outputs as follows:

504 Parallel Job Developer Guide

We use the Link Ordering tab to specify which outputs relate to which output links:

When we run the job we end up with three data sets of different sizes as shown in the following tables
(you would see this information if you looked at the data sets using the Data Set Manager:

Chapter 47. Sample stage 505

Table 8. 10 Percent Sample
# Node Records Blocks Bytes
0 node1 27 2 34194
1 node2 21 1 26586
2 node3 18 1 22788
3 node4 21 1 26598

Table 9. 15 Percent Sample

# Node Records Blocks Bytes
0 node1 12 1 15192
1 node2 10 1 12660
2 node3 13 1 16458
3 node4 16 1 20256

Table 10. 20Percent Sample

# Node Records Blocks Bytes
0 node1 26 2 32928
1 node2 29 2 36738
2 node3 32 2 40527
3 node4 29 2 36714

Sampling in Period Mode

In this example we are going to extract every twentieth row from each partition, up to a maximum of
forty rows (in paractice our example data set is not large enough to reach this maximum). In period
mode, you are limited to sampling into a single data set.

In the Stage page Properties tab we specify the period sample as follows:

506 Parallel Job Developer Guide

Because there can only be one output from the stage, we do not need to bother with the Link Ordering
tab.

When we run the job it produces a sample from each partion. Here is the data sampled from partition 0:

DocumentID Year Fname Sname Office

WBR 96 folio 34 1627 Guye Beckley none
(court leet attendees) 1687 Thomas Cisill none
WBR 96 folio 34 1627 John Dizell freeman
WBR 96 folio 1-46 1662 Gyles Franklyn councillor
WBR 96 folio 1-46 1662 John Hawkins none
WBR 96 folio 34 1627 Edward Johnson freeman
WBR 96 folio 21 1622 William Neele none
WBR 96 folio 11 1617 Thomas Paynter freeman
WBR 96 folio 1-46 1662 James Ryman freeman
WBR 96 folio 21 1622 Mathew Tomes freeman
WBR 96 folio 21 1622 John Woodroffe none

Chapter 47. Sample stage 507

Must do’s
WebSphere DataStage has many defaults which means that it can be very easy to include Sample stages
in a job. This section specifies the minimum steps to take to get a Sample stage functioning. WebSphere
DataStage provides a versatile user interface, and there are many shortcuts to achieving a particular end,
this section describes the basic method, you will learn where the shortcuts are when you get familiar
with the product.

To use a Sample stage:

v In the Stage page Properties Tab, choose the sample mode. This is Percent by default, but you can also
choose Period.
If you have chosen Percent, Specify the sampling percentage for an output link, and specify the output
link number it will be output on (links are numbered from 0). Repeat these properties to specify the
percentage for each of your output links.
If you have chosen the Period mode, specify the Period. This will sample every Nth row in each
partition.
v If you have chosen Percent mode, in the Stage page Link Ordering Tab, specify which of your actual
output links corresponds to link 0, link 1 etc.
v In the Output Page Mapping Tab, specify how output columns on each link are derived from the
columns of the input data.

Stage page
The General tab allows you to specify an optional description of the stage. The Properties tab lets you
specify what the stage does. The Advanced tab allows you to specify how the stage executes. TheLink
Ordering tab allows you to specify which output links are which.

Properties tab
The Properties tab allows you to specify properties which determine what the stage actually does. Some
of the properties are mandatory, although many have default settings. Properties without default settings
appear in the warning color (red by default) and turn black when you supply a value for them.

The following table gives a quick reference list of the properties and their attributes. A more detailed
description of each property follows.

Category/
Property Values Default Mandatory? Repeats? Dependent of
Options/Sample percent/period percent Y N N/A
Mode
Options/Percent number N/A Y (if Sample Y N/A
Mode = Percent)
Options/Output number N/A Y N Percent
Link Number
Options/Seed number N/A N N N/A
Options/Period number N/A Y (if Sample N N/A
(Per Partition) Mode = Period)
Options/Max number N/A N N N/A
Rows Per
Partition

508 Parallel Job Developer Guide

Options category
Sample mode

Specifies the type of sample operation. You can sample on a percentage of input rows (percent), or you
can sample the Nth row of every partition (period).

Percent

Specifies the sampling percentage for each output data set when use a Sample Mode of Percent. You can
repeat this property to specify different percentages for each output data set. The sum of the percentages
specified for all output data sets cannot exceed 100%. You can specify a job parameter if required.

Percent has a dependent property:

v Output Link Number
This specifies the output link to which the percentage corresponds. You can specify a job parameter if
required.

Seed

This is the number used to initialize the random number generator. You can specify a job parameter if
required. This property is only available if Sample Mode is set to percent.

Period (per partition)

Specifies the period when using a Sample Mode of Period.

Max rows per partition

This specifies the maximum number of rows that will be sampled from each partition.

Advanced tab
This tab allows you to specify the following:
v Execution Mode. The stage can execute in parallel mode or sequential mode. In parallel mode the
input data is processed by the available nodes as specified in the Configuration file, and by any node
constraints specified on the Advanced tab. In Sequential mode the entire data set is processed by the
conductor node.
v Combinability mode. This is Auto by default, which allows WebSphere DataStage to combine the
operators that underlie parallel stages so that they run in the same process if it is sensible for this type
of stage.
v Preserve partitioning. This is Propagate by default. It adopts Set or Clear from the previous stage. You
can explicitly select Set or Clear. Select Set to request the next stage should attempt to maintain the
partitioning.
v Node pool and resource constraints. Select this option to constrain parallel execution to the node pool
or pools and/or resource pool or pools specified in the grid. The grid allows you to make choices from
drop down lists populated from the Configuration file.
v Node map constraint. Select this option to constrain parallel execution to the nodes in a defined node
map. You can define a node map by typing node numbers into the text box or by clicking the browse
button to open the Available Nodes dialog box and selecting nodes from there. You are effectively
defining a new node pool for this stage (in addition to any node pools defined in the Configuration
file).

Chapter 47. Sample stage 509

Link Ordering tab
In Percent mode, this tab allows you to specify the order in which the output links are processed. This is
how they correspond to the Output Link Number properties on the Properties Tab.

By default the output links will be processed in the order they were added. To rearrange them, choose an
output link and click the up arrow button or the down arrow button.

Input page
The Input page allows you to specify details about the data set being sampled. There is only one input
link.

The General tab allows you to specify an optional description of the link. The Partitioning tab allows you
to specify how incoming data on the source data set link is partitioned. The Columns tab specifies the
column definitions of incoming data.

Details about Sample stage partitioning are given in the following section. See ″Stage Editors,″ for a
general description of the other tabs.

Partitioning on input links

The Partitioning tab allows you to specify details about how the incoming data is partitioned or collected
before the sample is performed.

By default the stage uses the auto partitioning method. If the Preserve Partitioning option has been set on
the previous stage in the job, the stage will warn if it cannot preserve the partitioning of the incoming
data.

If the Sample stage is operating in sequential mode, it will first collect the data before writing it to the file
using the default auto collection method.

The Partitioning tab allows you to override this default behavior. The exact operation of this tab depends
on:
v Whether the Sample stage is set to execute in parallel or sequential mode.
v Whether the preceding stage in the job is set to execute in parallel or sequential mode.

If the Sample stage is set to execute in parallel, then you can set a partitioning method by selecting from
the Partition type drop-down list. This will override any current partitioning.

If the Sample stage is set to execute in sequential mode, but the preceding stage is executing in parallel,
then you can set a collection method from the Collector type drop-down list. This will override the
default auto collection method.

The following partitioning methods are available:

v (Auto). WebSphere DataStage attempts to work out the best partitioning method depending on
execution modes of current and preceding stages and how many nodes are specified in the
Configuration file. This is the default method for the Sample stage.
v Entire. Each file written to receives the entire data set.
v Hash. The records are hashed into partitions based on the value of a key column or columns selected
from the Available list.
v Modulus. The records are partitioned using a modulus function on the key column selected from the
Available list. This is commonly used to partition on tag fields.

510 Parallel Job Developer Guide

v Random. The records are partitioned randomly, based on the output of a random number generator.
v Round Robin. The records are partitioned on a round robin basis as they enter the stage.
v Same. Preserves the partitioning already in place.
v DB2. Replicates the DB2 partitioning method of a specific DB2 table. Requires extra properties to be
set. Access these properties by clicking the properties button.
v Range. Divides a data set into approximately equal size partitions based on one or more partitioning
keys. Range partitioning is often a preprocessing step to performing a total sort on a data set. Requires
extra properties to be set. Access these properties by clicking the properties button.

The following Collection methods are available:

v (Auto). This is the default collection method for the Sample stage. Normally, when you are using Auto
mode, WebSphere DataStage will eagerly read any row from any input partition as it becomes
available.
v Ordered. Reads all records from the first partition, then all records from the second partition, and so
on.
v Round Robin. Reads a record from the first input partition, then from the second partition, and so on.
After reaching the last partition, the operator starts over.
v Sort Merge. Reads records in an order based on one or more columns of the record. This requires you
to select a collecting key column from the Available list.

The Partitioning tab also allows you to specify that data arriving on the input link should be sorted
before the sample is performed. The sort is always carried out within data partitions. If the stage is
partitioning incoming data the sort occurs after the partitioning. If the stage is collecting data, the sort
occurs before the collection. The availability of sorting depends on the partitioning or collecting method
chosen (it is not available for the default auto methods).

Select the check boxes as follows:

v Perform Sort. Select this to specify that data coming in on the link should be sorted. Select the column
or columns to sort on from the Available list.
v Stable. Select this if you want to preserve previously sorted data sets. This is the default.
v Unique. Select this to specify that, if multiple records have identical sorting key values, only one
record is retained. If stable sort is also set, the first record is retained.

If NLS is enabled an additional button opens a dialog box allowing you to select a locale specifying the
collate convention for the sort.

You can also specify sort direction, case sensitivity, whether sorted as ASCII or EBCDIC, and whether null
columns will appear first or last for each column. Where you are using a keyed partitioning method, you
can also specify whether the column is used as a key for sorting, for partitioning, or for both. Select the
column in the Selected list and right-click to invoke the shortcut menu.

Output page
The Output page allows you to specify details about data output from the Sample stage. In Percent
mode, the stage can have any number of output links, in Period mode it can only have one output.
Choose the link you want to work on from the Output Link drop down list.

The General tab allows you to specify an optional description of the output link. The Columns tab
specifies the column definitions of outgoing data. The Mapping tab allows you to specify the relationship
between the columns being input to the Sample stage and the output columns. The Advanced tab allows
you to change the default buffering settings for the output links. The Advanced tab allows you to change
the default buffering settings for the input link.

Chapter 47. Sample stage 511

Details about Sample stage mapping is given in the following section. See ″Stage Editors,″ for a general
description of the other tabs.

Mapping tab
For Sample stages the Mapping tab allows you to specify how the output columns are derived, i.e., what
input columns map onto them.

The left pane shows the columns of the sampled data. These are read only and cannot be modified on
this tab. This shows the meta data from the incoming link

The right pane shows the output columns for the output link. This has a Derivations field where you can
specify how the column is derived. You can fill it in by dragging input columns over, or by using the
Auto-match facility.

512 Parallel Job Developer Guide

Chapter 48. Peek stage
The Peek stage is a Development/Debug stage. It can have a single input link and any number of output
links.

The Peek stage lets you print record column values either to the job log or to a separate output link as
the stage copies records from its input data set to one or more output data sets. Like the Head stage
(Chapter 45, “Head stage,” on page 489) and the Tail stage (Chapter 47, “Sample stage,” on page 503), the
Peek stage can be helpful for monitoring the progress of your application or to diagnose a bug in your

application.

The stage editor has three pages:

v Stage Page. This is always present and is used to specify general information about the stage.
v Input Page. This is where you specify the details about the single input set from which you are
selecting records.
v Output Page. This is where you specify details about the processed data being output from the stage.

Must do’s
WebSphere DataStage has many defaults which means that it can be very easy to include Peek stages in a
job. This section specifies the minimum steps to take to get a Peek stage functioning. WebSphere
DataStage provides a versatile user interface, and there are many shortcuts to achieving a particular end,
this section describes the basic method, you will learn where the shortcuts are when you get familiar
with the product.

To use a Peek stage:

v In the Stage page Properties Tab, check that the default settings are suitable for your requirements.
v In the Stage page Link Ordering Tab, if you have chosen to output peeked records to a link rather
than the job log, choose which output link will carry the peeked records.

Stage page
The General tab allows you to specify an optional description of the stage. The Properties tab lets you
specify what the stage does. The Advanced tab allows you to specify how the stage executes.

© Copyright IBM Corp. 2006 513

Properties tab
The Properties tab allows you to specify properties which determine what the stage actually does. Some
of the properties are mandatory, although many have default settings. Properties without default settings
appear in the warning color (red by default) and turn black when you supply a value for them.

The following table gives a quick reference list of the properties and their attributes. A more detailed
description of each property follows.

Category/
Property Values Default Mandatory? Repeats? Dependent of
Rows/All True/False False N N N/A
Records (After
Skip)
Rows/Number of number 10 Y N N/A
Records (Per
Partition)
Rows/Period (per Number N/A N N N/A
Partition)
Rows/Skip (per Number N/A N N N/A
Partition)
Columns/Peek True/False True Y N N/A
All Input
Columns
Columns/Input Input Column N/A Y (if Peek All Y N/A
Column to Peek Input Columns =
False)
Partitions/All True/False True Y N N/A
Partitions
Partitions/ number N/A Y (if All Partitions Y N/A
Partition Number = False)
Options/Peek Job Log/Output Job Log N N N/A
Records Output
Mode
Options/Show True/False True N N N/A
Column Names
Options/ space/nl/tab space N N N/A
Delimiter String

Rows category
All records (after skip)

True to print all records from each partition. Set to False by default.

Number of records (per partition)

Specifies the number of records to print from each partition. The default is 10.

Period (per partition)

Print every Pth record in a partition, where P is the period. You can start the copy operation after records
have been skipped by using the Skip property. P must equal or be greater than 1.

514 Parallel Job Developer Guide

Skip (per partition)

Ignore the first number of rows of each partition of the input data set, where number is the number of
rows to skip. The default skip count is 0.

Columns category
Peek all input columns

True by default and prints all the input columns. Set to False to specify that only selected columns will be
printed and specify these columns using the Input Column to Peek property.

Input column to peek

If you have set Peek All Input Columns to False, use this property to specify a column to be printed.
Repeat the property to specify multiple columns.

Partitions category
All partitions

Set to True by default. Set to False to specify that only certain partitions should have columns printed,
and specify which partitions using the Partition Number property.

Partition number

If you have set All Partitions to False, use this property to specify which partition you want to print
columns from. Repeat the property to specify multiple columns.

Options category
Peek records output mode

Specifies whether the output should go to an output column (the Peek Records column) or to the job log.

Show column names

If True, causes the stage to print the column name, followed by a colon, followed by the column value. If
False, the stage prints only the column value, followed by a space. It is True by default.

Delimiter string

The string to use as a delimiter on columns. Can be space, tab or newline. The default is space.

Advanced tab
This tab allows you to specify the following:
v Execution Mode. The stage can execute in parallel mode or sequential mode. In parallel mode the
input data is processed by the available nodes as specified in the Configuration file, and by any node
constraints specified on the Advanced tab. In Sequential mode the entire data set is processed by the
conductor node.
v Combinability mode. This is Auto by default, which allows WebSphere DataStage to combine the
operators that underlie parallel stages so that they run in the same process if it is sensible for this type
of stage.
v Preserve partitioning. This is Propagate by default. It adopts Set or Clear from the previous stage. You
can explicitly select Set or Clear. Select Set to request that next stage in the job should attempt to
maintain the partitioning.

Chapter 48. Peek stage 515

v Node pool and resource constraints. Select this option to constrain parallel execution to the node pool
or pools and/or resource pool or pools specified in the grid. The grid allows you to make choices from
drop down lists populated from the Configuration file.
v Node map constraint. Select this option to constrain parallel execution to the nodes in a defined node
map. You can define a node map by typing node numbers into the text box or by clicking the browse
button to open the Available Nodes dialog box and selecting nodes from there. You are effectively
defining a new node pool for this stage (in addition to any node pools defined in the Configuration
file).

Link Ordering tab

This tab allows you to specify which output link carries the peek records data set if you have chosen to
output the records to a link rather than the job log.

By default the last link added will represent the peek data set. To rearrange the links, choose an output
link and click the up arrow button or the down arrow button.

Input page
The Input page allows you to specify details about the incoming data sets. The Peek stage expects one
incoming data set.

The General tab allows you to specify an optional description of the input link. The Partitioning tab
allows you to specify how incoming data is partitioned before being peeked. The Columns tab specifies
the column definitions of incoming data. The Advanced tab allows you to change the default buffering
settings for the input link.

Details about Peek stage partitioning are given in the following section. See ″Stage Editors,″ for a general
description of the other tabs.

Partitioning tab
The Partitioning tab allows you to specify details about how the incoming data is partitioned or collected
before it is peeked. It also allows you to specify that the data should be sorted before being operated on.

By default the stage partitions in Auto mode. This attempts to work out the best partitioning method
depending on execution modes of current and preceding stages and how many nodes are specified in the
Configuration file. If the Preserve Partitioning option has been set on the previous stage in the job, this
stage will warn if it cannot preserve the partitioning of the incoming data.

If the Peek stage is operating in sequential mode, it will first collect the data using the default Auto
collection method.

The Partitioning tab allows you to override this default behavior. The exact operation of this tab depends
on:
v Whether the Peek stage is set to execute in parallel or sequential mode.
v Whether the preceding stage in the job is set to execute in parallel or sequential mode.

If the Peek stage is set to execute in parallel, then you can set a partitioning method by selecting from the
Partition type drop-down list. This will override any current partitioning.

If the Peek stage is set to execute in sequential mode, but the preceding stage is executing in parallel,
then you can set a collection method from the Collector type drop-down list. This will override the
default collection method.

516 Parallel Job Developer Guide

The following partitioning methods are available:
v (Auto). WebSphere DataStage attempts to work out the best partitioning method depending on
execution modes of current and preceding stages and how many nodes are specified in the
Configuration file. This is the default method of the Peek stage.
v Entire. Each file written to receives the entire data set.
v Hash. The records are hashed into partitions based on the value of a key column or columns selected
from the Available list.
v Modulus. The records are partitioned using a modulus function on the key column selected from the
Available list. This is commonly used to partition on tag fields.
v Random. The records are partitioned randomly, based on the output of a random number generator.
v Round Robin. The records are partitioned on a round robin basis as they enter the stage.
v Same. Preserves the partitioning already in place.
v DB2. Replicates the DB2 partitioning method of a specific DB2 table. Requires extra properties to be
set. Access these properties by clicking the properties button.
v Range. Divides a data set into approximately equal size partitions based on one or more partitioning
keys. Range partitioning is often a preprocessing step to performing a total sort on a data set. Requires
extra properties to be set. Access these properties by clicking the properties button.

The following Collection methods are available:

v (Auto). WebSphere DataStage attempts to work out the best collection method depending on execution
modes of current and preceding stages, and how many nodes are specified in the Configuration file.
This is the default collection method for Peek stages.
v Ordered. Reads all records from the first partition, then all records from the second partition, and so
on.
v Round Robin. Reads a record from the first input partition, then from the second partition, and so on.
After reaching the last partition, the operator starts over.
v Sort Merge. Reads records in an order based on one or more columns of the record. This requires you
to select a collecting key column from the Available list.

The Partitioning tab also allows you to specify that data arriving on the input link should be sorted
before being peeked. The sort is always carried out within data partitions. If the stage is partitioning
incoming data the sort occurs after the partitioning. If the stage is collecting data, the sort occurs before
the collection. The availability of sorting depends on the partitioning or collecting method chosen (it is
not available with the default auto methods).

Select the check boxes as follows:

v Perform Sort. Select this to specify that data coming in on the link should be sorted. Select the column
or columns to sort on from the Available list.
v Stable. Select this if you want to preserve previously sorted data sets. This is the default.
v Unique. Select this to specify that, if multiple records have identical sorting key values, only one
record is retained. If stable sort is also set, the first record is retained.

If NLS is enabled an additional button opens a dialog box allowing you to select a locale specifying the
collate convention for the sort.

You can also specify sort direction, case sensitivity, whether sorted as ASCII or EBCDIC, and whether null
columns will appear first or last for each column. Where you are using a keyed partitioning method, you
can also specify whether the column is used as a key for sorting, for partitioning, or for both. Select the
column in the Selected list and right-click to invoke the shortcut menu.

Chapter 48. Peek stage 517

Output page
The Output page allows you to specify details about data output from the Peek stage. The Peek stage can
have any number of output links. Select the link whose details you are looking at from the Output name
drop-down list.

The General tab allows you to specify an optional description of the output link. The Columns tab
specifies the column definitions of the data. The Mapping tab allows you to specify the relationship
between the columns being input to the Peek stage and the Output columns. The Advanced tab allows
you to change the default buffering settings for the output links.

Details about Peek stage mapping is given in the following section. See ″Stage Editors,″ for a general
description of the other tabs.

Mapping tab
For the Peek stage the Mapping tab allows you to specify how the output columns are derived, i.e., what
input columns map onto them or how they are generated.

The left pane shows the columns being peeked. These are read only and cannot be modified on this tab.

The right pane shows the output columns for each link. This has a Derivations field where you can
specify how the column is derived. You can fill it in by dragging input columns over, or by using the
Auto-match facility.

518 Parallel Job Developer Guide

Chapter 49. Row Generator stage
The Row Generator stage is a Development/Debug stage. It has no input links, and a single output link.

The Row Generator stage produces a set of mock data fitting the specified meta data. This is useful
where you want to test your job but have no real data available to process. (See also the Column
Generator stage which allows you to add extra columns to existing data sets, Chapter 50, “Column
Generator stage,” on page 525.)

The meta data you specify on the output link determines the columns you are generating.

The stage editor has two pages:

v Stage Page. This is always present and is used to specify general information about the stage.
v Output Page. This is where you specify details about the generated data being output from the stage.

Examples

Using a Row Generator Stage in Default Mode

In this example we are going to allow the Row Generator stage to generate a data set using default
settings for the data types. The only change we make is to ask for 100 rows to be generated, rather than
the default ten. We do this by setting the Number of records property to 100 in the Properties tab.

We need to tell the stage how many columns in the generated data set and what type each column has.
We do this in the Output page Columns tab by specifying the following column definitions:

Column name SQL type

string Char
date Date
time Time
timestamp Char
integer integer
decimal Decimal

When we run the job, WebSphere DataStage generates a data set containing the following rows (sample
shown):

© Copyright IBM Corp. 2006 519

We can see from this the type of that is generated by default. For example, for date fields, the first row
has January 1st 1960, and this is incremented by one day for each subsequent row.

We can specify more details about each data type if required to shape the data being generated.

Example of specifying data to be generated

You can specify more details about the type of data being generated from the Edit Column Meta Data
dialog box. This is accessed from the Edit row... shortcut menu for individual column definitions on the
Output page Columns tab.

The Edit Column Meta Data dialog box contains different options for each data type. The possible
options are described in ″Generator″ . We can use the Next and <Previous buttons to go through all our
columns.

Using this dialog box we specify the following for the generated data:
v string
– Algorithm = cycle
– seven separate Values (assorted animals).
v date
– Epoch = 1958-08-18
– Type = cycle
– Increment = 10
v time
– Scale factor = 60
– Type = cycle
– Increment = 1
v timestamp

520 Parallel Job Developer Guide

 – Epoch = 1958-08-18
– Scale factor = 60
– Type = cycle
– Increment = 1
v integer
– Type = cycle
– Initial value = 300
– Increment = 10
– Limit = 3000
v decimal
– Percent invalid = 20
– Percent zeros = 20
– Type = random
– Seed=200

Here is the data generated by these settings, compare this with the data generated by the default settings.

Example of generating data in parallel

By default the Row Generator stage runs sequenially, generating data in a single partition. You can,
however, configure it to run in parallel, and you can use the partition number when you are generating
data to, for example, increment a value by the number of partitions. You will also get the Number of
Records you specify in each partition (so in our example where we have asked for 100 records, you will
get 100 records in each partition rather than 100 records divided between the number of partitions).

In this example we are generating a data set comprising two integers. One is generated by cycling, one
by random number generation.

Chapter 49. Row Generator stage 521

The cycling integer’s initial value is set to the partition number (using the special value `part’) and its
increment is set to the number of partitions (using the special value `partcount’). This is set in the Edit
Column Meta Data dialog box as follows (select column in Columns tab and choose Edit Row... from
shortcut menu):

The random integer’s seed value is set to the partition number, and the limit to the total number of
partitions.

When we run this job in parallel, on a system with four nodes, the data generated in partition 0 is as
follows:

integer1 integer2
0 1
4 2
8 3
12 2
16 3
20 1
24 2
28 3
32 3
36 1
40 0
44 3
48 3
52 2
56 0
60 0
64 1
68 3
72 2
76 2
80 0
84 1

522 Parallel Job Developer Guide

integer1 integer2
... ...

Must do’s
WebSphere DataStage has many defaults which means that it can be very easy to include Row Generator
stages in a job. This section specifies the minimum steps to take to get a Row Generator stage
functioning. WebSphere DataStage provides a versatile user interface, and there are many shortcuts to
achieving a particular end, this section describes the basic method, you will learn where the shortcuts are
when you get familiar with the product.

To use a Row Generator stage:

v In the Stage page Properties Tab, specify the Number of Records you want to generate.
v Specify the meta data for the rows you want to generate. You can do this either in the Output page
Columns Tab, or by specifying a schema file using the Schema File property on the Stage Page
Properties Tab.

Stage page
The General tab allows you to specify an optional description of the stage. The Advanced tab allows you
to specify how the stage executes.

Advanced tab
This tab allows you to specify the following:
v Execution Mode. The Generate stage executes in Sequential mode by default. You can select Parallel
mode to generate data sets in separate partitions.
v Combinability mode. This is Auto by default, which allows WebSphere DataStage to combine the
operators that underlie parallel stages so that they run in the same process if it is sensible for this type
of stage.
v Preserve partitioning. This is Propagate by default. If you have an input data set, it adopts Set or
Clear from the previous stage. You can explicitly select Set or Clear. Select Set to request the next stage
should attempt to maintain the partitioning.
v Node pool and resource constraints. Select this option to constrain parallel execution to the node pool
or pools and/or resource pool or pools specified in the grid. The grid allows you to make choices from
drop down lists populated from the Configuration file.
v Node map constraint. Select this option to constrain parallel execution to the nodes in a defined node
map. You can define a node map by typing node numbers into the text box or by clicking the browse
button to open the Available Nodes dialog box and selecting nodes from there. You are effectively
defining a new node pool for this stage (in addition to any node pools defined in the Configuration
file).

Output page
The Output page allows you to specify details about data output from the Row Generator stage.

The General tab allows you to specify an optional description of the output link. The Properties tab lets
you specify what the stage does. The Columns tab specifies the column definitions of outgoing data. The
Advanced tab allows you to change the default buffering settings for the output link.

Chapter 49. Row Generator stage 523

Properties tab
The Properties tab allows you to specify properties which determine what the stage actually does. Some
of the properties are mandatory, although many have default settings. Properties without default settings
appear in the warning color (red by default) and turn black when you supply a value for them. The
following table gives a quick reference list of the properties and their attributes. A more detailed
description of each property follows.

Category/
Property Values Default Mandatory? Repeats? Dependent of
Options/Number number 10 Y N N/A
of Records
Options/Schema pathname N/A N N N/A
File

Options category
Number of records

The number of records you want your generated data set to contain.

The default number is 10.

Schema file

By default the stage will take the meta data defined on the output link to base the mock data set on. But
you can specify the column definitions in a schema file, if required. You can browse for the schema file or
specify a job parameter.

524 Parallel Job Developer Guide

Chapter 50. Column Generator stage
The Column Generator stage is a Development/Debug stage. It can have a single input link and a single
output link.

The Column Generator stage adds columns to incoming data and generates mock data for these columns
for each data row processed. The new data set is then output. (See also the Row Generator stage which
allows you to generate complete sets of mock data, Chapter 49, “Row Generator stage,” on page 519.)

The stage editor has three pages:

v Stage Page. This is always present and is used to specify general information about the stage.
v Input Page. This is where you specify details about the input link.
v Output Page. This is where you specify details about the generated data being output from the stage.

Example
For our example we are going to generate an extra column for a data set containing a list of
seventeenth-century inhabitants of Woodstock, Oxfordshire. The extra column will contain a unique id for
each row.

The columns for the data input to the Column Generator stage is as follows:

Column name SQL type Length

DocumentID VarChar 50
Year VarChar 50
Orderno Integer 10
Fname VarChar 50
Sname VarChar 50
Office VarChar 50

We set the Column Generator properties to add an extra column called uniqueid to our data set as
follows:
v Column Method = Explicit
v Column To Generate = uniqueid

The new column now appears on the Output page Mapping tab and can be mapped across to the output
link (so it appears on the Output page Columns

© Copyright IBM Corp. 2006 525

tab):

In this example we select the uniqueid column on the Output page Columns tab, then choose Edit Row...
from the shortcut menu. The Edit Column Meta Data dialog box appears and lets us specify more details
about the data that will be generated for the new column. First we change the type from the default of
char to integer. Because we are running the job in parallel, we want to ensure that the id we are
generating will be unique across all partitions, to do this we set the initial value to the partition number
(using the special value `part’) and the increment to the number of partions (using the special
`partcount’):

When we run the job in parallel on a four-node system the stage will generate the uniqueid column for
each row. Here are samples of partion 0 and partition 1 to show how the unique number is generated:

uniqueid DocumentID Year Orderno Fname Sname

0 WBR 96 folio 11 1617 110 Henry Archer
4 WBR 96 folio 15 1619 115 Henry Archer
8 WBR 96 folio 21 1622 117 Henry Archer
12 WBR 96 folio 15 1619 95 John Archer
16 WBR 96 folio 21 1622 82 John Archer
20 WBR 96 folio 34 1627 95 John Archer
24 WBR 96 folio 1-46 1662 125 Thomas Archer
28 (court leet 1687 67 Thomas Archer
attendees)
32 Portmouth Book 1616 36 William Archer
36 WBR 96 folio 11 1617 37 William Archer
40 WBR 96 folio 1-46 1662 102 William Ball
44 WBR 96 folio 11 1617 59 George Barnsley

526 Parallel Job Developer Guide

uniqueid DocumentID Year Orderno Fname Sname
48 Portmouth Book 1616 35 John Batt
52 Portmouth Book 1616 65 John Batt
56 WBR 96 folio 11 1617 35 John Batt
60 WBR 96 folio 15 1619 37 John Batt
64 WBR 96 folio 15 1619 38 John Batt
68 WBR 96 folio 15 1619 114 Gey Becksley
72 WBR 96 folio 21 1622 116 Gey Becksley
76 WBR 96 folio 34 1627 114 Guye Becksley

uniqueid DocumentID Year Orderno Fname Sname

1 WBR 96 folio 21 1622 113 Marmad ?
5 WBR 96 folio 21 1622 68 Thomas Asplene
9 (court leet 1687 83 Charles Aston
attendees)
13 WBR 96 folio 34 1627 107 Richard Barnshooe
17 WBR 96 folio 34 1627 103 Walter Bayless
21 (court leet 1687 3 Nicholas Baynton
attendees)
25 WBR 96 folio 21 1622 111 Robert Belcher
29 WBR 96 folio 11 1617 102 Thomas Belcher
33 WBR 96 folio 1-46 1662 24 Perrigrine Bertie
37 WBR 96 folio 1-46 1662 16 John Bignill
41 Portmouth Book 1616 16 Robert Bignill
45 WBR 96 folio 1-46 1662 48 James Blunden
49 (court leet 1687 66 William Blunden
attendees)
53 WBR 96 folio 1-46 1662 119 John Borman
57 WBR 96 folio 11 1617 68 Henry Bradshaw
61 WBR 96 folio 34 1627 88 William Bradshaw
65 WBR 96 folio 21 1622 23 Robert Brewce
69 WBR 96 folio 21 1622 21 Thomas Brewce
73 WBR 96 folio 1-46 1662 84 Richard Broffett
77 (court leet 1687 34 John Brotherton
attendees)

Must do’s
WebSphere DataStage has many defaults which means that it can be very easy to include Column
Generator stages in a job. This section specifies the minimum steps to take to get a Column Generator
stage functioning. WebSphere DataStage provides a versatile user interface, and there are many shortcuts
to achieving a particular end, this section describes the basic method, you will learn where the shortcuts
are when you get familiar with the product.

Chapter 50. Column Generator stage 527

To use a Column Generator stage:
v In the Stage page Properties Tab, specify the Column Method. This is explicit by default, which means
that you should specify the meta data for the columns you want to generate on the Output Page
Columns tab. If you use the Explicit method, you also need to specify which of the output link
columns you are generating in the Column to Generate property. You can repeat this property to
specify multiple columns. If you use the Schema File method, you should specify the schema file.
v Ensure you have specified the meta data for the columns you want to add. If you have specified a
Column Method of explicit, you should do this on the Output Page Columns tab. If you have specified
a Column Method of Schema File, you should specify a schema file.
v In the Output Page Mapping Tab, specify how the incoming columns and generated columns map
onto the output columns.

Stage page
The General tab allows you to specify an optional description of the stage. The Properties tab lets you
specify what the stage does. The Advanced tab allows you to specify how the stage executes.

Properties tab
The Properties tab allows you to specify properties which determine what the stage actually does. Some
of the properties are mandatory, although many have default settings. Properties without default settings
appear in the warning color (red by default) and turn black when you supply a value for them.

The following table gives a quick reference list of the properties and their attributes. A more detailed
description of each property follows.

Category/
Property Values Default Mandatory? Repeats? Dependent of
Options/Column Explicit/ Column Explicit Y N N/A
Method Method
Options/Column output column N/A Y Y (if Column N/A
to Generate Method =
Explicit)
Options/Schema pathname N/A N Y (if Column N/A
File Method = Schema
File)

Options category
Column method

Select Explicit if you are going to specify the column or columns you want the stage to generate data for.
Select Schema File if you are supplying a schema file containing the column definitions.

Column to generate

When you have chosen a column method of Explicit, this property allows you to specify which output
columns the stage is generating data for. Repeat the property to specify multiple columns. You can
specify the properties for each column using the Parallel tab of the Edit Column Meta Dialog box
(accessible from the shortcut menu on the columns grid of the output Columns tab). You can use the
Column Selection dialog box to specify several columns at once if required.

528 Parallel Job Developer Guide

Schema file

When you have chosen a column method of schema file, this property allows you to specify the column
definitions in a schema file. You can browse for the schema file or specify a job parameter.

Advanced tab
This tab allows you to specify the following:
v Execution Mode. The stage can execute in parallel mode or sequential mode. In parallel mode the
input data is processed by the available nodes as specified in the Configuration file, and by any node
constraints specified on the Advanced tab. In Sequential mode the entire data set is processed by the
conductor node.
v Combinability mode. This is Auto by default, which allows WebSphere DataStage to combine the
operators that underlie parallel stages so that they run in the same process if it is sensible for this type
of stage.
v Preserve partitioning. This is Propagate by default. If you have an input data set, it adopts Set or
Clear from the previous stage. You can explicitly select Set or Clear. Select Set to request the next stage
should attempt to maintain the partitioning.
v Node pool and resource constraints. Select this option to constrain parallel execution to the node pool
or pools and/or resource pool or pools specified in the grid. The grid allows you to make choices from
drop down lists populated from the Configuration file.
v Node map constraint. Select this option to constrain parallel execution to the nodes in a defined node
map. You can define a node map by typing node numbers into the text box or by clicking the browse
button to open the Available Nodes dialog box and selecting nodes from there. You are effectively
defining a new node pool for this stage (in addition to any node pools defined in the Configuration
file).

Input page
The Input page allows you to specify details about the incoming data set you are adding generated
columns to. There is only one input link and this is optional.

The General tab allows you to specify an optional description of the link. The Partitioning tab allows you
to specify how incoming data on the source data set link is partitioned. The Columns tab specifies the
column definitions of incoming data. The Advanced tab allows you to change the default buffering
settings for the input link.

Details about Generate stage partitioning are given in the following section. See ″Stage Editors,″ for a
general description of the other tabs.

Partitioning on input links

The Partitioning tab allows you to specify details about how the incoming data is partitioned or collected
before the generate is performed.

By default the stage uses the auto partitioning method.

If the Column Generator stage is operating in sequential mode, it will first collect the data before writing
it to the file using the default auto collection method.

The Partitioning tab allows you to override this default behavior. The exact operation of this tab depends
on:
v Whether the Column Generator stage is set to execute in parallel or sequential mode.

Chapter 50. Column Generator stage 529

v Whether the preceding stage in the job is set to execute in parallel or sequential mode.

If the Column Generator stage is set to execute in parallel, then you can set a partitioning method by
selecting from the Partition type drop-down list. This will override any current partitioning.

If the Column Generator stage is set to execute in sequential mode, but the preceding stage is executing
in parallel, then you can set a collection method from the Collector type drop-down list. This will
override the default auto collection method.

The following partitioning methods are available:

v (Auto). WebSphere DataStage attempts to work out the best partitioning method depending on
execution modes of current and preceding stages and how many nodes are specified in the
Configuration file. This is the default method for the Column Generator stage.
v Entire. Each file written to receives the entire data set.
v Hash. The records are hashed into partitions based on the value of a key column or columns selected
from the Available list.
v Modulus. The records are partitioned using a modulus function on the key column selected from the
Available list. This is commonly used to partition on tag fields.
v Random. The records are partitioned randomly, based on the output of a random number generator.
v Round Robin. The records are partitioned on a round robin basis as they enter the stage.
v Same. Preserves the partitioning already in place.
v DB2. Replicates the DB2 partitioning method of a specific DB2 table. Requires extra properties to be
set. Access these properties by clicking the properties button.
v Range. Divides a data set into approximately equal size partitions based on one or more partitioning
keys. Range partitioning is often a preprocessing step to performing a total sort on a data set. Requires
extra properties to be set. Access these properties by clicking the properties button.

The following Collection methods are available:

v (Auto). This is the default collection method for the Column Generator stage. Normally, when you are
using Auto mode, WebSphere DataStage will eagerly read any row from any input partition as it
becomes available.
v Ordered. Reads all records from the first partition, then all records from the second partition, and so
on.
v Round Robin. Reads a record from the first input partition, then from the second partition, and so on.
After reaching the last partition, the operation starts over.
v Sort Merge. Reads records in an order based on one or more columns of the record. This requires you
to select a collecting key column from the Available list.

The Partitioning tab also allows you to specify that data arriving on the input link should be sorted
before the column generate operation is performed. The sort is always carried out within data partitions.
If the stage is partitioning incoming data the sort occurs after the partitioning. If the stage is collecting
data, the sort occurs before the collection. The availability of sorting depends on the partitioning or
collecting method chosen (it is not available for the default auto methods).

Select the check boxes as follows:

v Perform Sort. Select this to specify that data coming in on the link should be sorted. Select the column
or columns to sort on from the Available list.
v Stable. Select this if you want to preserve previously sorted data sets. This is the default.
v Unique. Select this to specify that, if multiple records have identical sorting key values, only one
record is retained. If stable sort is also set, the first record is retained.

530 Parallel Job Developer Guide

If NLS is enabled an additional button opens a dialog box allowing you to select a locale specifying the
collate convention for the sort.

You can also specify sort direction, case sensitivity, whether sorted as ASCII or EBCDIC, and whether null
columns will appear first or last for each column. Where you are using a keyed partitioning method, you
can also specify whether the column is used as a key for sorting, for partitioning, or for both. Select the
column in the Selected list and right-click to invoke the shortcut menu.

Output page
Details about Column Generator stage mapping is given in the following section. See ″Stage Editors,″ for
a general description of the other tabs.

Mapping tab
For Column Generator stages the Mapping tab allows you to specify how the output columns are
derived, i.e., how the generated data maps onto them.

The left pane shows the generated columns. These are read only and cannot be modified on this tab.
These columns are automatically mapped onto the equivalent output columns.

The right pane shows the output columns for the output link. This has a Derivations field where you can
specify how the column is derived.You can fill it in by dragging input columns over, or by using the
Auto-match facility.

The right pane represents the data being output by the stage after the generate operation.

Chapter 50. Column Generator stage 531

532 Parallel Job Developer Guide
Chapter 51. Write Range Map stage
The Write Range Map stage is a Development/Debug stage. It allows you to write data to a range map.
The stage can have a single input link. It can only run in sequential mode.

The Write Range Map stage takes an input data set produced by sampling and sorting a data set and
writes it to a file in a form usable by the range partitioning method. The range partitioning method uses
the sampled and sorted data set to determine partition boundaries. .

A typical use for the Write Range Map stage would be in a job which used the Sample stage to sample a
data set, the Sort stage to sort it and the Write Range Map stage to write the range map which can then
be used with the range partitioning method to write the original data set to a file set.

The Write Range Map stage editor has two pages:

v Stage Page. This is always present and is used to specify general information about the stage.
v Input Page. This is present when you are writing a range map. This is where you specify details about
the file being written to.

Example
In this example, we sample the data in a flat file then pass it to the Write Range Map stage. The stage
sorts the data itself before constructing a range map and writing it to a file.

© Copyright IBM Corp. 2006 533

The stage sorts the data on the same key that it uses to create the range map. The shows the properties
that determine how the stage will produce the range map:

Must do’s
WebSphere DataStage has many defaults which means that it can be very easy to include Write Range
Map stages in a job. This section specifies the minimum steps to take to get a Write Range Map stage
functioning. WebSphere DataStage provides a versatile user interface, and there are many shortcuts to
achieving a particular end, this section describes the basic method, you will learn where the shortcuts are
when you get familiar with the product.

To use a Write Range Map stage:

v In the Input Link Properties Tab:
– Specify the key column(s) for the range map you are creating.
– Specify the name of the range map you are creating.
– Specify whether it is OK to overwrite an existing range map of that name (be default an error occurs
if a range map with that name already exists).
v Ensure that column definitions have been specified for the range map (this can be done in an earlier
stage).

Stage page
The General tab allows you to specify an optional description of the stage. The Advanced tab allows you
to specify how the stage executes. The NLS Locale tab appears if your have NLS enabled on your system.
It allows you to select a locale other than the project default to determine collating rules.

534 Parallel Job Developer Guide

Advanced tab
This tab allows you to specify the following:
v Execution Mode. The stage always executes in sequential mode.
v Combinability mode. This is Auto by default, which allows WebSphere DataStage to combine the
operators that underlie parallel stages so that they run in the same process if it is sensible for this type
of stage.
v Preserve partitioning. This is Set by default. The Partition type is range and cannot be overridden.
v Node pool and resource constraints. Select this option to constrain parallel execution to the node pool
or pools and/or resource pool or pools specified in the grid. The grid allows you to make choices from
drop down lists populated from the Configuration file.
v Node map constraint. Select this option to constrain parallel execution to the nodes in a defined node
map. You can define a node map by typing node numbers into the text box or by clicking the browse
button to open the Available Nodes dialog box and selecting nodes from there. You are effectively
defining a new node pool for this stage (in addition to any node pools defined in the Configuration
file).

NLS Locale tab

This appears if you have NLS enabled on your system. It lets you view the current default collate
convention, and select a different one for this stage if required. You can also use a job parameter to
specify the locale, or browse for a file that defines custom collate rules. The collate convention defines the
order in which characters are collated. The Write Range Map stage uses this when it is determining the
sort order for key columns. Select a locale from the list, or click the arrow button next to the list to use a
job parameter or browse for a collate file.

Input page
The Input page allows you to specify details about how the Write Range Map stage writes the range map
to a file. The Write Range Map stage can have only one input link.

The General tab allows you to specify an optional description of the input link. The Properties tab allows
you to specify details of exactly what the link does. The Partitioning tab allows you to view collecting
details. The Columns tab specifies the column definitions of the data. The Advanced tab allows you to
change the default buffering settings for the input link.

Details about Write Range Map stage properties and collecting are given in the following sections. See
″Stage Editors,″ for a general description of the other tabs.

Input Link Properties tab

The Properties tab allows you to specify properties for the input link. These dictate how incoming data is
written to the range map file. Some of the properties are mandatory, although many have default settings.
Properties without default settings appear in the warning color (red by default) and turn black when you
supply a value for them.

The following table gives a quick reference list of the properties and their attributes. A more detailed
description of each property follows.

Category/
Property Values Default Mandatory? Repeats? Dependent of
Options/File Create/Overwrite Create Y N N/A
Update Mode

Chapter 51. Write Range Map stage 535

Category/
Property Values Default Mandatory? Repeats? Dependent of
Options/Key input column N/A Y Y N/A
Options/ Ascending/ Ascending N N Key
Descending
Options/ True/False True N N Key
Options/ First/Last First N N Key
Options/ True/False False N N Key
Options/Range pathname N/A Y N N/A
Map File

Options category
File update mode

This is set to Create by default. If the file you specify already exists this will cause an error. Choose
Overwrite to overwrite existing files.

Key

This allows you to specify the key for the range map. Choose an input column from the drop-down list.
You can specify a composite key by specifying multiple key properties. You can use the Column Selection
dialog box to select several keys at once if required). Key has the following dependent properties:
Sort Order
Choose Ascending or Descending. The default is Ascending.
Case Sensitive
This property is optional. Use this to specify whether each group key is case sensitive or not, this
is set to True by default, i.e., the values “CASE” and “case” would not be judged equivalent.
Nulls Position
This property is optional. By default columns containing null values appear first in the sorted
data set. To override this default so that columns containing null values appear last in the sorted
data set, select Last.
Sort as EBCDIC
To sort as in the EBCDIC character set, choose True.

Range map file

Specify the file that is to hold the range map. You can browse for a file or specify a job parameter.

Partitioning tab
The Partitioning tab normally allows you to specify details about how the incoming data is partitioned or
collected before it is written to the file or files. In the case of the Write Range Map stage execution is
always sequential, so there is never a need to set a partitioning method.

You can set a collection method if collection is required. The following Collection methods are available:
v (Auto). This is the default collection method for the Column Generator stage. Normally, when you are
using Auto mode, WebSphere DataStage will eagerly read any row from any input partition as it
becomes available.
v Ordered. Reads all records from the first partition, then all records from the second partition, and so
on.

536 Parallel Job Developer Guide

v Round Robin. Reads a record from the first input partition, then from the second partition, and so on.
After reaching the last partition, the operation starts over.
v Sort Merge. Reads records in an order based on one or more columns of the record. This requires you
to select a collecting key column from the Available list.

The Partitioning tab also allows you to specify that data arriving on the input link should be sorted
before the write range map operation is performed. If the stage is collecting data, the sort occurs before
the collection. The availability of sorting depends on the collecting method chosen (it is not available for
the default auto methods).

Select the check boxes as follows:

v Perform Sort. Select this to specify that data coming in on the link should be sorted. Select the column
or columns to sort on from the Available list.
v Stable. Select this if you want to preserve previously sorted data sets. This is the default.
v Unique. Select this to specify that, if multiple records have identical sorting key values, only one
record is retained. If stable sort is also set, the first record is retained.

If NLS is enabled an additional button opens a dialog box allowing you to select a locale specifying the
collate convention for the sort.

You can also specify sort direction, case sensitivity, whether sorted as ASCII or EBCDIC, and whether null
columns will appear first or last for each column. Where you are using a keyed partitioning method, you
can also specify whether the column is used as a key for sorting, for partitioning, or for both. Select the
column in the Selected list and right-click to invoke the shortcut menu. Because the partition mode is set
and cannot be overridden, you cannot use the stage sort facilities, so these are disabled.

Chapter 51. Write Range Map stage 537

538 Parallel Job Developer Guide
Chapter 52. Parallel jobs on USS
This chapter explains how parallel jobs can be deployed and run on mainframe systems running z/OS®
UNIX System Services (popularly known as USS).

You specify that you want to run jobs on USS systems in the WebSphere DataStage Administrator client.
This is done on a per-project basis. Once you have elected to deploy jobs in a project to USS, you can no
longer run parallel jobs from that project on your WebSphere DataStage server unless you opt to switch
back. See WebSphere DataStage Administrator Client Guide for details on how to set up a project for
deployment to USS.

Note: You cannot include server shared containers, BASIC Transformer stages, or supplementary stages
in a job intended for deployment on a USS system. The DB2 stage is the only database stage
currently supported.

Set up
To set up the deployment and running of parallel jobs on a USS system, you need to take the following
steps:
1. Use the WebSphere DataStage Administrator to specify a project that will be used for parallel jobs
intended for USS deployment (see WebSphere DataStage Administrator Client Guide).
2. Install the parallel engine on the USS machine and set up access to it as described in IBM WebSphere
DataStage Installation and Administration Guide.
3. On the server machine, set the environment variable APT_ORCHHOME to identify the parallel
engine’s top-level directory on the USS system.
4. On the WebSphere DataStage server machine, construct a suitable configuration file, and set the
APT_CONFIG_FILE environment variable to point to it.

Deployment options
There are two options for deploying on USS:
v Under control of WebSphere DataStage. Jobs run under the control of the WebSphere DataStage
Director client. This method suits the scenario where the job developer has direct access to the USS
machine.
v Deploy standalone. Parallel jobs scripts are transferred to the USS machine and run there totally
independently of WebSphere DataStage. This method suites the scenario where jobs are run by
operators or external schedulers, maybe overnight.

You can have both of these options selected at once, if required, so you do not have to decide how to run
a job until you come to run it.

Deploy under control of WebSphere DataStage

With this option selected, you design a job as normal using the WebSphere DataStage Designer. When
you compile the job, WebSphere DataStage automatically sends it to the machine and the location
specified in the WebSphere DataStage Administrator.

When you are ready to run the job, you start the WebSphere DataStage Director client and select the job
and run it as you would any other job. WebSphere DataStage sends two more files to the USS machine,

© Copyright IBM Corp. 2006 539

specifying environment variables and job parameters for the job run. It then uses a remote shell to
execute the job on the USS machine. You can specify the remote shell commands and options in the
WebSphere DataStage Administrator.

As the job runs, logging information is captured from the remotely executing job and placed in the
WebSphere DataStage log in real time. The log messages indicate that they originate from a remote
machine. You can monitor the job from the Director, and collect operational metadata.

Note: Only size-based monitoring is available when jobs run on the USS system: i.e., you cannot set
APT_MONITOR_TIME, only APT_MONITOR_SIZE.

You can run a job on a USS system using the command line or job control interfaces on your WebSphere
DataStage Server as described in the WebSphere DataStage Parallel Job Developer Guide. You can also include
jobs in a job sequence.

There are certain restrictions on the use of the built-in WebSphere DataStage macros when running jobs
on USS:
Macro Restrictions
DSHostName
Name of WebSphere DataStage server, not of USS machine
DSProjectName
Supported
DSJobController
Supported
DSJobName
Supported
DSJobStartTimeStamp
Supported, but gives server date and time
DSJobStartDate
Supported, but gives server date
DSJobStartTime
Supported, but gives server time
DSJobWaveNo
Supported
DSJobInvocationId
Supported
DSProjectMapName
Supported (internal value)

When you deploy under the control of WebSphere DataStage, certain other functions besides running jobs
are available:
v View Data.
v Data set management tool.
v Configuration file editing and validation.
v Deployment of build stages on USS.
v Importing Orchestrate schemas.

Special considerations about these features are described in the following sections.

540 Parallel Job Developer Guide

Using View Data
The View Data button is available on some stage editors, and allows you to view the actual data on a
source stage. This facility is available in USS projects if FTP and remote shell options are enabled.
WebSphere DataStage FTPs and remotely executes a script on the USS machine which accesses the data
and returns it to the WebSphere DataStage server.

Using the Data Set Management tool

The Data Set Management tool is available from the WebSphere DataStage Designer and Director clients.
This allows you to view source or, provided the job has already been run, target data sets (see ″Managing
Data Sets.″)

The tool is available from USS projects if FTP and remote shell options are enabled. The header bar of the
data set Browse File dialog box indicates that you are browsing data sets on a remote machine.

Editing and validating configuration files

In order to run parallel jobs on a USS machine, it must have a configuration file which describes its
parallel capabilities. The default configuration file supplied with the project is NOT suitable for USS
deployment (it is designed to run jobs on the WebSphere DataStage server).The Designer has a tool which
allows you to create, edit and validate configuration files. When you use this tool from within a USS
project that is deployed under the control of WebSphere DataStage, the configuration file is mirrored on
the USS machine. It is updated whenever the file on the server is saved. When you use the Check feature,
the file is validated against the USS syatem configuration. The title bar of the Configuration file tool
indicates that the file is on the USS machine.

We recommend that you change the APT_CONFIG_FILE environment variable in your project to point to
the location of your USS configuration file on the server machine (WebSphere DataStage knows the
location on the USS machine and translates as appropriate). Although you can set it to point directly to
the file on the USS machine itself.

Deploying Build stages

WebSphere DataStage allows you to develop your own stages for parallel jobs as described in the
WebSphere DataStage Parallel Job Developer Guide. You can deploy such stages to USS systems for inclusion
in parallel jobs. When you generate a Build stage in a USS project, it is automatically sent to the USS
machine and built there so that any jobs developed that use the stage will successfully run under USS.

Importing Orchestrate schemas

WebSphere DataStage allows you to import table definitions from Orchestrate schemas. This uses the
Import Orchestrate Schema wizard, available from the Designer (see WebSphere DataStage Designer
Client Guide). When you are importing definitions into a USS project, the wizard allows you to import
from text files, data sets, or file sets on the USS machine.

Deploy standalone
With this option selected, you design a job as normal using the Designer. When you compile the job,
WebSphere DataStage produces files which can be transferred to the USS machine using your preferred
method. You can then set the correct execute permissions for the files and run the job on the USS
machine by executing scripts.

If you have specified a remote machine name in the WebSphere DataStage Administrator Project
Properties Remote tab (see WebSphere DataStage Administrator Client Guide), files will automatically be sent
to the USS machine. The job can then be run by executing the scripts on the machine to compile any
transformers the job contains and then run the job.

Chapter 52. Parallel jobs on USS 541

You can also enable the send and/or remote shell capabilities in isolation by supplying the required
details to the Remote page in the project properties in the WebSphere DataStage Administrator.

Different restrictions reply to the WebSphere DataStage built-in macros when you run a job using the
deploy standalone method:
Macro Restrictions
DSHostName
Name of WebSphere DataStage server, not of USS machine
DSProjectName
Supported
DSJobController
Not supported
DSJobName
Supported
DSJobStartTimeStamp
Not supported
DSJobStartDate
Not supported
DSJobStartTime
Not supported
DSJobWaveNo
Not supported
DSJobInvocationId
Not supported
DSProjectMapName
Supported (internal value)

Details of the files that are created and where they should be transferred to on the USS machine are given
in the following section, ″Implementation Details″.

Implementation details
This section describes the directory structure required for job deployment on USS machines. It also
describes files that are generated by WebSphere DataStage when you compile a job in a USS project.

Directory structure
Each job deployed to the USS machine must have a dedicated directory. If you are allowing WebSphere
DataStage to automatically send files to the USS machine for you at compile time, the files are, by
default, copied to the following directory:
/Base_directory/project_name/RT_SCjobnumber
v Base_directory. You must specify a specific base directory in the WebSphere DataStage Administrator
(see WebSphere DataStage Administrator Client Guide).
v project_name. This is a directory named after the USS project.
v RT_SCjobnum. This is the directory that holds all the deployment files for a particular job. By default
the job directory is RT_SCjobnum where jobnum is the internal jobnumber allocated by WebSphere
DataStage, but you can change the form of this name in the Administrator client (see WebSphere
DataStage Administrator Client Guide.

542 Parallel Job Developer Guide

If you are deploying standalone, and are not automatically sending files, you can specify your own
directory structure, but we recommend that you follow the /base_directory/project_name/job_identifier
model.

On the WebSphere DataStage server the files are copied to the directory:
$DSHOME/../Projects/project_name/RT_SCjobnumber

Generated files
When you compile a parallel job intended for deployment on a USS machine, it produces various files
which are copied into the job directory on the USS machine. The files are as follows:
File Purpose
OshScript.osh
The main parallel job script . This script is run automatically via a remote shell when jobs are run
under the control of WebSphere DataStage. The script needs to be run manually using the
pxrun.sh script when jobs are deployed standalone.
pxrun.sh
This script is run in order to run OshScript.osh when jobs are deployed standalone.
jpdepfile
This is used by pxrun.sh. It contains the job parameters for a job deployed standalone when it is
run. It is based on the default job parameters when the job was compiled.
evdepfile
This is sourced by pxrun.sh. It contains the environment variables for a job deployed standalone
when it is run. It is based on the environment variables set when the job was compiled.
pxcompile.sh
This file is generated if the job contains one or more Transformer stages and the Deploy
Standalone option is selected. It is used to control the compilation of the transformers on the USS
machine.
internalidentifier _jobname_stagename.trx
There is a file for each Transformer stage in the job; it contains the source code for each stage.
internalidentifier _jobname_stagename.trx.sh
This is a script for compiling Transformer stages. There is one for each transformer stage. It is
called by pxcompile.sh; it can be called individually if required.
internalidentifier _jobname_stagename.trx.osh
Parallel job script to compile the corresponding Transformer stage. Called from corresponding .sh
file.

Where you are deploying jobs under the control of WebSphere DataStage, you will also see the following
files in the job directory on the USS machine:
v OshExecute.sh. This executes the job script, OshScript.osh, under the control of WebSphere DataStage.
You should NOT attempt to run this file manually.
v jpfile and evfile. These are visible while the job is actually running and contain the job parameters and
environment variables used for the job run.

If your job contains one or more Transformer stages, you will also see the following files in your job
directory:
v jobnamestagename.trx.so. Object file, one for each Transformer stage.
v jobnamestagename.trx.C. If the compilation of the corresponding Transformer stage fails for some reason,
this file is left behind.

Chapter 52. Parallel jobs on USS 543

Configuration files
In order to run parallel jobs on the USS machine, there must be a configuration file describing the parallel
capabilities of that machine (see ″The Parallel Engine Configuration File.″)

If you deploy jobs under the control of WebSphere DataStage the configuration maintained on the server
will be automatically mirrored on the USS machine when you edit it.

If you deploy jobs standalone, you must ensure that the USS system has a valid configuration file
identified by the environment variable APT_CONFIG_FILE..

Running jobs on the USS machine

This section describes three basic scenarios for running WebSphere DataStage parallel jobs on a USS
machine:
v Deploying under the control of WebSphere DataStage and running from the WebSphere DataStage
Director.
v Deploying under the control of WebSphere DataStage but running manually.
v Deploying and running manually.

Deploying and running from WebSphere DataStage

In order to deploy the job from WebSphere DataStage and run it from the Director, proceed as follows:
1. In the WebSphere DataStage Administrator, in the Project Properties dialog box, set up the project on
the Remote page as follows:
v Select the Jobs run under control of DataStage option.
v Specify the name of the target machine and the username and password used to connect to it. This
is used to send the job deployment files to the USS machine.
v Specify a template for the remote shell used to run the jobs (in most cases you can use the default,
so need take no action here).
v Specify a base directory on the USS machine to hold the project directory and all the individual job
directories.
v Optionally specify a template for naming the job directories on the USS machine.
v Optionally specify commands to be executed on the WebSphere DataStage server after the job files
have been deployed.
For more details about making these settings in the WebSphere DataStage Administrator, see in
WebSphere DataStage Administrator Client Guide.
2. In the Designer, design your parallel job as normal (but remember that you cannot use BASIC
Transformer stages, shared containers, or supplementary stages in jobs to run under USS).
3. When you are happy with your job design, compile it. As part of this process, the necessary files will
be sent to the specified location on the USS machine, and the remote shell invoked to set permissions
and perform other housekeeping tasks. The environment variables as set at job compile time, and any
default settings for job parameters are transferred as part of this process.
4. In the Director, select the job and run it. Set the required parameters and set any environment
variables required for this run in the Job Run Options dialog box. WebSphere DataStage will use the
remote shell to run the job on the USS machine (if required you could alternatively run the job from
the command line of the server machine, or using the job control facilities described in the WebSphere
DataStage Parallel Job Developer Guide).

544 Parallel Job Developer Guide

Deploying from WebSphere DataStage, running manually
This section described a halfway-house solution, whereby you can use WebSphere DataStage to
automatically copy the required files to the USS machine, and set the correct permissions, but run the
jobs manually directly from the USS machine.
1. In the WebSphere DataStage Administrator, in the Project Properties dialog box Parallel page, set up
the project as follows:
a. Select the Jobs run under control of DataStage option and the Deploy Standalone parallel job
scripts option.
b. Specify the name of the target machine and the username and password used to connect to it. This
is used to FTP the job deployment files to the USS machine.
c. Specify a template for the remote shell used to run the jobs.
d. Optionally specify a base directory on the USS machine to hold the project directory and all the
individual job directories.
e. Optionally specify a template for naming the job directories on the USS machine.
f. Optionally specify commands to be executed on the WebSphere DataStage server after the job files
have been deployed.
For more details about making these settings in the WebSphere DataStage Administrator, see
WebSphere DataStage Administrator Client Guide.
2. In the WebSphere DataStage Administrator, set the environment variable APT_CONFIG_FILE to
identify the configuration file used to run jobs on the USS system.
3. In the Designer, design your parallel job as normal (but remember that you cannot use BASIC
Transformer stages, server shared containers, or supplementary stages in jobs to run under USS).
4. When you are happy with your job design, compile it. As part of this process, the necessary files will
be FTPed to the specified location on the USS machine, and the remote shell invoked to set
permissions and perform other housekeeping tasks. The environment variables as set at job compile
time, and any default settings for job parameters are transferred as part of this process.
5. When you are ready to run your job, on the USS machine, go the job directory for the required job.
6. If your job contains Transformer stages, execute the following file:
pxcompile.sh
7. When your Transformer stages have successfully compiled, run the job by executing the following file:
pxrun.sh

Deploying and running manually

This describes how to set WebSphere DataStage up so that you both transfer jobs to the USS machine and
run them manually, without further intervention by WebSphere DataStage.
1. In the Administrator, in the Project Properties dialog box Remote page, set up the project as follows:
v Select the Deploy Standalone parallel job scripts option.
2. In the Administrator, set the environment variable APT_CONFIG_FILE to identify the configuration
file used to run jobs on the USS system.
3. In the Designer, design your parallel job as normal (but remember that you cannot use BASIC
Transformer stages, shared containers, or supplementary stages in jobs to run under USS).
4. When you are happy with your job design, compile it.
5. On your WebSphere DataStage server, go to the directory:
$DSHOME/../Projects/project_name/RT_SCjobnumber
6. Copy the following files to a directory on your USS machine (each job must be in a separate
directory):
v OshScript.osh

Chapter 52. Parallel jobs on USS 545

 v pxrun.sh
v jpdepfile
v evdepfile
If your job contains Transformer stages, you will also need to copy the following files:
v pxcompile.sh
v jobnamestagename.trx
v jobnamestagename.trx.sh
v jobnamestagename.trx.osh

Note: You can enter commands in the Custom deployment commands field in the Administrator
Project Properties dialog box Remote page to further automate the process of deployment,
for example:
tar -cvf * %j.tar
cp %j.tar /home/mydeploy
7. When you are ready to run your job, on the USS machine, go the job directory for the required job.
8. If your job contains Transformer stages, execute the following file:
pxcompile.sh
9. When your Transformer stages have successfully compiled, run the job by executing the following file:
pxrun.sh

546 Parallel Job Developer Guide

Chapter 53. Managing data sets
WebSphere DataStage parallel jobs use data sets to store data being operated on in a persistent form.
Data sets are operating system files, each referred to by a descriptor file, usually with the suffix .ds.

You can create and read data sets using the Data Set stage, which is described in Chapter 6, “File set
stage,” on page 99. WebSphere DataStage also provides a utility for managing data sets from outside a
job. This utility is available from the WebSphere DataStage Designer and Director clients.

Structure of data sets

A data set comprises a descriptor file and a number of other files that are added as the data set grows.
These files are stored on multiple disks in your system. A data set is organized in terms of partitions and
segments. Each partition of a data set is stored on a single processing node. Each data segment contains
all the records written by a single WebSphere DataStage job. So a segment can contain files from many
partitions, and a partition has files from many segments.

Partition 1 Partition 2 Partition 3 Partition 4

Segment 1

Segment 1

Segment 1

One or more
data files

The descriptor file for a data set contains the following information:
v Data set header information.
v Creation time and data of the data set.
v The schema of the data set.
v A copy of the configuration file use when the data set was created.

For each segment, the descriptor file contains:

v The time and data the segment was added to the data set.
v A flag marking the segment as valid or invalid.
v Statistical information such as number of records in the segment and number of bytes.
v Path names of all data files, on all processing nodes.

This information can be accessed through the Data Set Manager.

© Copyright IBM Corp. 2006 547

Starting the data set manager
To start the Data Set Manager from the WebSphere DataStage Designer, or Director:
1. Choose Tools → Data Set Management, a Browse Files dialog box appears.
2. Navigate to the directory containing the data set you want to manage. By convention, data set files
have the suffix .ds.
3. Select the data set you want to manage and click OK. The Data Set Viewer appears. From here you
can copy or delete the chosen data set. You can also view its schema (column definitions) or the data
it contains.

Data set viewer

The Data Set viewer displays information about the data set you are viewing:

Partitions

The partition grid shows the partitions the data set contains and describes their properties:
v #. The partition number.
v Node. The processing node that the partition is currently assigned to.
v Records. The number of records the partition contains.
v Blocks. The number of blocks the partition contains.
v Bytes. The number of bytes the partition contains.

Segments

Click on an individual partition to display the associated segment details. This contains the following
information:
v #. The segment number.
v Created. Date and time of creation.
v Bytes. The number of bytes in the segment.
v Pathname. The name and path of the file containing the segment in the selected partition.

Click the Refresh button to reread and refresh all the displayed information.

Click the Output button to view a text version of the information displayed in the Data Set Viewer.

You can open a different data set from the viewer by clicking the Open icon on the tool bar. The browse
dialog open box opens again and lets you browse for a data set.

Viewing the schema

Click the Schema icon from the tool bar to view the record schema of the current data set. This is
presented in text form in the Record Schema window.

Viewing the data

Click the Data icon from the tool bar to view the data held by the current data set. This options the Data
Viewer Options dialog box, which allows you to select a subset of the data to view.
v Rows to display. Specify the number of rows of data you want the data browser to display.
v Skip count. Skip the specified number of rows before viewing data.

548 Parallel Job Developer Guide

v Period. Display every Pth record where P is the period. You can start after records have been skipped
by using the Skip property. P must equal or be greater than 1.
v Partitions. Choose between viewing the data in All partitions or the data in the partition selected from
the drop-down list.

Click OK to view the selected data, the Data Viewer window appears.

Copying data sets

Click the Copy icon on the tool bar to copy the selected data set. TheCopy data set dialog box appears,
allowing you to specify a path where the new data set will be stored.

The new data set will have the same record schema, number of partitions and contents as the original
data set.

Note: You cannot use the UNIX cp command to copy a data set because WebSphere DataStage represents
a single data set with multiple files.

Deleting data sets

Click the Delete icon on the tool bar to delete the current data set data set. You will be asked to confirm
the deletion.

Note: You cannot use the UNIX rm command to copy a data set because WebSphere DataStage represents
a single data set with multiple files. Using rm simply removes the descriptor file, leaving the much
larger data files behind.

Chapter 53. Managing data sets 549

550 Parallel Job Developer Guide
Chapter 54. The Parallel engine configuration file
One of the great strengths of the WebSphere DataStage Enterprise Edition is that, when designing parallel
jobs, you don’t have to worry too much about the underlying structure of your system, beyond
appreciating its parallel processing capabilities. If your system changes, is upgraded or improved, or if
you develop a job on one platform and implement it on another, you don’t necessarily have to change
your job design.

WebSphere DataStage learns about the shape and size of the system from the configuration file. It
organizes the resources needed for a job according to what is defined in the configuration file. When
your system changes, you change the file not the jobs.

This chapter describes how to define configuration files that specify what processing, storage, and sorting
facilities on your system should be used to run a parallel job. You can maintain multiple configuration
files and read them into the system according to your varying processing needs.

When you install WebSphere DataStage Enterprise Edition the system is automatically configured to use
the supplied default configuration file. This allows you to run parallel jobs right away, but is not
optimized for your system. Follow the instructions in this chapter to produce configuration file
specifically for your system.

Configurations editor
The WebSphere DataStage Designer provides a configuration file editor to help you define configuration
files for the parallel engine. To use the editor, choose Tools → Configurations, the Configurations dialog
box appears.

To define a new file, choose (New) from the Configurations drop-down list and type into the upper text
box. Guidance on the operation and format of a configuration file is given in the following sections. Click
Save to save the file at any point. You are asked to specify a configuration name, the config file is then
saved under that name with an .apt extension.

You can verify your file at any time by clicking Check. Verification information is output in the Check
Configuration Output pane at the bottom of the dialog box.

To edit an existing configuration file, choose it from the Configurations drop-down list. You can delete an
existing configuration by selecting it and clicking Delete. You are warned if you are attempting to delete
the last remaining configuration file.

You specify which configuration will be used by setting the APT_CONFIG_FILE environment variable.
This is set on installation to point to the default configuration file, but you can set it on a project wide
level from the WebSphere DataStage Administrator (see WebSphere DataStage Administrator Client Guide) or
for individual jobs from the Job Properties dialog.

Configuration considerations
The parallel engine’s view of your system is determined by the contents of your current configuration
file. Your file defines the processing nodes and disk space connected to each node that you allocate for
use by parallel jobs. When invoking a parallel job, the parallel engine first reads your configuration file to
determine what system resources are allocated to it and then distributes the job to those resources.

© Copyright IBM Corp. 2006 551

When you modify the system by adding or removing nodes or disks, you must modify your
configuration file correspondingly. Since the parallel engine reads the configuration file every time it runs
a parallel job, it automatically scales the application to fit the system without your having to alter the job
code.

Your ability to modify the parallel engine configuration means that you can control the parallelization of
a parallel job during its development cycle. For example, you can first run the job on one node, then on
two, then on four, and so on. You can measure system performance and scalability without altering
application code.

Logical processing nodes

A parallel engine configuration file defines one or more processing nodes on which your parallel job will
run. The processing nodes are logical rather than physical. The number of processing nodes does not
necessarily correspond to the number of CPUs in your system. Your configuration file can define one
processing node for each physical node in your system, or multiple processing nodes for each physical
node.

Optimizing parallelism
The degree of parallelism of a parallel job is determined by the number of nodes you define when you
configure the parallel engine. Parallelism should be optimized for your hardware rather than simply
maximized. Increasing parallelism distributes your work load but it also adds to your overhead because
the number of processes increases. Increased parallelism can actually hurt performance once you exceed
the capacity of your hardware. Therefore you must weigh the gains of added parallelism against the
potential losses in processing efficiency.

Obviously, the hardware that makes up your system influences the degree of parallelism you can
establish.

SMP systems allow you to scale up the number of CPUs and to run your parallel application against
more memory. In general, an SMP system can support multiple logical nodes. Some SMP systems allow
scalability of disk I/O. ″Configuration Options for an SMP″ discusses these considerations.

In a cluster or MPP environment, you can use the multiple CPUs and their associated memory and disk
resources in concert to tackle a single computing problem. In general, you have one logical node per CPU
on an MPP system. ″Configuration Options for an MPP System″ describes these issues.

The properties of your system’s hardware also determines configuration. For example, applications with
large memory requirements, such as sort operations, are best assigned to machines with a lot of memory.
Applications that will access an RDBMS must run on its server nodes; and stages using other proprietary
software, such as SAS, must run on nodes with licenses for that software.

Here are some additional factors that affect the optimal degree of parallelism:
v CPU-intensive applications, which typically perform multiple CPU-demanding operations on each
record, benefit from the greatest possible parallelism, up to the capacity supported by your system.
v Parallel jobs with large memory requirements can benefit from parallelism if they act on data that has
been partitioned and if the required memory is also divided among partitions.
v Applications that are disk- or I/O-intensive, such as those that extract data from and load data into
RDBMSs, benefit from configurations in which the number of logical nodes equals the number of disk
spindles being accessed. For example, if a table is fragmented 16 ways inside a database or if a data set
is spread across 16 disk drives, set up a node pool consisting of 16 processing nodes.
v For some jobs, especially those that are disk-intensive, you must sometimes configure your system to
prevent the RDBMS from having either to redistribute load data or to re-partition the data from an
extract operation.

552 Parallel Job Developer Guide

v The speed of communication among stages should be optimized by your configuration. For example,
jobs whose stages exchange large amounts of data should be assigned to nodes where stages
communicate by either shared memory (in an SMP environment) or a high-speed link (in an MPP
environment). The relative placement of jobs whose stages share small amounts of data is less
important.
v For SMPs, you may want to leave some processors for the operating system, especially if your
application has many stages in a job. See ″Configuration Options for an SMP″ .
v In an MPP environment, parallelization can be expected to improve the performance of CPU-limited,
memory-limited, or disk I/O-limited applications. See ″Configuration Options for an MPP System″ .

The most nearly-equal partitioning of data contributes to the best overall performance of a job run in
parallel. For example, when hash partitioning, try to ensure that the resulting partitions are evenly
populated.This is referred to as minimizing skew. Experience is the best teacher. Start with smaller data
sets and try different parallelizations while scaling up the data set sizes to collect performance statistics.

Configuration options for an SMP

An SMP contains multiple CPUs which share operating system, disk, and I/O resources. Data is
transported by means of shared memory. A number of factors contribute to the I/O scalability of your
SMP. These include the number of disk spindles, the presence or absence of RAID, the number of I/O
controllers, and the speed of the bus connecting the I/O system to memory.

SMP systems allow you to scale up the number of CPUs. Increasing the number of processors you use
may or may not improve job performance, however, depending on whether your application is CPU-,
memory-, or I/O-limited. If, for example, a job is CPU-limited, that is, the memory, memory bus, and
disk I/O of your hardware spend a disproportionate amount of time waiting for the CPU to finish its
work, it will benefit from being executed in parallel. Running your job on more processing units will
shorten the waiting time of other resources and thereby speed up the overall application.

All SMP systems allow you to increase your parallel job’s memory access bandwidth. However, none
allow you to increase the memory bus capacity beyond that of the hardware configuration. Therefore,
memory-intensive jobs will also benefit from increased parallelism, provided they do not saturate the
memory bus capacity of your system. If your application is already approaching, or at the memory bus
limit, increased parallelism will not provide performance improvement.

Some SMP systems allow scalability of disk I/O. In those systems, increasing parallelism can increase the
overall throughput rate of jobs that are disk I/O-limited.

For example, the following figure shows a data flow containing three parallel stages:

Chapter 54. The Parallel engine configuration file 553

 Stage 1

Stage 2

Stage 3

Data flow

For each stage in this data flow, the parallel engine creates a single UNIX process on each logical
processing node (provided that stage combining is not in effect). On an SMP defined as a single logical
node, each stage runs sequentially as a single process, and the parallel engine executes three processes in
total for this job. If the SMP has three or more CPUs, the three processes in the job can be executed
simultaneously by different CPUs. If the SMP has fewer than three CPUs, the processes must be
scheduled by the operating system for execution, and some or all of the processors must execute multiple
processes, preventing true simultaneous execution.

In order for an SMP to run parallel jobs, you configure the parallel engine to recognize the SMP as a
single or as multiple logical processing node(s), that is:

1 <= M <= N logical processing nodes

where N is the number of CPUs on the SMP and M is the number of processing nodes on the
configuration. (Although M can be greater than N when there are more disk spindles than there are
CPUs.)

As a rule of thumb, it is recommended that you create one processing node for every two CPUs in an
SMP. You can modify this configuration to determine the optimal configuration for your system and
application during application testing and evaluation. In fact, in most cases the scheduling performed by
the operating system allows for significantly more than one process per processor to be managed before
performance degradation is seen. The exact number depends on the nature of the processes, bus
bandwidth, caching effects, and other factors.

554 Parallel Job Developer Guide

Depending on the type of processing performed in your jobs (sorting, statistical analysis, database I/O),
different configurations may be preferable.

For example, on an SMP viewed as a single logical processing node, the parallel engine creates a single
UNIX process on the processing node for each stage in a data flow. The operating system on the SMP
schedules the processes to assign each process to an individual CPU.

If the number of processes is less than the number of CPUs, some CPUs may be idle. For jobs containing
many stages, the number of processes may exceed the number of CPUs. If so, the processes will be
scheduled by the operating system.

Suppose you want to configure the parallel engine to recognize an eight-CPU SMP, for example, as two
or more processing nodes. When you configure the SMP as two separate processing nodes, the parallel
engine creates two processes per stage on the SMP. For the three-stage job shown above, configuring an
SMP as more than two parallel engine processing nodes creates at least nine UNIX processes, although
only eight CPUs are available. Process execution must be scheduled by the operating system.

For that reason, configuring the SMP as three or more parallel engine processing nodes can conceivably
degrade performance as compared with that of a one- or two-processing node configuration. This is so
because each CPU in the SMP shares memory, I/O, and network resources with the others. However, this
is not necessarily true if some stages read from and write to disk or the network; in that case, other
processes can use the CPU while the I/O-bound processes are blocked waiting for operations to finish.

Example Configuration File for an SMP

This section contains a sample configuration file for the four-CPU SMP shown below:

CPU CPU

CPU CPU

The table below lists the processing node names and the file systems used by each processing node for
both permanent and temporary storage in this example system:

Node name on fast Directory for Directory for temp

Node name network Node pools permanent storage storage

node0 node0_byn "", node0, /orch/s0 /scratch

node0_fddi /orch/s1

node1 node0_byn "", node1, /orch/s0 /scratch

node1_fddi /orch/s1

Chapter 54. The Parallel engine configuration file 555

The table above also contains a column for node pool definitions. Node pools allow you to execute a
parallel job or selected stages on only the nodes in the pool. See ″Node Pools and the Default Node Pool″
for more details.

In this example, the parallel engine processing nodes share two file systems for permanent storage. The
nodes also share a local file system (/scratch) for temporary storage.

Here is the configuration file corresponding to this system. ″Configuration Files″ discusses the keywords
and syntax of configuration files.
{
node "node0" {
fastname "node0_byn" /* node name on a fast network */
pools "" "node0" "node0_fddi" /* node pools */
resource disk "/orch/s0" {}
resource disk "/orch/s1" {}
resource scratchdisk "/scratch" {}
}
node "node1" {
fastname "node0_byn"
pools "" "node1" "node1_fddi"
resource disk "/orch/s0" {}
resource disk "/orch/s1" {}
resource scratchdisk "/scratch" {}
}
}

Configuration options for an MPP system

An MPP consists of multiple hosts, where each host runs its own image of the operating system and
contains its own processors, disk, I/O resources, and memory. This is also called a shared-nothing
environment. Each host in the system is connected to all others by a high-speed network. A host is also
referred to as a physical node.

In an MPP environment, you can use the multiple CPUs and their associated memory and disk resources
in concert. In this environment, each CPU has its own dedicated memory, memory bus, disk, and disk
access.

When configuring an MPP, you specify the physical nodes in your system on which the parallel engine
will run your parallel jobs. You do not have to specify all nodes.

556 Parallel Job Developer Guide

An Example of a four-node MPP system configuration
The following figure shows a sample MPP system containing four physical nodes:

high-speed network (switch)

node0_css node2_css

CPU CPU

node0 node2

node1_css node3_css

CPU CPU

node1 node3

Ethernet

This figure shows a disk-everywhere configuration. Each node is connected to both a high-speed switch
and an Ethernet. Note that the configuration information below for this MPP would be similar for a
cluster of four SMPs connected by a network.

The following table shows the storage local to each node:

Chapter 54. The Parallel engine configuration file 557

 Node name on fast Directory for Directory for temp
Node name network Node pools permanent storage storage

node0 node0_css "", node0, node0_css /orch/s0 /orch/s1 /scratch

node1 node1_css "", node1, /orch/s0 /scratch

node1_css /orch/s1

node2 node2_css "", node2, /orch/s0 /scratch

node2_css /orch/s1

node3 node3_css "", node3, /orch/s0 /scratch

node3_css /orch/s1

Note that because this is an MPP system, each node in this configuration has its own disks and hence its
own /orch/s0, /orch/s1, and /scratch. If this were an SMP, the logical nodes would be sharing the same
directories.

Here is the configuration file for this sample system. ″Configuration Files″ discusses the keywords and
syntax of configuration files.
{
node "node0" {
fastname "node0_css" /* node name on a fast network*/
pools "" "node0" "node0_css" /* node pools */
resource disk "/orch/s0" {}
resource disk "/orch/s1" {}
resource scratchdisk "/scratch" {}
}
node "node1" {
fastname "node1_css"
pools "" "node1" "node1_css"
resource disk "/orch/s0" {}
resource disk "/orch/s1" {}
resource scratchdisk "/scratch" {}
}
node "node2" {
fastname "node2_css"
pools "" "node2" "node2_css"
resource disk "/orch/s0" {}
resource disk "/orch/s1" {}
resource scratchdisk "/scratch" {}
}
node "node3" {
fastname "node3_css"
pools "" "node3" "node3_css"
resource disk "/orch/s0" {}
resource disk "/orch/s1" {}
resource scratchdisk "/scratch" {}
}
}

Configuration options for an SMP cluster

An SMP cluster consists of one or more SMPs and, optionally, single-CPU nodes connected by a
high-speed network. In this case, each SMP in the cluster is referred to as a physical node. When you
configure your system, you can divide a physical node into logical nodes. The following figure shows a
cluster containing four physical nodes, one of which (node1) is an SMP containing two CPUs.

558 Parallel Job Developer Guide

 high-speed network (switch)

node0_css node2_css

CPU CPU

node0 node2

node1_css node3_css

CPU

CPU
CPU

node1 node3

Ethernet

An example of an SMP cluster configuration

The following configuration file divides physical node1 into logical nodes node1 and node1a. Both are
connected to the high-speed switch by the same fastname; in the configuration file, the same fastname is
specified for both nodes. ″Configuration Files″ discusses the keywords and syntax of configuration files.
{
node "node0" {
fastname "node0_css" /* node name on a fast network */
pools "" "node0" "node0_css" /* node pools */
resource disk "/orch/s0" {}
resource disk "/orch/s1" {}
resource scratchdisk "/scratch" {}
}

node "node1" {

Chapter 54. The Parallel engine configuration file 559

 fastname "node1_css"
pools "" "node1" "node1_css"
resource disk "/orch/s0" {}
resource disk "/orch/s1" {}
resource scratchdisk "/scratch" {}
}
node "node1a" {
fastname "node1_css"
pools "" "node1" "node1_css"
resource disk "/orch/s0" {}
resource disk "/orch/s1" {}
resource scratchdisk "/scratch" {}
}
node "node2" {
fastname "node2_css"
pools "" "node2" "node2_css"
resource disk "/orch/s0" {}
resource disk "/orch/s1" {}
resource scratchdisk "/scratch" {}
}
node "node3" {
fastname "node3_css"
pools "" "node3" "node3_css"
resource disk "/orch/s0" {}
resource disk "/orch/s1" {}
resource scratchdisk "/scratch" {}
}
}

In this example, consider the disk definitions for /orch/s0. Since node1 and node1a are logical nodes of
the same physical node, they share access to that disk. Each of the remaining nodes, node0, node2, and
node3, has its own /orch/s0 that is not shared. That is, there are four distinct disks called /orch/s0.
Similarly, /orch/s1 and /scratch are shared between node1 and node1a but not the others.

Options for a cluster with the conductor unconnected to the

high-speed switch
The parallel engine starts your parallel job from the Conductor node.

A cluster may have a node that is not connected to the others by a high-speed switch, as in the following
figure.

560 Parallel Job Developer Guide

 high-speed network (switch)

node0_css node2_css

CPU CPU

node0 node2

node1_css node3_css

CPU

CPU
CPU

node1 node3

Ethernet

CPU

Node4

In this example, node4 is the Conductor, which is the node from which you need to start your
application. By default, the parallel engine communicates between nodes using the fastname, which in
this example refers to the high-speed switch. But because the Conductor is not on that switch, it cannot
use the fastname to reach the other nodes.

Therefore, to enable the Conductor node to communicate with the other nodes, you need to identify each
node on the high-speed switch by its canonicalhostname and give its Ethernet name as its quoted
attribute, as in the following configuration file. ″Configuration Files″ discusses the keywords and syntax
of configuration files.

Chapter 54. The Parallel engine configuration file 561

{ node "node0" {
fastname "node0_css"
resource canonicalhostname "node1-eth-1"
pools "" "node0" "node0_css"
resource disk "/orch/s0" {}
resource disk "/orch/s1" {}
resource scratchdisk "/scratch" {}
}
node "node1" {
fastname "node1_css"
resource canonicalhostname "node1-eth-1"
pools "" "node1" "node1_css"
resource disk "/orch/s0" {}
resource disk "/orch/s1" {}
resource scratchdisk "/scratch" {}
}
node "node2" {
fastname "node2_css"
resource canonicalhostname "node1-eth-1"
pools "" "node2" "node2_css"
resource disk "/orch/s0" {}
resource disk "/orch/s1" {}
resource scratchdisk "/scratch" {}
}
node "node3" {
fastname "node3_css"
resource canonicalhostname "node1-eth-1"
pools "" "node3" "node3_css"
resource disk "/orch/s0" {}
resource disk "/orch/s1" {}
resource scratchdisk "/scratch" {}
}
node "node4" {
pools "" "conductor" "node4" "node4_css"
/* not in the default pool */
resource disk "/orch/s0" {}
resource disk "/orch/s1" {}
resource scratchdisk "/scratch" {}
}
}

Note: Since node4 is not on the high-speed switch and we are therefore using it only as the Conductor
node, we have left it out of the default node pool (″″). This causes the parallel engine to avoid
placing stages on node4. See ″Node Pools and the Default Node Pool″ .

Diagram of a cluster environment

The following figure shows a mixed MPP and SMP cluster environment containing six physical nodes.
Only the four nodes of the left are intended to be allocated for use by the parallel engine.

562 Parallel Job Developer Guide

 high-speed network (switch)

CPU CPU CPU CPU

CPU

CPU

CPU CPU

CPU CPU

Parallel engine processing

Configuration files
This section describes parallel engine configuration files, and their uses and syntax. The parallel engine
reads a configuration file to ascertain what processing and storage resources belong to your system.
Processing resources include nodes; and storage resources include both disks for the permanent storage
of data and disks for the temporary storage of data (scratch disks). The parallel engine uses this
information to determine, among other things, how to arrange resources for parallel execution.

You must define each processing node on which the parallel engine runs jobs and qualify its
characteristics; you must do the same for each disk that will store data. You can specify additional
information about nodes and disks on which facilities such as sorting or SAS operations will be run, and
about the nodes on which to run stages that access the following relational data base management
systems: DB2, INFORMIX, and Oracle.

You can maintain multiple configuration files and read them into the system according to your needs.

A sample configuration file is located in Configurations directory under the Server directory of your
installation, and is called default.apt..

Chapter 54. The Parallel engine configuration file 563

This section contains the following subsections:
v ″The Default Path Name and the APT_CONFIG_FILE″
v ″Syntax″
v ″Node Names″
v ″Options″
v ″Node Pools and the Default Node Pool″
v ″Disk and Scratch Disk Pools and Their Defaults″
v ″Buffer Scratch Disk Pools″

The default path name and the APT_CONFIG_FILE

The default name of the configuration file is default.apt and it is located in the Configurations directory
in the Server directory of your installation

You can give the configuration file a different name or location or both from their defaults. If you do,
assign the new path and file name to the environment variable APT_CONFIG_FILE. If
APT_CONFIG_FILE is defined, the parallel engine uses that configuration file rather than searching in
the default locations. In a production environment, you can define multiple configurations and set
APT_CONFIG_FILE to different path names depending on which configuration you want to use.

You can set APT_CONFIG_FILE on a project wide level from the WebSphere DataStage Administrator
(see WebSphere DataStage Administrator Client Guide) or for individual jobs from the Job Properties dialog.

Note: Although the parallel engine may have been copied to all processing nodes, you need to copy the
configuration file only to the nodes from which you start parallel engine applications (conductor
nodes).

Syntax
Configuration files are text files containing string data. The general form of a configuration file is as
follows:
/* commentary */
{
node "node name" {
<node information>
.
.
.
}
.
.
.
}

These are the syntactic characteristics of configuration files:

v Braces { } begin and end the file.
v The word node begins every node definition.
v The word node is followed by the name of the node enclosed in quotation marks. For a detailed
discussion of node names, see ″Node Names″ .
v Braces { } follow the node name. They enclose the information about the node (its options), including
an enumeration of each disk and scratch disk resource. The legal options are: fastname, pools, and
resource.
v Spaces separate items.
v Quotation (") marks surround the attributes you assign to options, that is, the names of nodes, disks,
scratch disks, and pools.

564 Parallel Job Developer Guide

v Comments are demarcated by /* . . . */, in the style of the C programming language. They are
optional, but are recommended where indicated in the examples.

Node names
Each node you define is followed by its name enclosed in quotation marks, for example:
node "orch0"

For a single CPU node or workstation, the node’s name is typically the network name of a processing
node on a connection such as a high-speed switch or Ethernet. Issue the following UNIX command to
learn a node’s network name:
$ uname -n

On an SMP, if you are defining multiple logical nodes corresponding to the same physical node, you
replace the network name with a logical node name. In this case, you need a fast name for each logical
node.

If you run an application from a node that is undefined in the corresponding configuration file, each user
must set the environment variable APT_PM_CONDUCTOR_NODENAME to the fast name of the node
invoking the parallel job.

Options
Each node takes options that define the groups to which it belongs and the storage resources it employs.
Options are as follows:

fastname
Syntax:
fastname "name"

This option takes as its quoted attribute the name of the node as it is referred to on the fastest network in
the system, such as an IBM switch, FDDI, or BYNET. The fastname is the physical node name that stages
use to open connections for high volume data transfers. The attribute of this option is often the network
name. For an SMP, all CPUs share a single connection to the network, and this setting is the same for all
parallel engine processing nodes defined for an SMP. Typically, this is the principal node name, as
returned by the UNIX command uname -n.

pools
Syntax:
pools "node_pool_name0" "node_pool_name1" ...

The pools option indicates the names of the pools to which this node is assigned. The option’s attribute is
the pool name or a space-separated list of names, each enclosed in quotation marks. For a detailed
discussion of node pools, see ″Node Pools and the Default Node Pool″ .

Note that the resource disk and resource scratchdisk options can also take pools as an option, where it
indicates disk or scratch disk pools. For a detailed discussion of disk and scratch disk pools, see ″Disk
and Scratch Disk Pools and Their Defaults″ .

Node pool names can be dedicated. Reserved node pool names include the following names:
DB2 See the DB2 resource below and ″The resource DB2 Option″ .
INFORMIX
See the INFORMIX resource below and ″The resource INFORMIX Option″ .
ORACLE See the ORACLE resource below and ″The resource ORACLE option″ .

Chapter 54. The Parallel engine configuration file 565

sas See ″The SAS Resources″ .
sort See ″Sort Configuration″ .

Reserved disk pool names include the following names:

See ″Buffer Scratch Disk Pools″ .
export For use by the export stage.
lookup For use by the lookup stage.
sasdataset
See ″The SAS Resources″ .
sort See ″Sort Configuration″ .

resource
Syntax:
resource resource_type "location" [{pools "disk_pool_name"}] |
resource resource_type "value"

The resource_type can be one of the following:

canonicalhostname
Syntax:
canonicalhostname "ethernet name"

The canonicalhostname resource takes as its quoted attribute the ethernet name of a node in a cluster that
is unconnected to the Conductor node by the high-speed network. If the Conductor node cannot reach
the unconnected node by a fastname, you must define the unconnected node’s canonicalhostname to
enable communication.

DB2
Syntax:
resource DB2 "node_number" [{pools "instance_owner" ...}]

This option allows you to specify logical names as the names of DB2 nodes. For a detailed discussion of
configuring DB2, see ″The resource DB2 Option″ .

disk
Syntax:
resource disk "directory_path"
[{pools "poolname"...}]

Assign to this option the quoted absolute path name of a directory belonging to a file system connected
to the node. The node reads persistent data from and writes persistent data to this directory. One node
can have multiple disks. Relative path names are not supported.

Typically, the quoted name is the root directory of a file system, but it does not have to be. For example,
the quoted name you assign to disk can be a subdirectory of the file system.

You can group disks in pools. Indicate the pools to which a disk belongs by following its quoted name
with a pools definition enclosed in braces. For a detailed discussion of disk pools, see ″Disk and Scratch
Disk Pools and Their Defaults″ .

INFORMIX

566 Parallel Job Developer Guide

Syntax:
resource INFORMIX "coserver_basename" [{pools "db_server_name" ... }]

This option allows you to specify logical names as the names of INFORMIX nodes. For a detailed
discussion of configuring INFORMIX, see ″The resource INFORMIX Option″ .

ORACLE
Syntax:
resource ORACLE "nodename"
[{pools "db_server_name" ...}]

This option allows you to define the nodes on which Oracle runs. For a detailed discussion of
configuring Oracle, see ″The resource ORACLE option″ .

sasworkdisk
Syntax:
resource sasworkdisk "directory_path"
[{pools "poolname"...}]

This option is used to specify the path to your SAS work directory. See ″The SAS Resources″ .

scratchdisk
Syntax:
resource scratchdisk "directory_path"
[{pools "poolname"...}]

Assign to this option the quoted absolute path name of a directory on a file system where intermediate
data will be temporarily stored. All users of this configuration must be able to read from and write to this
directory. Relative path names are unsupported.

The directory should be local to the processing node and reside on a different spindle from that of any
other disk space. One node can have multiple scratch disks.

Assign at least 500 MB of scratch disk space to each defined node. Nodes should have roughly equal
scratch space. If you perform sorting operations, your scratch disk space requirements can be
considerably greater, depending upon anticipated use.

We recommend that:
v Every logical node in the configuration file that will run sorting operations have its own sort disk,
where a sort disk is defined as a scratch disk available for sorting that resides in either the sort or
default disk pool.
v Each logical node’s sorting disk be a distinct disk drive. Alternatively, if it is shared among multiple
sorting nodes, it should be striped to ensure better performance.
v For large sorting operations, each node that performs sorting have multiple distinct sort disks on
distinct drives, or striped.

You can group scratch disks in pools. Indicate the pools to which a scratch disk belongs by following its
quoted name with a pools definition enclosed in braces. For more information on disk pools, see ″Disk
and Scratch Disk Pools and Their Defaults″ .

The following sample SMP configuration file defines four logical nodes.
{
node "borodin0" {
fastname "borodin"
pools "compute_1" ""

Chapter 54. The Parallel engine configuration file 567

 resource disk "/sfiles/node0" {pools ""}
resource scratchdisk "/scratch0" {pools "" "sort"}
}
node "borodin1" {
fastname "borodin"
pools "compute_1" ""
resource disk "/sfiles/node1" {pools ""}
resource scratchdisk "/scratch1" {pools "" "sort"}
}
node "borodin2" {
fastname "borodin"
pools "compute_1" ""
resource disk "/sfiles/node2" {pools ""}
resource scratchdisk "/scratch2" {pools "" "sort"}
}
node "borodin3"
{
fastname "borodin"
pools "compute_1" ""
resource disk "/sfiles/node3" {pools ""}
resource scratchdisk "/scratch3" {pools "" "sort"}
}
}

In the example shown above:

v All nodes are elements of pool compute_1 and the default node pool, indicated by ″″.
v The resource disk of node borodin0 is the directory /sfiles/node0.
v The resource disks of nodes borodin1 to borodin3 are the directories /sfiles/node1, /sfiles/node2, and
/sfiles/node3.
v All resource disks are elements of the default disk pool, indicated by ″″.
v For sorting, each logical node has its own scratch disk.
v All scratch disks are elements of the sort scratch disk pool and the default scratch disk pool which is
indicated by ″″.

Node pools and the default node pool

Node pools allow association of processing nodes based on their characteristics. For example, certain
nodes can have large amounts of physical memory, and you can designate them as compute nodes.
Others can connect directly to a mainframe or some form of high-speed I/O. These nodes can be grouped
into an I/O node pool.

The option pools is followed by the quoted names of the node pools to which the node belongs. A node
can be assigned to multiple pools, as in the following example, where node1 is assigned to the default
pool (″″) as well as the pools node1, node1_css, and pool4.
node "node1"
{
fastname "node1_css"
pools "" "node1" "node1_css" "pool4"
resource disk "/orch/s0" {}
resource scratchdisk "/scratch" {}
}

A node belongs to the default pool unless you explicitly specify a pools list for it, and omit the default
pool name (″″) from the list.

Once you have defined a node pool, you can constrain a parallel stage or parallel job to run only on that
pool, that is, only on the processing nodes belonging to it. If you constrain both an stage and a job, the
stage runs only on the nodes that appear in both pools.

Nodes or resources that name a pool declare their membership in that pool.
568 Parallel Job Developer Guide
We suggest that when you initially configure your system you place all nodes in pools that are named
after the node’s name and fast name. Additionally include the default node pool in this pool, as in the
following example:
node "n1"
{
fastname "nfast"
pools "" "n1" "nfast"
}

By default, the parallel engine executes a parallel stage on all nodes defined in the default node pool. You
can constrain the processing nodes used by the parallel engine either by removing node descriptions from
the configuration file or by constraining a job or stage to a particular node pool.

Disk and scratch disk pools and their defaults

When you define a processing node, you can specify the options resource disk and resource scratchdisk.
They indicate the directories of file systems available to the node. You can also group disks and scratch
disks in pools. Pools reserve storage for a particular use, such as holding very large data sets. The syntax
for setting up disk and scratch disk pools is as follows:
resource disk "disk_name"
{pools "disk_pool0" ... "disk_poolN"}
resource scratchdisk "s_disk_name"
{pools "s_pool0" ... "s_poolN"}

where:
v disk_name and s_disk_name are the names of directories.
v disk_pool... and s_pool... are the names of disk and scratch disk pools, respectively.

Pools defined by disk and scratchdisk are not combined; therefore, two pools that have the same name
and belong to both resource disk and resource scratchdisk define two separate pools.

A disk that does not specify a pool is assigned to the default pool. The default pool may also be
identified by ″″ by and { } (the empty pool list). For example, the following code configures the disks for
node1:
node "node1" {
resource disk "/orch/s0" {pools "" "pool1"}
resource disk "/orch/s1" {pools "" "pool1"}
resource disk "/orch/s2" { } /* empty pool list */
resource disk "/orch/s3" {pools "pool2"}
resource scratchdisk "/scratch" {pools "" "scratch_pool1"}
}

In this example:
v The first two disks are assigned to the default pool.
v The first two disks are assigned to pool1.
v The third disk is also assigned to the default pool, indicated by { }.
v The fourth disk is assigned to pool2 and is not assigned to the default pool.
v The scratch disk is assigned to the default scratch disk pool and to scratch_pool1.

Application programmers make use of pools based on their knowledge of both their system and their
application.

Chapter 54. The Parallel engine configuration file 569

Buffer scratch disk pools
Under certain circumstances, the parallel engine uses both memory and disk storage to buffer virtual data
set records.The amount of memory defaults to 3 MB per buffer per processing node. The amount of disk
space for each processing node defaults to the amount of available disk space specified in the default
scratchdisk setting for the node.

The parallel engine uses the default scratch disk for temporary storage other than buffering. If you define
a buffer scratch disk pool for a node in the configuration file, the parallel engine uses that scratch disk
pool rather than the default scratch disk for buffering, and all other scratch disk pools defined are used
for temporary storage other than buffering.

Here is an example configuration file that defines a buffer scratch disk pool:
{
node node1 {
fastname "node1_css"
pools "" "node1" "node1_css"
resource disk "/orch/s0" {}
resource scratchdisk "/scratch0" {pools "buffer"}
resource scratchdisk "/scratch1" {}
}
node node2 {
fastname "node2_css"
pools "" "node2" "node2_css"
resource disk "/orch/s0" {}
resource scratchdisk "/scratch0" {pools "buffer"}
resource scratchdisk "/scratch1" {}
}
}

In this example, each processing node has a single scratch disk resource in the buffer pool, so buffering
will use /scratch0 but not /scratch1. However, if /scratch0 were not in the buffer pool, both /scratch0
and /scratch1 would be used because both would then be in the default pool.

The resource DB2 option

The DB2 file db2nodes.cfg contains information for translating DB2 node numbers to node names. You
must define the node names specified in db2nodes.cfg in your configuration file, if you want the parallel
engine to communicate with DB2. You can designate each node specified in db2nodes.cfg in one of the
following ways:
v By assigning to node its quoted network name, as returned by the UNIX operating system command
uname -n; for example, node ″node4″.
v By assigning to node a logical name, for example ″DB2Node3″. If you do so, you must specify the
option resource DB2 followed by the node number assigned to the node in db2nodes.cfg.

The resource DB2 option can also take the pools option. You assign to it the user name of the owner of
each DB2 instance configured to run on each node. DB2 uses the instance to determine the location of
db2nodes.cfg.

Here is a sample DB2 configuration:

{
node "Db2Node0" {
/* other configuration parameters for node0 */
resource DB2 "0" {pools "Mary" "Tom"}
}
node "Db2Node1" {
/* other configuration parameters for node1 */
resource DB2 "1" {pools "Mary" "Tom"}
}
node "Db2Node2" {

570 Parallel Job Developer Guide

 /* other configuration parameters for node2 */
resource DB2 "2" {pools "Mary" "Tom" "Bill"}
}

node "Db2Node3" {
/* other configuration parameters for node3 */
resource DB2 "3" {pools "Mary" "Bill"}
}

/* other nodes used by the parallel engine*/

In the example above:

v The resource DB2 option takes the DB2 node number corresponding to the processing node.
v All nodes are used with the DB2 instance Mary.
v Nodes 0, 1, and 2 are used with the DB2 instance Tom.
v Nodes 2 and 3 are used with the DB2 instance Bill.

If you now specify a DB2 instance of Mary in your jobs, the location of db2nodes.cfg is
~Mary/sqllib/db2nodes.cfg.

The resource INFORMIX option

To communicate with INFORMIX, the parallel engine must be configured to run on all processing nodes
functioning as INFORMIX coservers. This means that the configuration must include a node definition for
the coserver nodes. The list of INFORMIX coservers is contained in the file pointed to by the
environment variable $INFORMIXSQLHOSTS or in the file $INFORMIXDIR/etc/sqlhosts.

There are two methods for specifying the INFORMIX coserver names in the configuration file.
1. Your configuration file can contain a description of each node, supplying the node name (not a
synonym) as the quoted name of the node. Typically, the node name is the network name of a
processing node as returned by the UNIX command uname -n.
Here is a sample configuration file for a system containing INFORMIX coserver nodes node0, node1,
node2, and node3:
{
node "node0" {
/* configuration parameters for node0 */
}
node "node1" {
/* configuration parameters for node1 */
}
node "node2" {
/* configuration parameters for node2 */
}
node "node3" {
/* configuration parameters for node3 */
}

/* other nodes used by the parallel engine*/

}
1. You can supply a logical rather than a real network name as the quoted name of node. If you do so,
you must specify the resource INFORMIX option followed by the name of the corresponding
INFORMIX coserver.
Here is a sample INFORMIX configuration:
{
node "IFXNode0" {
/* other configuration parameters for node0 */

Chapter 54. The Parallel engine configuration file 571

 resource INFORMIX "node0" {pools "server"}
}
node "IFXNode1" {
/* other configuration parameters for node1 */
resource INFORMIX "node1" {pools "server"}
}
node "IFXNode2" {
/* other configuration parameters for node2 */
resource INFORMIX "node2" {pools "server"}
}
node "IFXNode3" {
/* other configuration parameters for node3 */
resource INFORMIX "node3" {pools "server"}
}

/* other nodes used by the parallel engine*/

}

When you specify resource INFORMIX, you must also specify the pools parameter. It indicates the base
name of the coserver groups for each INFORMIX server. These names must correspond to the coserver
group base name using the shared-memory protocol. They also typically correspond to the
DBSERVERNAME setting in the ONCONFIG file. For example, coservers in the group server are typically
named server.1, server.2, and so on.

The resource ORACLE option

By default, the parallel engine executes Oracle stages on all processing nodes belonging to the default
node pool, which typically corresponds to all defined nodes.

You can optionally specify the resource ORACLE option to define the nodes on which you want to run
the Oracle stages. If you do, the parallel engine runs the Oracle stages only on the processing nodes for
which resource ORACLE is defined. You can additionally specify the pools parameter of resource
ORACLE to define resource pools, which are groupings of Oracle nodes.

Here is a sample Oracle configuration:

{
node "node0" {
/* other configuration parameters for node0 */
resource ORACLE "node0" {pools "group1" "group2" "group3"}
}
node "node1" {
/* other configuration parameters for node1 */
resource ORACLE "node1" {pools "group1" "group2"}
}
node "node2" {
/* other configuration parameters for node2 */
resource ORACLE "node2" {pools "group1" "group3"}
}
node "node3" {
/* other configuration parameters for node3 */
resource ORACLE "node3" {pools "group1" "group2" "group3"}
}

/* any other nodes used by the parallel engine*/

}

In the example above, Oracle runs on node0 to node3.

v node0-node3 are used with node pool group1.
v node0, node1, and node3 are used with node pool group2.
v node0, node2, and node3 are used with node pool group3.

572 Parallel Job Developer Guide

The SAS resources

Adding SAS information to your configuration file

To configure your system to use the SAS stage, you need to specify the following information in your
configuration file:
v The location of the SAS executable, if it is not in your PATH;
v An SAS work disk directory, one for each parallel engine node;
v Optionally, a disk pool specifically for parallel SAS data sets, called sasdataset.

The resource names sas and sasworkdisk and the disk pool name sasdataset are all reserved words. Here
is an example of each of these declarations:
resource sas "/usr/sas612/" { }
resource sasworkdisk "/usr/sas/work/" { }
resource disk "/data/sas/" {pools "" "sasdataset"}

While the disks designated as sasworkdisk need not be a RAID configuration, best performance will
result if each parallel engine logical node has its own reserved disk that is not shared with other parallel
engine nodes during sorting and merging. The total size of this space for all nodes should optimally be
equal to the total work space you use when running SAS sequentially (or a bit more, to allow for uneven
distribution of data across partitions).

The number of disks in the sasdataset disk pool is the degree of parallelism of parallel SAS data sets.
Thus if you have 24 processing nodes, each with its associated disk in the sasdataset disk pool, parallel
SAS data sets will be partitioned among all 24 disks, even if the operation preceding the disk write is, for
example, only four-way parallel.

Example
Here a single node, grappelli0, is defined, along with its fast name. Also defined are the path to a SAS
executable, a SAS work disk (corresponding to the SAS work directory), and two disk resources, one for
parallel SAS data sets and one for non-SAS file sets.
node "grappelli0"
{
fastname "grappelli"
pools "" "a"
resource sas "/usr/sas612" { }
resource scratchdisk "/scratch" { }
resource sasworkdisk "/scratch" { }
disk "/data/pds_files/node0" { pools "" "export" }
disk "/data/pds_files/sas" { pools "" "sasdataset" }
}

Sort configuration
You may want to define a sort scratch disk pool to assign scratch disk space explicitly for the storage of
temporary files created by the Sort stage. In addition, if only a subset of the nodes in your configuration
have sort scratch disks defined, we recommend that you define a sort node pool, to specify the nodes on
which the sort stage should run. Nodes assigned to the sort node pool should be those that have scratch
disk space assigned to the sort scratch disk pool.

The parallel engine then runs sort only on the nodes in the sort node pool, if it is defined, and otherwise
uses the default node pool. The Sort stage stores temporary files only on the scratch disks included in the
sort scratch disk pool, if any are defined, and otherwise uses the default scratch disk pool.

Chapter 54. The Parallel engine configuration file 573

When the parallel engine runs, it determines the locations of temporary files by:
1. Searching the parallel engine configuration for any scratch disk resources in the sort resource pool on
the nodes sort will run on. If found, the scratch disks are used as a location for temporary storage by
sort.
2. If no scratch disk resources are found that belong to the disk pool sort, the system determines
whether any scratch disk resources belong to the default scratch disk pool on the nodes sort will run
on. If so, the scratch disks belonging to the default pool are used by tsort for temporary storage.
3. If no scratch disk resources are found that belong to either sort or the default scratch disk pool, the
parallel engine issues a warning message and runs sort using the directory indicated by the TMPDIR
environment variable or /tmp for temporary storage.

Allocation of resources
The allocation of resources for a given stage, particularly node and disk allocation, is done in a
multi-phase process. Constraints on which nodes and disk resources are used are taken from the parallel
engine arguments, if any, and matched against any pools defined in the configuration file. Additional
constraints may be imposed by, for example, an explicit requirement for the same degree of parallelism as
the previous stage. After all relevant constraints have been applied, the stage allocates resources,
including instantiation of Player processes on the nodes that are still available and allocation of disks to
be used for temporary and permanent storage of data.

Selective configuration with startup scripts

As part of running an application, the parallel engine creates a remote shell on all parallel engine
processing nodes on which the application will be executed. After the parallel engine creates the remote
shell, it copies the environment from the system on which the application was invoked to each remote
shell. This means that all remote shells have the same configuration by default.

However, you can override the default and set configuration parameters for individual processing nodes.
To do so, you create a parallel engine startup script. If a startup script exists, the parallel engine runs it
on all remote shells before it runs your application.

When you invoke an application, the parallel engine looks for the name and location of a startup script
as follows:
1. It uses the value of the APT_STARTUP_SCRIPT environment variable.
2. It searches the current working directory for a file named startup.apt.
3. Searches for the file install_dir/etc/startup.apt on the system that invoked the parallel engine
application, where install_dir is the top-level directory of the installation.
4. If the script is not found, it does not execute a startup script.

Here is a template you can use with Korn shell to write your own startup script.
#!/bin/ksh # specify Korn shell
# your shell commands go here

shift 2 # required for all shells

exec $* # required for all shells

You must include the last two lines of the shell script. This prevents your application from running if
your shell script detects an error.

The following startup script for the Bourne shell prints the node name, time, and date for all processing
nodes before your application is run:

574 Parallel Job Developer Guide

 #!/bin/sh # specify Bourne shell

echo `hostname` `date`

shift 2
exec $*

A single script can perform node-specific initialization by means of a case statement. In the following
example, the system has two nodes named node1 and node2. This script performs initialization based on
which node it is running on.
#!/bin/sh # use Bourne shell

# Example APT startup script.

case `hostname` in
node1)
# perform node1 init
node-specific directives ;;
node2)
# perform node2 init
node-specific directives ;;
esac
shift 2
exec $*

The parallel engine provides the APT_NO_STARTUP_SCRIPT environment variable to prevent the
parallel engine from running the startup script. By default, the parallel engine executes the startup script.
If the variable is set, the parallel engine ignores the startup script. This can be useful for debugging a
startup script.

Hints and tips

The configuration file tells the engine how to exploit the underlying computer system. For a given system
there is not necessarily one ideal configuration file because of the high variability between the way
different jobs work. So where do you start?

Let’s assume you are running on a shared-memory multi-processor system, i.e., an SMP box (these are
the most common platforms today). Let’s assume these properties. You can adjust the illustration below
to match your precise situation:
v computer’s hostname ″fastone″
v 6 CPUs
v 4 separate file systems on 4 drives named /fs0 /fs1 /fs2 /fs3

The configuration file to use as a starting point would look like the one below. Note the way the
disk/scratchdisk resources are handled. That’s the real trick here.
{ /* config file allows C-style comments. */
/*
config files look like they have flexible syntax.
They do NOT. Keep all the sub-items of the individual
node specifications in the order shown here.
*/
node "n0" {
pools "" /* on an SMP node pools aren’t used often. */
fastname "fastone"
resource scratchdisk "/fs0/ds/scratch" {} /*start with fs0*/
resource scratchdisk "/fs1/ds/scratch" {}
resource scratchdisk "/fs2/ds/scratch" {}
resource scratchdisk "/fs3/ds/scratch" {}
resource disk "/fs0/ds/disk" {} /* start with fs0 */
resource disk "/fs1/ds/disk" {}
resource disk "/fs2/ds/disk" {}
resource disk "/fs3/ds/disk" {}

Chapter 54. The Parallel engine configuration file 575

}
node "n1" {pools ""
fastname "fastone"
resource scratchdisk "/fs1/ds/scratch" {} /*start with fs1*/
resource scratchdisk "/fs2/ds/scratch" {}
resource scratchdisk "/fs3/ds/scratch" {}
resource scratchdisk "/fs0/ds/scratch" {}
resource disk "/fs1/ds/disk" {} /* start with fs1 */
resource disk "/fs2/ds/disk" {}
resource disk "/fs3/ds/disk" {}
resource disk "/fs0/ds/disk" {}
}
node "n2" {
pools ""
fastname "fastone"
resource scratchdisk "/fs2/ds/scratch" {} /*start with fs2*/
resource scratchdisk "/fs3/ds/scratch" {}
resource scratchdisk "/fs0/ds/scratch" {}
resource scratchdisk "/fs1/ds/scratch" {}
resource disk "/fs2/ds/disk" {} /* start with fs2 */
resource disk "/fs3/ds/disk" {}
resource disk "/fs0/ds/disk" {}
resource disk "/fs1/ds/disk" {}
}
node "n3" {
pools ""
fastname "fastone"
resource scratchdisk "/fs3/ds/scratch" {} /*start with fs3*/
resource scratchdisk "/fs0/ds/scratch" {}
resource scratchdisk "/fs1/ds/scratch" {}
resource scratchdisk "/fs2/ds/scratch" {}
resource disk "/fs3/ds/disk" {} /* start with fs3 */
resource disk "/fs0/ds/disk" {}
resource disk "/fs1/ds/disk" {}
resource disk "/fs2/ds/disk" {}
}
node "n4" {
pools ""
fastname "fastone"
/*
* Ok, now what. We rotated through starting with a
* different disk, but we have a basic problem here which is
* that there are more CPUs than disks. So what do we do
* now? The answer: something that is not perfect. We’re
* going to repeat the sequence. You could shuffle
* differently i.e., use /fs0 /fs2 /fs1 /fs3 as an order.
* I’m not sure it will matter all that much.
*/
resource scratchdisk "/fs0/ds/scratch" {} /*start with fs0
again*/
resource scratchdisk "/fs1/ds/scratch" {}
resource scratchdisk "/fs2/ds/scratch" {}
resource scratchdisk "/fs3/ds/scratch" {}
resource disk "/fs0/ds/disk" {} /* start with fs0 again */
resource disk "/fs1/ds/disk" {}
resource disk "/fs2/ds/disk" {}
resource disk "/fs3/ds/disk" {}
}
node "n5" {
pools ""
fastname "fastone"
resource scratchdisk "/fs1/ds/scratch" {} /*start with fs1*/
resource scratchdisk "/fs2/ds/scratch" {}
resource scratchdisk "/fs3/ds/scratch" {}
resource scratchdisk "/fs0/ds/scratch" {}
resource disk "/fs1/ds/disk" {} /* start with fs1 */
resource disk "/fs2/ds/disk" {}

576 Parallel Job Developer Guide

resource disk "/fs3/ds/disk" {}
resource disk "/fs0/ds/disk" {}
}
} /* end of whole config */

The above config file pattern could be called ″give everyone all the disk″. This configuration style works
well when the flow is complex enough that you can’t really figure out and precisely plan for good I/O
utilization. Giving every partition (node) access to all the I/O resources can cause contention, but the
parallel engine tends to use fairly large blocks for I/O so the contention isn’t as much of a problem as
you might think. This configuration style works for any number of CPUs and any number of disks since
it doesn’t require any particular correspondence between them. The heuristic principle at work here is
this ″When it’s too difficult to figure out precisely, at least go for achieving balance.″

The alternative to the above configuration style is more careful planning of the I/O behavior so as to
reduce contention. You can imagine this could be hard given our hypothetical 6-way SMP with 4 disks
because setting up the obvious one-to-one correspondence doesn’t work. Doubling up some nodes on the
same disk is unlikely to be good for overall performance since we create a hotspot. We could give every
CPU 2 disks and rotate around, but that would be little different than our above strategy. So, let’s
imagine a less constrained environment and give ourselves 2 more disks /fs4 and /fs5. Now a config file
might look like this:
{
node "n0" {
pools ""
fastname "fastone"
resource scratchdisk "/fs0/ds/scratch" {}
resource disk "/fs0/ds/disk" {}
}
node "n1" {
pools ""
fastname "fastone"
resource scratchdisk "/fs1/ds/scratch" {}
resource disk "/fs1/ds/disk" {}
}
node "n2" {
pools ""
fastname "fastone"
resource scratchdisk "/fs2/ds/scratch" {}
resource disk "/fs2/ds/disk" {}
}
node "n3" {
pools ""
fastname "fastone"
resource scratchdisk "/fs3/ds/scratch" {}
resource disk "/fs3/ds/disk" {}
}
node "n4" {
pools ""
fastname "fastone"
resource scratchdisk "/fs4/ds/scratch" {}
resource disk "/fs4/ds/disk" {}
}
node "n5" {
pools ""
fastname "fastone"
resource scratchdisk "/fs5/ds/scratch" {}
resource disk "/fs5/ds/disk" {}
}
} /* end of whole config */

This is simplest, but realize that no single player (stage/operator instance) on any one partition can go
faster than the single disk it has access to.

Chapter 54. The Parallel engine configuration file 577

You could combine strategies by adding in a node pool where disks have this one-to-one association with
nodes. These nodes would then not be in the default node pool, but a special one that you would assign
stages/operators to specifically.

Other configuration file hints:

v Consider avoiding the disk/disks that your input files reside on. Often those disks will be hotspots
until the input phase is over. If the job is large and complex this is less of an issue since the input part
is proportionally less of the total work.
v Ensure that the different file systems mentioned as the disk and scratchdisk resources hit disjoint sets
of spindles even if they’re located on a RAID system.
v Know what is real and what is NFS: Real disks are directly attached, or are reachable over a SAN
(storage-area network - dedicated, just for storage, low-level protocols).
– Never use NFS file systems for scratchdisk resources.
– If you use NFS file system space for disk resources, then you need to know what you are doing.
For example, your final result files may need to be written out onto the NFS disk area, but that
doesn’t mean the intermediate data sets created and used temporarily in a multi-job sequence
should use this NFS disk area. Better to setup a ″final″ disk pool, and constrain the result sequential
file or data set to reside there, but let intermediate storage go to local or SAN resources, not NFS.
v Know what data points are striped (RAID) and which are not. Where possible, avoid striping across
data points that are already striped at the spindle level.

578 Parallel Job Developer Guide

Chapter 55. Remote deployment
Remote deployment of parallel jobs allows job scripts to be stored and run on a separate machine from
the WebSphere DataStage Server machine. The remote deployment option can, for example, be used to
run jobs on a computer grid.

Any remote system that has a job so deployed must have access to the Parallel Engine in order to run the
job. Such systems must also have the correct runtime libraries for that platform type.

Because these jobs are not run on the WebSphere DataStage Server, server components (such as BASIC
Transformer stages, server shared containers, before and after subroutines, and job control routines)
cannot be used. There is also a limited set of plug-in stages available for use in these jobs.

When you run the jobs the logging, monitoring, and operational meta data collection facilities provided
by WebSphere DataStage are not available. Deployed jobs do output logging information in internal
paralle engine format, but provision for collecting this is the user’s responsibility.

You develop a Parallel job for deployment using the WebSphere DataStage Designer, and then compile it.
A deployment package is automatically produced at compilation. Such jobs can also be run under the
control of the WebSphere DataStage Server (using Designer or Director clients, or the dsjob command) as
per normal. (Note that running jobs in the `normal’ way runs the executables in the project directory, not
the deployment scripts.)

It is your responsibility to define a configuration file on the remote machine, transfer the deployment
package to the remote computer and to run the job.

The following diagram gives a conceptual view of an example deployment system. In this example,
deployable jobs are transferred to three `conductor node’ machines. Each conductor node has a
configuration file describing the resources that it has available for running the jobs. The jobs then run
under the control of that conductor:

© Copyright IBM Corp. 2006 579

 Design time Design time DS Server
DS Server

Deployable scripts

conductor conductor conductor

node node node

node node node

node node node

node node node

Note: The WebSphere DataStage Server system and the Node systems must be running the same
operating system.

Enabling a project for job deployment

Projects are made capable of deploying jobs in this way from the WebSphere DataStage Administrator
client. To make the jobs in a project deployable:
1. Start the WebSphere DataStage Administrator client.
2. Go to the Projects tab and select the project whose parallel jobs you want to make deployable from
the list.
3. Click the Properties button to open the Project Properties dialog box.
4. Go to the Remote tab.
5. In the Base directory name field, provide a home directory location for deployment; in this directory
there will be one directory for each project. This location has to be accessible from the server machine,
but does not have to be a disk local to that machine. Providing a location here enables the job
deployment features.
6. In the Deployed job directory template field, optionally specify an alternative name for the
deployment directory associated with a particular job. This field is used in conjunction with Base
directory name in the form base_name/project_name/job_directory. By default, if nothing is specified,
the name corresponds to the internal script directory used on the WebSphere DataStage server project
directory, RT_SCjobnum, where jobnum is the internal job number allocated to the job. Substitution
strings provided are:

580 Parallel Job Developer Guide

 v %j - jobname
v %d - internal number
The simplest case is just ″%j″ - use the jobname. A prefix can be used, i.e., ″job_%j″. The default
corresponds to RT_SC%d.
7. In the Custom deployment commands field, optionally specify further actions to be carried out at the
end of a deployment compile. You can specify Unix programs and /or calls to user shell scripts as
required. The actions take place in the deployment directory for the job.
This field uses the same substitution strings as the directory template. For example:

Deployment package
When you compile a job in the WebSphere DataStage Designer with project deployment enabled, the
following files are produced:
v Command shell script
v Environment variable setting source script
v Main Parallel (osh) program script
v Script parameter file
v XML report file (if enabled - see WebSphere DataStage Parallel Job Advanced Developer Guide).
v Compiled transformer binary files (if the job contains any Transformer stages)
v Transformer source compilation scripts

These are the files that will be copied to a job directory in the base directory specified in the
Administrator client for the project. By default the job directory is called RT_SCjobnum, where jobnum is
the internal job number allocated to the job (you can change the form of the name in the Administrator
client).

If you have additional custom components designed outside the job (for example, custom, built, or
wrapped stages) you should ensure that these are available when the job is run. They are not
automatically packaged and deployed.

Command shell script - pxrun.sh

The command shell script sources the environment variable script, then calls the PXEngine, specifying the
main osh program script and script parameter file as parameters. Run this script to run your job.

Environment variable setting source script - evdepfile

This file contains the environment variables for a deployed job when it is run. It is based on the
environment variables set when the job was compiled.

It is possible to edit this file manually if required before running a job. The file can be removed
altogether, but it is then your responsibility to set up the environment before running the job.

Main parallel (OSH) program script - OshScript.osh

The main parallel job script. You must execute the command shell script in order to run this, you should
not run it directly.

Script parameter file - jpdepfile

This is used by pxrun.sh. It contains the job parameters for a deployed job when it is run. It is based on
the default job parameters when the job was compiled.

Chapter 55. Remote deployment 581

It is possible to edit this file manually if required before running a job.

XML report file - <jobname>.xml

An XML report of the job design can be automatically generated at compile time (if enabled using an
administration command - see WebSphere DataStage Parallel Job Advanced Developer Guide and the report is
included in the job deployment package. For more information on HTML and XML job reports, see
WebSphere DataStage Designer Client Guide.

Compiled transformer binary files - <jobnamestagename>.trx.so

There is one of these for each Transformer stage in your job.

Self-contained transformer compilation

In order to make the job self-contained with regard to transformer compilation, there are the following
additional files which can optionally be used for transformer recompilation; none are present if there are
no transformers in the job:
v Transformer source files (internal transformer language). It has a name in the form
<internalidentifier>_<jobname>_<stagename>.trx. There is one such file for each Transformer stage in the
job.
v Shell scripts to run transformer operator compile jobs. It has a name in the form
<internalidentifier>_<jobname>_<stagename>.trx.sh. There is one such file for each Transformer stage in
the job.
v Transformer compilation operator osh scripts. This is a Parallel job script to compile the corresponding
Transformer stage. It is called from corresponding .sh file. It has a name in the form
<internalidentifier>_<jobname>_<stagename>.trx.osh. There is one such file for each Transformer stage in
the job.
v One master shell script to call all transformer compile scripts called pxcompile.sh.

If you want to recompile transformers on your deployment platform before running the job, you should
run pxcompile.sh.

Deploying a job
This describes how to design a job on the WebSphere DataStage system in a remote deployment project,
transfer it to the deployment machine, and run it.
1. In the WebSphere DataStage Administrator, specify a remote deployment project as described in
″Enabling a Project for Job Deployment″ .
2. Define a configuration file on your remote deployment systems that will describe it. Use the
environment variable APT_CONFIG_FILE to identify it on the remote machine. You can do this in one
of three ways:
v If you are always going to use the same configuration file on the same remote system, define
APT_CONFIG_FILE on a project-wide basis in the WebSphere DataStage Administrator. All your
remote deployment job packages will have that value for APT_CONFIG_FILE.
v To specify the value at individual job level, specify APT_CONFIG_FILE as a job parameter and set
the default value to the location of the configuration file. This will be packaged with that particular
job.
v To specify the value at run time, set the value of APT_CONFIG_FILE to $ENV in the WebSphere
DataStage Administrator and then define APT_CONFIG_FILE as an environment variable on your
remote machine. The job will pick up the value at run time.

582 Parallel Job Developer Guide

3. In the WebSphere DataStage Designer, design your parallel job as normal (but remember that you
cannot use BASIC Transformer stages, shared containers, or plugin stages in remote deployment jobs).
4. When you are happy with your job design, compile it.
5. If your job contains Transformer stages, you can if required recompile the transformers on the
deployment machine. To do this, execute the following file:
pxcompile.sh
6. When your Transformer stages have successfully compiled, run the job by executing the following file:
pxrun.sh

Server side plug-ins

WebSphere DataStage XML and Java™ plug-ins operate on remote nodes. The following directories are
required on the nodes in order to run a plug-in, these can be copied from a WebSphere DataStage Server
installation:
v DSEngine/java
v DSEngine/lib
v DSCAPIOp

Note: The Java plug-in does not run on Red Hat Enterprise Linux® AS 2.1/Red Hat 7.3.

Chapter 55. Remote deployment 583

584 Parallel Job Developer Guide
Appendix A. Schemas
Schemas are an alternative way for you to specify column definitions for the data used by parallel jobs.
By default, most parallel job stages take their meta data from the Columns tab, which contains table
definitions, supplemented, where necessary by format information from the Format tab. For some stages,
you can specify a property that causes the stage to take its meta data from the specified schema file
instead. Some stages also allow you to specify a partial schema. This allows you to describe only those
columns that a particular stage is processing and ignore the rest.

The schema file is a plain text file, this appendix describes its format. A partial schema has the same
format.

Note: If you are using a schema file on an NLS system, the schema file needs to be in UTF-8 format. It is,
however, easy to convert text files between two different maps with a WebSphere DataStage job.
Such a job would read data from a text file using a Sequential File stage and specifying the
appropriate character set on theNLS Map page. It would write the data to another file using a
Sequential File stage, specifying the UTF-8 map on the NLS Map page.

Schema format
A schema contains a record (or row) definition. This describes each column (or field) that will be
encountered within the record, giving column name and data type. The following is an example record
schema:
record (
name:string[255];
address:nullable string[255];
value1:int32;
value2:int32
date:date)

(The line breaks are there for ease of reading, you would omit these if you were defining a partial
schema, for example record(name:string[255];value1:int32;date:date) is a valid schema.)

The format of each line describing a column is:

column_name:[nullability]datatype;
v column_name. This is the name that identifies the column. Names must start with a letter or an
underscore (_), and can contain only alphanumeric or underscore characters. The name is not case
sensitive. The name can be of any length.
v nullability. You can optionally specify whether a column is allowed to contain a null value, or whether
this would be viewed as invalid. If the column can be null, insert the word ’nullable’. By default
columns are not nullable.
You can also include ’nullable’ at record level to specify that all columns are nullable, then override the
setting for individual columns by specifying `not nullable’. For example:
record nullable (
name:not nullable string[255];
value1:int32;
date:date)
v datatype. This is the data type of the column. This uses the internal data types as described on page
Data Types, not SQL data types as used on Columns tabs in stage editors.

You can include comments in schema definition files. A comment is started by a double slash //, and
ended by a newline.

© Copyright IBM Corp. 2006 585

The example schema corresponds to the following table definition as specified on a Columns tab of a
stage editor:

The following sections give special consideration for representing various data types in a schema file.

Date columns
The following examples show various different data definitions:
record (dateField1:date; ) // single date
record (dateField2[10]:date; ) // 10-element date vector
record (dateField3[]:date; ) // variable-length date vector
record (dateField4:nullable date;) // nullable date

(See ″Complex Data Types″ on page Complex Data Types for information about vectors.)

Decimal columns
To define a record field with data type decimal, you must specify the column’s precision, and you may
optionally specify its scale, as follows:
column_name:decimal[ precision, scale];

where precision is greater than or equal 1 and scale is greater than or equal to 0 and less than precision.

If the scale is not specified, it defaults to zero, indicating an integer value.

The following examples show different decimal column definitions:

586 Parallel Job Developer Guide

record (dField1:decimal[12]; ) // 12-digit integer
record (dField2[10]:decimal[15,3]; )// 10-element
//decimal vector
record (dField3:nullable decimal[15,3];) // nullable decimal

Floating-point columns
To define floating-point fields, you use the sfloat (single-precision) or dfloat (double-precision) data type,
as in the following examples:
record (aSingle:sfloat; aDouble:dfloat; ) // float definitions
record (aSingle: nullable sfloat;) // nullable sfloat
record (doubles[5]:dfloat;) // fixed-length vector of dfloats
record (singles[]:sfloat;) // variable-length vector of sfloats

Integer columns
To define integer fields, you use an 8-, 16-, 32-, or 64-bit integer data type (signed or unsigned), as shown
in the following examples:
record (n:int32;) // 32-bit signed integer
record (n:nullable int64;) // nullable, 64-bit signed integer record (n[10]:int16;) // fixed-length vector of 16-bit
//signed integer
record (n[]:uint8;) // variable-length vector of 8-bit unsigned
//int

Raw columns
You can define a record field that is a collection of untyped bytes, of fixed or variable length. You give
the field data type raw. The definition for a raw field is similar to that of a string field, as shown in the
following examples:
record (var1:raw[];) // variable-length raw field
record (var2:raw;) // variable-length raw field; same as raw[]
record (var3:raw[40];) // fixed-length raw field
record (var4[5]:raw[40];)// fixed-length vector of raw fields

You can specify the maximum number of bytes allowed in the raw field with the optional property max,
as shown in the example below:
record (var7:raw[max=80];)

The length of a fixed-length raw field must be at least 1.

String columns
You can define string fields of fixed or variable length. For variable-length strings, the string length is
stored as part of the string as a hidden integer. The storage used to hold the string length is not included
in the length of the string.

The following examples show string field definitions:

record (var1:string[];) // variable-length string
record (var2:string;) // variable-length string; same as string[]
record (var3:string[80];) // fixed-length string of 80 bytes
record (var4:nullable string[80];) // nullable string
record (var5[10]:string;) // fixed-length vector of strings
record (var6[]:string[80];) // variable-length vector of strings

You can specify the maximum length of a string with the optional property max, as shown in the
example below:
record (var7:string[max=80];)

Appendix A. Schemas 587

The length of a fixed-length string must be at least 1.

Time columns
By default, the smallest unit of measure for a time value is seconds, but you can instead use
microseconds with the [microseconds] option. The following are examples of time field definitions:
record (tField1:time; ) // single time field in seconds
record (tField2:time[microseconds];)// time field in //microseconds
record (tField3[]:time; ) // variable-length time vector
record (tField4:nullable time;) // nullable time

Timestamp columns
Timestamp fields contain both time and date information. In the time portion, you can use seconds (the
default) or microseconds for the smallest unit of measure. For example:
record (tsField1:timestamp;)// single timestamp field in //seconds
record (tsField2:timestamp[microseconds];)// timestamp in //microseconds
record (tsField3[15]:timestamp; )// fixed-length timestamp //vector
record (tsField4:nullable timestamp;)// nullable timestamp

Vectors
Many of the previous examples show how to define a vector of a particular data type. You define a
vector field by following the column name with brackets []. For a variable-length vector, you leave the
brackets empty, and for a fixed-length vector you put the number of vector elements in the brackets. For
example, to define a variable-length vector of int32, you would use a field definition such as the
following one:
intVec[]:int32;

To define a fixed-length vector of 10 elements of type sfloat, you would use a definition such as:
sfloatVec[10]:sfloat;

You can define a vector of any data type, including string and raw. You cannot define a vector of a vector
or tagged type. You can, however, define a vector of type subrecord, and you can define that subrecord
includes a tagged column or a vector.

You can make vector elements nullable, as shown in the following record definition:
record (vInt[]:nullable int32;
vDate[6]:nullable date; )

In the example above, every element of the variable-length vector vInt will be nullable, as will every
element of fixed-length vector vDate. To test whether a vector of nullable elements contains no data, you
must check each element for null.

Subrecords
Record schemas let you define nested field definitions, or subrecords, by specifying the type subrec. A
subrecord itself does not define any storage; instead, the fields of the subrecord define storage. The fields
in a subrecord can be of any data type, including tagged.

The following example defines a record that contains a subrecord:

588 Parallel Job Developer Guide

record ( intField:int16;
aSubrec:subrec (
aField:int16;
bField:sfloat; );
)

In this example, the record contains a 16-bit integer field, intField, and a subrecord field, aSubrec. The
subrecord includes two fields: a 16-bit integer and a single-precision float.

Subrecord columns of value data types (including string and raw) can be nullable, and subrecord
columns of subrec or vector types can have nullable elements. A subrecord itself cannot be nullable.

You can define vectors (fixed-length or variable-length) of subrecords. The following example shows a
definition of a fixed-length vector of subrecords:
record (aSubrec[10]:subrec (
aField:int16;
bField:sfloat; );
)

You can also nest subrecords and vectors of subrecords, to any depth of nesting. The following example
defines a fixed-length vector of subrecords, aSubrec, that contains a nested variable-length vector of
subrecords, cSubrec:
record (aSubrec[10]:subrec (
aField:int16;
bField:sfloat;
cSubrec[]:subrec (
cAField:uint8;
cBField:dfloat; );
);
)

Subrecords can include tagged aggregate fields, as shown in the following sample definition:
record (aSubrec:subrec (
aField:string;
bField:int32;
cField:tagged (
dField:int16;
eField:sfloat;
);
);
)

In this example, aSubrec has a string field, an int32 field, and a tagged aggregate field. The tagged
aggregate field cField can have either of two data types, int16 or sfloat.

Tagged columns
You can use schemas to define tagged columns (similar to C unions), with the data type tagged. Defining
a record with a tagged type allows each record of a data set to have a different data type for the tagged
column. When your application writes to a field in a tagged column, WebSphere DataStage updates the
tag, which identifies it as having the type of the column that is referenced.

The data type of a tagged columns can be of any data type except tagged or subrec. For example, the
following record defines a tagged subrecord field:
record ( tagField:tagged (
aField:string;
bField:int32;
cField:sfloat;
) ;
)

Appendix A. Schemas 589

In the example above, the data type of tagField can be one of following: a variable-length string, an int32,
or an sfloat.

Partial schemas
Some parallel job stages allow you to use a partial schema. This means that you only need define column
definitions for those columns that you are actually going to operate on. The stages that allow you to do
this are file stages that have a Format tab. These are:
v Sequential File stage
v File Set stage
v External Source stage
v External Target stage
v Column Import stage

You specify a partial schema using the Intact property on the Format tab of the stage together with the
Schema File property on the corresponding Properties tab. To use this facility, you need to turn Runtime
Column Propagation on, and provide enough information about the columns being passed through to
enable WebSphere DataStage to skip over them as necessary.

In the file defining the partial schema, you need to describe the record and the individual columns.
Describe the record as follows:
v intact. This property specifies that the schema being defined is a partial one. You can optionally specify
a name for the intact schema here as well, which you can then reference from the Intact property of the
Format tab.
v record_length. The length of the record, including record delimiter characters.
v record_delim_string. String giving the record delimiter as an ASCII string in single quotes. (For a
single character delimiter, use record_delim and supply a single ASCII character in single quotes).

Describe the columns as follows:

v position. The position of the starting character within the record.
v delim. The column trailing delimiter, can be any of the following:
– ws to skip all standard whitespace characters (space, tab, and newline) trailing after a field.
– end to specify that the last field in the record is composed of all remaining bytes until the end of the
record.
– none to specify that fields have no delimiter.
– null to specify that the delimiter is the ASCII null character.
– ASCII_char specifies a single ASCII delimiter. Enclose ASCII_char in single quotation marks. (To
specify multiple ASCII characters, use delim_string followed by the string in single quotes.)
v text specifies the data representation type of a field as being text rather than binary. Data is formatted
as text by default. (Specify binary if data is binary.)

Columns that are being passed through intact only need to be described in enough detail to allow
WebSphere DataStage to skip them and locate the columns that are to be operated on.

For example, say you have a sequential file defining rows comprising six fixed width columns, and you
are in interested in the last two. You know that the first four columns together contain 80 characters. Your
partial schema definition might appear as follows:
record { intact=details, record_delim_string = ’\r\n’ }
( colstoignore: string [80]
name: string [20] { delim=none };
income: uint32 {delim = ",", text };

590 Parallel Job Developer Guide

Your stage would not be able to alter anything in a row other than the name and income columns (it
could also add a new column to either the beginning or the end of a row).

Appendix A. Schemas 591

592 Parallel Job Developer Guide
Appendix B. Functions
This appendix describes the functions that are available from the expression editor under the Function...
menu item. You would typically use these functions when defining a column derivation in a Transformer
stage. The functions are described by category.

This set includes functions that take string arguments or return string values. If you have NLS enabled,
the arguments strings or returned strings can be strings or ustrings. The same function is used for either
string type. The only exceptions are the functions StringToUstring () and UstringToString ().

Date and time functions

The following table lists the functions available in the Date & Time category (Square brackets indicate an
argument is optional):

Name Description Arguments Output

DateFromDaysSince Returns a date by adding number (int32) [baseline date
an integer to a baseline date]
date
DateFromJulianDay Returns a date from the juliandate (uint32) date
given julian date
DaysSinceFromDate Returns the number of source_date days since (int32)
days from source date to
the given date given_date
HoursFromTime Returns the hour portion time hours (int8)
of a time
JulianDayFromDate Returns julian day from date julian date (int32)
the given date
MicroSecondsFromTime Returns the microsecond time microseconds (int32)
portion from a time
MinutesFromTime Returns the minute portion time minutes (int8)
from a time
MonthDayFromDate Returns the day of the date day (int8)
month given the date
MonthFromDate Returns the month number date month number (int8)
given the date
NextWeekdayFromDate Returns the date of the source date date
specified day of the week
soonest after the source day of week (string)
date
PreviousWeekdayFromDate Returns the date of the source date date
specified day of the week
most recent before the day of week (string)
source date
SecondsFromTime Returns the second portion time seconds (dfloat)
from a time
SecondsSinceFromTimestamp Returns the number of timestamp base timestamp seconds (dfloat)
seconds between two
timestamps

© Copyright IBM Corp. 2006 593

Name Description Arguments Output
TimeDate Returns the system time - system time and date
and date as a formatted (string)
string
TimeFromMidnightSeconds Returns the time given the seconds (dfloat) time
number of seconds since
midnight
TimestampFromDateTime Returns a timestamp form date time timestamp
the given date and time
TimestampFromSecondsSince Returns the timestamp seconds (dfloat) timestamp
from the number of
seconds from the base [base timestamp]
timestamp
TimestampFromTimet Returns a timestamp from timet (int32) timestamp
the given unix time_t value
TimetFromTimestamp Returns a unix time_t timestamp timet (int32)
value from the given
timestamp
WeekdayFromDate Returns the day number of date [origin day] day (int8)
the week from the given
date. Origin day optionally
specifies the day regarded
as the first in the week and
is Sunday by default
YeardayFromDate Returns the day number in date day (int16)
the year from the given
date
YearFromDate Returns the year from the date year (int16)
given date
YearweekFromDate Returns the week number date week (int16)
in the year from the given
date

Date, Time, and Timestamp functions that specify dates, times, or timestamps in the argument use strings
with specific formats:

For a date, the format is %yyyy-%mm-%dd

For a time, the format is %hh:%nn:%ss, or, if extended to include microseconds, %hh:%nn:%ss.x where x
gives the number of decimal places seconds is given to.

For a timestamp the format is %yyyy-%mm-%dd %hh:%nn:%ss, or, if extended to include microseconds,
%yyyy-%mm-%dd %hh:%nn:%ss.x where x gives the number of decimal places seconds is given to.

This applies to the arguments date, baseline date, given date, time, timestamp, and base timestamp.

Functions that have days of week in the argument take a string specifying the day of the week, this
applies to day of week and origin day.

594 Parallel Job Developer Guide

Logical Functions
The following table lists the functions available in the Logical category (square brackets indicate an
argument is optional):

Name Description Arguments Output

Not Returns the complement of expression Complement (int8)
the logical value of an
expression
BitAnd Returns the bitwise AND of number 1 (uint64) number number (uint64)
the two integer arguments 2 (uint64)
BitOr Returns the bitwise OR of number 1 (uint64) number number (uint64)
the two integer arguments 2 (uint64)
BitXOr Returns the bitwise number 1 (uint64) number number (uint64)
Exclusive OR of the two 2 (uint64)
integer arguments
BitExpand Returns a string containing number (uint64) string
the binary representation in
″1″s and ″0″s of the given
integer
BitCompress Returns the integer made number (string) number (uint64)
from the string argument,
which contains a binary
representation of ″1″s and
″0″s.
SetBit Returns an integer with origfield (uint64) bitlist number (uint64)
specific bits set to a specific (string)
state, where
bitstate (uint8)
origfield is the input value
to perform the action on,

bitlist is a string containing

a list of comma separated
bit numbers to set the state
of, and bitstate is either 1 or
0, indicating which state to
set those bits.

Mathematical Functions
The following table lists the functions available in the Mathematical category (square brackets indicate an
argument is optional):

Name Description Arguments Output

Abs Absolute value of any number (int32) result (dfloat)
numeric expression
Acos Calculates the trigonometric number (dfloat) result (dfloat)
arc-cosine of an expression
Asin Calculates the trigonometric number (dfloat) result (dfloat)
arc-sine of an expression
Atan Calculates the trigonometric number (dfloat) result (dfloat)
arc-tangent of an expression

Appendix B. Functions 595

Name Description Arguments Output
Ceil Calculates the smallest number (decimal) result (int32)
integer value greater than
or equal to the given
decimal value
Cos Calculates the trigonometric number (dfloat) result (dfloat)
cosine of an expression
Cosh Calculates the hyperbolic number (dfloat) result (dfloat)
cosine of an expression
Div Outputs the whole part of dividend (dfloat) divisor result (dfloat)
the real division of two real (dfloat)
numbers (dividend, divisor)
Exp Calculates the result of base number (dfloat) result (dfloat)
’e’ raised to the power
designated by the value of
the expression
Fabs Calculates the absolute number (dfloat) result (dfloat)
value of the given value
Floor Calculates the largest number (decimal) result (int32)
integer value less than or
equal to the given decimal
value
Ldexp Calculates a number from mantissa (dfloat) result (dfloat)
an exponent and mantissa
exponent (int32)
Llabs Returns the absolute value number (uint64) result (int64)
of the given integer
Ln Calculates the natural number (dfloat) result (dfloat)
logarithm of an expression
in base ’e’
Log10 Returns the log to the base number (dfloat) result (dfloat)
10 of the given value
Max Returns the greater of the number 1 (int32) number result (int32)
two argument values 2(int32)
Min Returns the lower of the number 1 (int32) number 2 result (int32)
two argument values (int32)
Mod Calculates the modulo (the dividend (int32) divisor result (int32)
remainder) of two (int32)
expressions (dividend,
divisor)
Neg Negate a number number (dfloat) result (dfloat)
Pwr Calculates the value of an expression (dfloat) power result (dfloat)
expression when raised to a (dfloat)
specified power
(expression, power)
Rand Return a psuedo random - result (uint32)
integer between 0 and 232-1
Random Returns a random number - result (uint32)
between 0 232-1
Sin Calculates the trigonometric number (dfloat) result (dfloat)
sine of an angle

596 Parallel Job Developer Guide

Name Description Arguments Output
Sinh Calculates the hyperbolic number (dfloat) result (dfloat)
sine of an expression
Sqrt Calculates the square root number (dfloat) result (dfloat)
of a number
Tan Calculates the trigonometric number (dfloat) result (dfloat)
tangent of an angle
Tanh Calculates the hyperbolic number (dfloat) result (dfloat)
tangent of an expression

Null handling functions

The following table lists the functions available in the Null Handling category (square brackets indicate
an argument is optional):

Name Description Arguments Output

IsNotNull Returns true when an any true/false (int8)
expression does not
evaluate to the null value
IsNull Returns true when an any true/false (int8)
expression evaluates to the
null value
MakeNull Change an in-band null to any (column) -
out of band null
string (string)
NullToEmpty Returns an empty string if input column input column value or
input column is null, empty string
otherwise returns the input
column value
NullToZero Returns zero if input input column input column value or zero
column is null, otherwise
returns the input column
value
NullToValue Returns specified value if input column, value input column value or value
input column is null,
otherwise returns the input
column value
SetNull Assign a null value to the - -
target column

true = 1

false = 0

Appendix B. Functions 597

Number functions
The following table lists the functions available in the Number category (square brackets indicate an
argument is optional):

Name Description Arguments Output

MantissaFromDecimal Returns the mantissa from number (decimal) result (dfloat)
the given decimal
MantissaFromDFloat Returns the mantissa from number (dfloat) result (dfloat)
the given dfloat

Raw functions
The following table lists the functions available in the Raw category (square brackets indicate an
argument is optional):

Name Description Arguments Output

RawLength Returns the length of a raw input string (raw) Result (int32)
string

String functions
The following table lists the functions available in the String category (square brackets indicate an
argument is optional):

Name Description Arguments Output

AlNum Return whether the given string (string) true/false (int8)
string consists of
alphanumeric characters
Alpha Returns 1 if string is purely string (string) result (int8)
alphabetic
CompactWhiteSpace Return the string after string (string) result (string)
reducing all consective
whitespace to a single
space
Compare Compares two strings for string1 (string) result (int8)
sorting
string2 (string)

[justification (L or R)]
ComparNoCase Case insensitive string1 (string) string2 result (int8)
comparison of two strings (string)
ComparNum Compare the first n string1 (string) string2 result (int8)
characters of the two (string)
strings
length (int16)
CompareNumNoCase Caseless comparison of the string1 (string) string2 result (int8)
first n characters of the two (string)
strings
length (int16)

598 Parallel Job Developer Guide

Name Description Arguments Output
Convert Converts specified fromlist (string) result (string)
characters in a string to
designated replacement tolist (string)
characters
expression (string)
Count Count number of times a string (string) result (int32)
substring occurs in a string
substring (string)
Dcount Count number of delimited string (string) result (int32)
fields in a string
delimiter (string)
DownCase Change all uppercase string (string) result (string)
letters in a string to
lowercase
DQuote Enclose a string in double string (string) result (string)
quotation marks
Field Return 1 or more delimited string (string) delimiter result (string)
substrings (string)

occurrence (int32) [number

(int32)]
Index Find starting character string (string) substring result (int32)
position of substring (string) occurrence (int32)
Left Leftmost n characters of string (string) result (string)
string
number (int32)
Len Length of string in string (string) result (int32)
characters
Num Return 1 if string can be string (string) result (int8)
converted to a number
PadString Return the string padded string (string) result (string)
with the optional pad
character and optional padlength (int32)
length
Right Rightmost n characters of string (string) result (string)
string
number (int32)
Soundex Returns a string which string (string) result (string)
identifies a set of words
that are (roughly)
phonetically alike based on
the standard, open
algorithm for SOUNDEX
evaluation
Space Return a string of N space length (int32) result (string)
characters
Squote Enclose a string in single string (string) result (string)
quotation marks
Str Repeat a string string (string) result (string)

repeats (int32)

Appendix B. Functions 599

Name Description Arguments Output
Return the string after string (string) result (string)
stripping all whitespace
from it
Remove all leading and string (string) [stripchar result (string)
trailing spaces and tabs (string)] [options (string)]
plus reduce internal
occurrences to one
TrimB Remove all trailing spaces string (string) result (string)
and tabs
TrimF Remove all leading spaces string (string) result (string)
and tabs
Trim Leading Trailing Returns a string with string (string) result (string)
leading and trailing
whitespace removed
Upcase Change all lowercase letters string (string) result (string)
in a string to uppercase

true = 1

false = 0

Possible options for the Trim function are:

v L Removes leading occurrences of character.
v T Removes trailing occurrences of character.
v B Removes leading and trailing occurrences of character.
v R Removes leading and trailing occurrences of character, and reduces multiple occurrences to a single
occurrence.
v A Removes all occurrences of character.
v F Removes leading spaces and tabs.
v E Removes trailing spaces and tabs.
v D Removes leading and trailing spaces and tabs, and reduces multiple spaces and tabs to single ones.

Vector function
The following function can be used within expressions to access an element in a vector column. The
vector index starts at 0.

Name Description Arguments Output

ElementAt Accesses an element of a input column index (int) element of vector
vector

This can be used as part of, or the whole of an expression. For example, an expression to add 1 to the
third element of an vector input column ’InLink.col1’ would be:
ElementAt(InLink.col1, 2) + 1

600 Parallel Job Developer Guide

Type Conversion Functions
The following table lists the functions available in the Type Conversion category (square brackets indicate
an argument is optional):

Name Description Arguments Output

DateToString Return the string date result (string)
representation of the given
date [format (string)]
DecimalToDecimal Returns the given decimal decimal (decimal) [rtype result (decimal)
in decimal representation (string)] [packedflag (int8)]
with specified precision
and scale
DecimalToDFloat Returns the given decimal number (decimal) result (dfloat)
in dfloat representation [″fix_zero″]
DecimalToString Return the string number (decimal) result (string)
representation of the given [″fix_zero″]
decimal
DfloatToDecimal Returns the given dfloat in number (dfloat) [rtype result (decimal)
decimal representation (string)]
DfloatToStringNoExp Returns the given dfloat in number (dfloat) scale result (string)
its string representation (string)
with no exponent, using the
specified scale
IsValid Return whether the given type (string) format (string) result (int8)
string is valid for the given
type. Valid types are ″date″,
″decimal″, ″dfloat″, ″sfloat″,
″int8″, ″uint8″, ″int16″,
″uint16″, ″int32″, ″uint32″,
″int64″, ″uint64″, ″raw″,
″string″, ″time″,
″timestamp″. ″ustring″
StringToDate Returns a date from the date (string) date
given string in the given
format format (string)
StringToDecimal Returns the given string in string (string) [rtype result (decimal)
decimal representation (string)]
StringToRaw Returns a string in raw string (string) result (raw)
representation
StringToTime Returns a time string (string) [format time
representation of the given (string)]
string
StringToTimestamp Returns a timestamp string (string) [format timestamp
representation of the given (string)]
string
TimestampToDate Returns a date from the timestamp date
given timestamp
TimestampToString Return the string timestamp [format (string)] result (string)
representation of the given
timestamp
TimestampToTime Returns the time from a timestamp time
given timestamp

Appendix B. Functions 601

Name Description Arguments Output
TimeToString Return the string time [format (string)] result (string)
representation of the given
time
StringToUstring Returns a ustring from the string (string) [,mapname result (ustring)
given string, optionally (string)]
using the specified map
(otherwise uses project
default)
UstringToString Returns a string from the string(ustring) result (string)
given ustring, optionally
using the specified map [,mapname (string)]
(otherwise uses project
default)

Rtype. The rtype argument is a string, and should contain one of the following:
v ceil. Round the source field toward positive infinity. E.g, 1.4 -> 2, -1.6 -> -1.
v floor. Round the source field toward negative infinity. E.g, 1.6 -> 1, -1.4 -> -2.
v round_inf. Round or truncate the source field toward the nearest representable value, breaking ties by
rounding positive values toward positive infinity and negative values toward negative infinity. E.g, 1.4
-> 1, 1.5 -> 2, -1.4 -> -1, -1.5 -> -2.
v trunc_zero. Discard any fractional digits to the right of the rightmost fractional digit supported in the
destination, regardless of sign. For example, if the destination is an integer, all fractional digits are
truncated. If the destination is another decimal with a smaller scale, round or truncate to the scale size
of the destination decimal. E.g, 1.6 -> 1, -1.6 -> -1.

The default is trunc_zero.

Format string. Date, Time, and Timestamp functions that take a format string (e.g., timetostring(time,
stringformat)) need to have the date format specified. The format strings are described in “Date and time
formats” on page 30.

Where your dates, times, or timestamps convert to or from ustrings, WebSphere DataStage will pick this
up automatically. In these cases the separators in your format string (for example, `:’ or `-’) can
themselves be Unicode characters.

fix_zero. By default decimal numbers comprising all zeros are treated as invalid. If the string fix_zero is
specified as a second argument, then all zero decimal values are regarded as valid.

Type `casting’ functions

There is a special class of type conversion function to help you when performing mathematical
calculations using numeric fields. For example, if you have a calculation using an output column of type
float derived from an input column of type integer in a Parallel Transformer stage the result will be
derived as an integer regardless of its float type. If you want a non-integral result for a calculation using
integral operands, you can use the following functions (which act in a similar way as casting in C) to cast
the integer operands into non-integral operands:

Name Description Arguments Output

AsDouble Treat the given number as a number (number) number (double)
double

602 Parallel Job Developer Guide

Name Description Arguments Output
AsFloat Treat the given number as a number (number) number (float)
float
AsInteger Treat the given number as number (number) number (int)
an integer

Utility functions
The following table lists the functions available in the Utility category (square brackets indicate an
argument is optional):

Name Description Arguments Output

GetEnvironment Returns the value of the environment variable result (string)
given environment variable (string)
NextSKChain Returns the value of the value (number) result (int64)
surrogate key column for
the next record in the chain,
or value for the newest
record
NextSurrogateKey Returns the value of the None result (int64)
next surrogate key
PrevSKChain Returns the value of the value (number) result (int64)
surrogate key column for
the previous record in the
chain, or value for the first
record

Appendix B. Functions 603

604 Parallel Job Developer Guide
Appendix C. Fillers
Fillers are created when you load columns from COBOL file definitions that represent simple or complex
flat files. Since these file definitions can contain hundreds of columns, you can choose to collapse
sequences of unselected columns into FILLER items. This maintains the byte order of the columns, and
saves storage space and processing time.

This appendix gives examples of filler creation for different types of COBOL structures, and explains how
to expand fillers later if you need to reselect any columns.

Creating fillers
Unlike other parallel stages, Complex Flat File stages have stage columns. You load columns on the
Records tab of the Complex Flat File Stage page.

First, you select a table from the Table Definitions window. Next, you select columns from the Select
Columns From Table window. This window has an Available columns tree that displays COBOL
structures such as groups and arrays, and a Selected columns list that displays the columns to be loaded
into the stage. The Create fillers check box is selected by default.

When columns appear on the Records tab, FILLER items are shown for the unselected columns. FILLER
columns have a native data type of CHARACTER and a name of FILLER_XX_YY, where XX is the start
offset and YY is the end offset. Fillers for elements of a group array or an OCCURS DEPENDING ON
(ODO) column have the name of FILLER_NN, where NN is the element number. The NN begins at 1 for
the first unselected group element and continues sequentially. Any fillers that follow an ODO column are
also numbered sequentially.

Level numbers of column definitions, including filler columns, are changed after they are loaded into the
Complex Flat File stage. However, the underlying structure is preserved.

Filler creation rules

The rules for filler creation are designed to preserve the storage length of all columns that are replaced by
a filler column. They allow a filler column to be expanded back to the original set of defining columns,
each having the correct name, data type, and storage length.

The basic filler creation rules are:

1. A filler column will replace one or more original columns with a storage length that is equal to the
sum of the storage length of each individual column that is being replaced.
2. Separate fillers are created when column level numbers decrease. For example, if an unselected
column at level 05 follows an unselected column at level 10, separate fillers are created for the
columns at the 05 and 10 levels.
3. Any ODO column and its associated `depending on’ column will be automatically selected and not
replaced by a filler column.
4. If a REDEFINE column is selected, the column that it is redefining is also automatically selected and
will not be included as part of a filler column.
5. If two fillers share the same storage offset (such as for a REDEFINE) the name of the subsequent
fillers will be FILLER_XX_YY_NN, where NN is a sequential number that begins at 1.
6. If the starting or ending column for a filler is the child of a parent that contains an OCCURS clause,
then the generated FILLER name will be FILLER_NN instead of FILLER_XX_YY.

© Copyright IBM Corp. 2006 605

The remaining rules are explained through the following set of examples.

Filler creation examples

The following examples explain filler creation for groups, REDEFINES, and arrays using different
scenarios for column selection. The source table contains single columns, a group that redefines a column,
a nested group with an array, and a column that redefines another column:
05 A PIC X(1).
05 B PIC X(8).
05 GRP1 REDEFINES B.
10 C1 PIC X(1).
10 C2 PIC X(1).
10 GRP2 OCCURS 2 TIMES.
15 D1 PIC X(1).
15 D2 PIC X(1).
15 D3 PIC X(1).
05 E PIC X(1).
05 F PIC 9(1) REDEFINES E.
05 G PIC X(1).

Select a simple column

Suppose a simple column, A, is selected from the table. On the Columns tab, a single filler is created with
the name FILLER_2_11 and a length of 10. The length represents the sum of the lengths of columns B (8),
E (1), and G (1). GRP1 and its elements, along with column F, are excluded because they redefine other
columns that were not selected.

The file layout is:

Column Picture Clause Starting column Ending column Storage length

A PIC X(1). 1 1 1
FILLER_2_11 PIC X(10). 2 11 10

Select a column that is redefined by a group

Suppose column B is selected, which is redefined by GRP1. Two fillers are created, one for column A and
the other for columns E and G. Since GRP1 redefines column B, it is dropped along with its elements.
Column F is also dropped because it redefines column E. The dropped columns will be available during
filler expansion (see “Expanding fillers” on page 611 ).

The file layout is:

Column Picture Clause Starting column Ending column Storage length

FILLER_1_1 PIC X(1). 1 1 1
B PIC X(8). 2 9 8
FILLER_2_11 PIC X(2). 10 11 2

Select a group column that redefines a column

Next, suppose a group column is selected (GRP1) that redefines another column (B). This time three
fillers are created: one for column A, one for columns C1 through D3 (which are part of GRP1), and one
for columns E and G. Column B is preserved since it is redefined by the selected group column.

606 Parallel Job Developer Guide

The file layout is:

Column Picture Clause Starting column Ending column Storage length

FILLER_1_1 PIC X(1). 1 1 1
B PIC X(8). 2 9 8
GRP1 REDEFINES B. 2 9 8
FILLER_2_9 PIC X(8). 2 9 8
FILLER_10_11 PIC X(2). 10 11 2

Select a group element

Consider what happens when a group element (C1) is selected by itself. Three fillers are created: one for
column A, one for columns C2 through D3, and one for columns E and G. Since an element of GRP1 is
selected and GRP1 redefines column B, both column B and GRP1 are preserved.

The file layout is:

Column Picture Clause Starting column Ending column Storage length

FILLER_1_1 PIC X(1). 1 1 1
B PIC X(8). 2 9 8
GRP1 REDEFINES B. 2 9 8
C1 PIC X(1). 2 2 1
FILLER_3_9 PIC X(7). 3 9 7
FILLER_10_11 PIC X(2). 10 11 2

The next example shows what happens when a different group element is selected, in this case, column
C2. Four fillers are created: one for column A, one for column C1, one for GRP2 and its elements, and
one for columns E and G. Column B and GRP1 are preserved for the same reasons as before.

The file layout is:

Column Picture Clause Starting column Ending column Storage length

FILLER_1_1 PIC X(1). 1 1 1
B PIC X(8). 2 9 8
GRP1 REDEFINES B. 2 9 8
FILLER_2_2 PIC X(1). 2 2 1
C2 PIC X(1). 3 3 1
FILLER_4_9 PIC X(6). 4 9 6
FILLER_10_11 PIC X(2). 10 11 2

Select a group array column

Consider what happens when a group array column (GRP2) is selected and passed as is. Four fillers are
created: one for column A, one for columns C1 and C2, one for columns D1 through D3, and one for
columns E and G. Since GRP2 is nested within GRP1, and GRP1 redefines column B, both column B and
GRP1 are preserved.

Appendix C. Fillers 607

The file layout is:

Column Picture Clause Starting column Ending column Storage length

FILLER_1_1 PIC X(1). 1 1 1
B PIC X(8). 2 9 8
GRP1 REDEFINES B. 2 9 8
FILLER_2_3 PIC X(2). 2 3 2
GRP2 OCCURS 2 TIMES. 4 9 6
FILLER_1 PIC X(3).
FILLER_10_11 PIC X(2). 10 11 2

If the selected array column (GRP2) is flattened, both occurrences (GRP2 and GRP2_2) are loaded into the
stage. The file layout is:

Column Picture Clause Starting column Ending column Storage length

FILLER_1_1 PIC X(1). 1 1 1
B PIC X(8). 2 9 8
GRP1 REDEFINES B. 2 9 8
FILLER_2_3 PIC X(2). 2 3 2
GRP2 4 6 3
FILLER_1 PIC X(3). 4 6 3
GRP2_2 7 9 3
FILLER_1_2 PIC X(3). 7 9 3
FILLER_10_11 PIC X(2). 10 11 2

Select an array element

Suppose an element (D1) of a group array is selected. If the array GRP2 is passed as is, fillers are created
for column A, columns C1 and C2, columns D2 and D3, and columns E and G. Column B, GRP1, and
GRP2 are preserved for the same reasons as before.

The file layout is:

Column Picture Clause Starting column Ending column Storage length

FILLER_1_1 PIC X(1). 1 1 1
B PIC X(8). 2 9 8
GRP1 REDEFINES B. 2 9 8
FILLER_2_3 PIC X(2). 2 3 2
GRP2 OCCURS 2 TIMES. 4 9 6
D1 PIC X(1). 1
FILLER_1 PIC X(2). 2
FILLER_10_11 PIC X(2). 10 11 2

608 Parallel Job Developer Guide

Select a column that is redefined by another column
Consider what happens when column E is selected, which is redefined by another column. Two fillers are
created: one for columns A through D3, and another for column G. Since column F redefines column E, it
is dropped, though it will be available for expansion (see “Expanding fillers” on page 611 ).

The file layout is:

Column Picture Clause Starting column Ending column Storage length

FILLER_1_9 PIC X(9). 1 9 9
E PIC X(1). 10 10 1
FILLER_10_11 PIC X(1). 11 11 1

Now suppose the REDEFINE column (F) is selected. In this case column E is preserved since it is
redefined by column F. One filler is created for columns A through D3, and another for column G. The
file layout is:

Column Picture Clause Starting column Ending column Storage length

FILLER_1_9 PIC X(9). 1 9 9
E PIC X(1). 10 10 1
F PIC 9(1) REDEFINES 10 10 1
E.
FILLER_11_11 PIC X(1). 11 11 1

Select multiple redefine columns

This example describes how fillers are created for multiple redefine columns. In this case the same
column is being redefined multiple times. The source table contains a column and a group that redefine
column A, as well as two columns that redefine the group that redefines column A:
05 A PIC X(100).
05 B PIC X(11) REDEFINES A.
05 GRP1 REDEFINES A.
10 C1 PIC X(10).
10 C2 PIC 9(1).
05 D PIC X(1) REDEFINES GRP1.
05 E PIC 9(1) REDEFINES GRP1.
05 F PIC X(1).

If columns C2 and E are selected, four fillers are created: one for column B, one for column C1, one for
column D, and one for column F. Since an element of GRP1 is selected and GRP1 redefines column A,
both column A and GRP1 are preserved. The first three fillers have the same start offset because they
redefine the same storage area.

The file layout is:

Column Picture Clause Starting column Ending column Storage length

A PIC X(100). 1 100 100
FILLER_1_11 PIC X(11) REDEFINES A. 1 11 11
GRP1 REDEFINES A. 1 11 11
FILLER_1_10 PIC X(10). 1 10 10
C2 PIC 9(1). 11 11 1

Appendix C. Fillers 609

Column Picture Clause Starting column Ending column Storage length
FILLER_1_1 PIC X(1). REDEFINES GRP1. 1 1 1
E PIC 9(1) REDEFINES GRP1. 1 1 1
FILLER_101_101 PIC X(1). 101 101 1

Select multiple cascading redefine columns

This example shows filler creation for multiple redefine columns, except this time they are cascading
redefines instead of redefines of the same column. Consider the following source table, where column B
redefines column A, GRP1 redefines column B, column D redefines GRP1, and column E redefines
column D:
05 A PIC X(100).
05 B PIC X(11) REDEFINES A.
05 GRP1 REDEFINES B.
10 C1 PIC X(10).
10 C2 PIC 9(1).
05 D PIC X(2) REDEFINES GRP1.
05 E PIC 9(1) REDEFINES D.
05 F PIC X(1).

If columns C2 and E are selected, this time only two fillers are created: one for column C1 and one for
column F. Column A, column B, GRP1, and column D are preserved because they are redefined by other
columns.

The file layout is:

Column Picture Clause Starting column Ending column Storage length

A PIC X(100). 1 100 100
B PIC X(11) REDEFINES A. 1 11 11
GRP1 REDEFINES B. 1 11 11
FILLER_1_10 PIC X(10). 1 10 10
C2 PIC 9(1). 11 11 1
D PIC X(2). REDEFINES GRP1. 1 2 2
E PIC 9(1) REDEFINES D. 1 1 1
FILLER_101_101 PIC X(1). 101 101 1

Select an OCCURS DEPENDING ON column

The final example how an ODO column is handled. Suppose the source table has the following structure:
05 A PIC X(1).
05 B PIC X(8).
05 GRP1 REDEFINES B.
10 C1 PIC X(1).
10 C2 PIC 9(1).
10 GRP2 OCCURS 0 TO 2 TIMES DEPENDING ON C2.
15 D1 PIC X(1).
15 D2 PIC X(1).
15 D3 PIC X(1).
05 E PIC X(1).
05 F PIC 9(1) REDEFINES E.
05 G PIC X(1).

610 Parallel Job Developer Guide

If column B is selected, four fillers are created. The file layout is:

Column Picture Clause Starting column Ending column Storage length

FILLER_1_1 PIC X(1). 1 1 1
B PIC X(8). 2 9 8
GRP1 REDEFINES B. 2 9 8
FILLER_2_2 PIC X(1). 2 2 1
C2 PIC 9(1). 3 3 1
GRP2 OCCURS 0 TO 2 TIMES 4 9 6
DEPENDING ON C2.
FILLER_1 PIC X(3). 3
FILLER_2 PIC X(2). 10 11 2

Fillers are created for column A, column C1, columns D1 through D3, and columns E and G. GRP1 is
preserved because it redefines column B. Since GRP2 (an ODO column) depends on column C2, column
C2 is preserved. GRP2 is preserved because it is an ODO column.

Expanding fillers
After you select columns to load into a Complex Flat File stage, the selected columns and fillers appear
on the Records tab on the Stage page. If you need to reselect any columns that are represented by fillers,
it is not necessary to reload your table definition. An Expand filler option allows you to reselect any or
all of the columns from a given filler.

To expand a filler, right-click the filler column in the columns tree and select Expand filler from the
pop-up menu. The Expand Filler window opens. The contents of the given filler are displayed in the
Available columns tree, allowing you to reselect the columns that you need.

Suppose the Records tab contains the following columns:

FILLER_1_1
B
GRP1
FILLER_2_9
FILLER_10_11

If you expand FILLER_2_9, the Available columns tree in the Expand Filler window displays the
contents of FILLER_2_9:
C1
C2
GRP2(2)
D1
D2
D3

If you select column C1, the Records tab changes to this:

FILLER_1_1
B
GRP1
C1
FILLER_3_9
FILLER_10_11

If you expand FILLER_3_9 and select column C2, the Records tab now changes to this:

Appendix C. Fillers 611

FILLER_1_1
B
GRP1
C1
C2
FILLER_4_9
FILLER_10_11

If you continue to expand the fillers, eventually the Records tab will contain all of the original columns in
the table:
A
B
GRP1
C1
C2
GRP2
D1
D2
D3
E
F
G

612 Parallel Job Developer Guide

Accessing information about IBM
IBM has several methods for you to learn about products and services.

You can find the latest information on the Web at www.ibm.com/software/data/integration/

info_server/:
v Product documentation in PDF and online information centers
v Product downloads and fix packs
v Release notes and other support documentation
v Web resources, such as white papers and IBM Redbooks™
v Newsgroups and user groups
v Book orders

To access product documentation, go to this site:

publib.boulder.ibm.com/infocenter/iisinfsv/v8r0/index.jsp

You can order IBM publications online or through your local IBM representative.
v To order publications online, go to the IBM Publications Center at www.ibm.com/shop/publications/
order.
v To order publications by telephone in the United States, call 1-800-879-2755.

To find your local IBM representative, go to the IBM Directory of Worldwide Contacts at
www.ibm.com/planetwide.

Contacting IBM
You can contact IBM by telephone for customer support, software services, and general information.

Customer support

To contact IBM customer service in the United States or Canada, call 1-800-IBM-SERV (1-800-426-7378).

Software services

To learn about available service options, call one of the following numbers:
v In the United States: 1-888-426-4343
v In Canada: 1-800-465-9600

General information

To find general information in the United States, call 1-800-IBM-CALL (1-800-426-2255).

Go to www.ibm.com for a list of numbers outside of the United States.

Accessible documentation
Documentation is provided in XHTML format, which is viewable in most Web browsers.

© Copyright IBM Corp. 2006 613

XHTML allows you to view documentation according to the display preferences that you set in your
browser. It also allows you to use screen readers and other assistive technologies.

Syntax diagrams are provided in dotted decimal format. This format is available only if you are accessing
the online documentation using a screen reader.

Providing comments on the documentation

Please send any comments that you have about this information or other documentation.

Your feedback helps IBM to provide quality information. You can use any of the following methods to
provide comments:
v Send your comments using the online readers’ comment form at www.ibm.com/software/awdtools/
rcf/.
v Send your comments by e-mail to comments@us.ibm.com. Include the name of the product, the version
number of the product, and the name and part number of the information (if applicable). If you are
commenting on specific text, please include the location of the text (for example, a title, a table number,
or a page number).

614 Parallel Job Developer Guide

Notices and trademarks
Notices
This information was developed for products and services offered in the U.S.A.

IBM may not offer the products, services, or features discussed in this document in other countries.
Consult your local IBM representative for information on the products and services currently available in
your area. Any reference to an IBM product, program, or service is not intended to state or imply that
only that IBM product, program, or service may be used. Any functionally equivalent product, program,
or service that does not infringe any IBM intellectual property right may be used instead. However, it is
the user’s responsibility to evaluate and verify the operation of any non-IBM product, program, or
service.

IBM may have patents or pending patent applications covering subject matter described in this
document. The furnishing of this document does not grant you any license to these patents. You can send
license inquiries, in writing, to:

IBM Director of Licensing

IBM Corporation
North Castle Drive
Armonk, NY 10504-1785 U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property
Department in your country or send inquiries, in writing, to:

IBM World Trade Asia Corporation

Licensing 2-31 Roppongi 3-chome, Minato-ku
Tokyo 106-0032, Japan

The following paragraph does not apply to the United Kingdom or any other country where such
provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION
PROVIDES THIS PUBLICATION ″AS IS″ WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR
IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some
states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this
statement may not apply to you.

This information could include technical inaccuracies or typographical errors. Changes are periodically
made to the information herein; these changes will be incorporated in new editions of the publication.
IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this
publication at any time without notice.

Any references in this information to non-IBM Web sites are provided for convenience only and do not in
any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of
the materials for this IBM product and use of those Web sites is at your own risk.

IBM may use or distribute any of the information you supply in any way it believes appropriate without
incurring any obligation to you.

© Copyright IBM Corp. 2006 615

Licensees of this program who wish to have information about it for the purpose of enabling: (i) the
exchange of information between independently created programs and other programs (including this
one) and (ii) the mutual use of the information which has been exchanged, should contact:

IBM Corporation
J46A/G4
555 Bailey Avenue
San Jose, CA 95141-1003 U.S.A.

Such information may be available, subject to appropriate terms and conditions, including in some cases,
payment of a fee.

The licensed program described in this document and all licensed material available for it are provided
by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or
any equivalent agreement between us.

Any performance data contained herein was determined in a controlled environment. Therefore, the
results obtained in other operating environments may vary significantly. Some measurements may have
been made on development-level systems and there is no guarantee that these measurements will be the
same on generally available systems. Furthermore, some measurements may have been estimated through
extrapolation. Actual results may vary. Users of this document should verify the applicable data for their
specific environment.

Information concerning non-IBM products was obtained from the suppliers of those products, their
published announcements or other publicly available sources. IBM has not tested those products and
cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM
products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of
those products.

All statements regarding IBM’s future direction or intent are subject to change or withdrawal without
notice, and represent goals and objectives only.

This information is for planning purposes only. The information herein is subject to change before the
products described become available.

This information contains examples of data and reports used in daily business operations. To illustrate
them as completely as possible, the examples include the names of individuals, companies, brands, and
products. All of these names are fictitious and any similarity to the names and addresses used by an
actual business enterprise is entirely coincidental.

COPYRIGHT LICENSE:

This information contains sample application programs in source language, which illustrate programming
techniques on various operating platforms. You may copy, modify, and distribute these sample programs
in any form without payment to IBM, for the purposes of developing, using, marketing or distributing
application programs conforming to the application programming interface for the operating platform for
which the sample programs are written. These examples have not been thoroughly tested under all
conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these
programs.

Each copy or any portion of these sample programs or any derivative work, must include a copyright
notice as follows:

© (your company name) (year). Portions of this code are derived from IBM Corp. Sample Programs. ©
Copyright IBM Corp. _enter the year or years_. All rights reserved.

616 Parallel Job Developer Guide

If you are viewing this information softcopy, the photographs and color illustrations may not appear.

Trademarks
IBM trademarks and certain non-IBM trademarks are marked at their first occurrence in this document.

See http://www.ibm.com/legal/copytrade.shtml for information about IBM trademarks.

The following terms are trademarks or registered trademarks of other companies:

Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun
Microsystems, Inc. in the United States, other countries, or both.

Microsoft®, Windows®, Windows NT®, and the Windows logo are trademarks of Microsoft Corporation in
the United States, other countries, or both.

Intel®, Intel Inside® (logos), MMX and Pentium® are trademarks of Intel Corporation in the United States,
other countries, or both.

UNIX is a registered trademark of The Open Group in the United States and other countries.

Linux is a trademark of Linus Torvalds in the United States, other countries, or both.

Other company, product or service names might be trademarks or service marks of others.

Notices and trademarks 617

618 Parallel Job Developer Guide
Index
A Complex Flat File stages (continued)
editing (continued)
external source stage output
properties 133
accessibility 614 as a target 164 external target stage 143
Advanced tab Inputs page 61 fillers 159 external target stage input
Advanced tab Ouputs page 65 output column selection 161 properties 145
advanced tab, stage page 43 array columns 161
after-stage subroutines group columns 163
for Transformer stages 190, 196
aggragator stage 205
overview 157
record definitions 158
F
aggragator stage properties 209 file set output properties 112
reject links 165
arrays file set stage 99
compress stage 283
load options 160 file set stage input properties 101
compress stage properties 284
output column selection 161 filler creation and expansion 159, 605
configuration file editor 551
automatic type conversions 303 fillers
constraints
creation 605
output link 164
examples 606
record ID 160
B contacting IBM 613
array element 608
column redefined by a group 606
before-stage subroutines containers 36
column redefined by another
for Transformer stages 190, 196 copy stage 291, 319
column 609
copy stage properties 297
group array column 607
group column that redefines a
C D
column 606
change apply stage 341 group element 607
change apply stage properties 344 data set 24 multiple cascading redefine
change capture stage 331 data set stage 67 columns 610
change capture stage properties data set stage input properties 69 multiple redefine columns 609
properties data set stage output properties 71 OCCURS DEPENDING ON
change capture stage 322, 333 data types 26 column 610
cluster systems 1 complex 29 simple column 606
column auto-match facility 174, 193, 245 database sequences 401 expansion 611
column export stage 425 creating 401 in Complex Flat File stages 159
column export stage properties deleting 402 overview 605
properties date format 30 rules for creation 605
column export stage 429 DB2 partition properties 49 Find and Replace dialog box 171, 191,
column generator stage 301, 525 decode stage 371 243
column generator stage properties 303, decode stage properties 371 format string 30, 34, 36
528 defining format tab, inputs page 49
column import stage 415 local stage variables 177, 197 FTP Enterprise stage 383
column import stage properties difference stage 351 FTP Enterprise stage output
properties difference stage properties 353 properties 390
column import stage 377, 418 documentation functions 593
columns tab, inputs page 50 accessible 614 funnel stage 267
columns tab, outputs page 63 ordering 613 funnel stage properties 271
combine records stage 455 Web site 613
combine records stage properties 460
comments on documentation 614 G
compare stage 359, 361 E general tab, inputs page 47
compare stage properties 361 editing general tab, outputs page 62
complex data types 29 Transformer stages 171, 190, 242 general tab, stage page 41
Complex Flat File stages encode stage 367, 368 Generic stage 395
arrays encode stage properties 368 generic stage properties 396
load options 160 examples
output column selection 161 Development Kit program 585
column definitions 158
loading columns 159
expand stage 287
expand stage properties 287
H
typing columns 159 head stage 489
expression editor 178, 250
constraints head stage properties 492
Expression Editor 198
output link 164 external fileter stage 327
record ID 160 external fileter stage properties 327
editing external source stage 131
as a source 157

© Copyright IBM Corp. 2006 619

I P reject links (continued)
in Complex Flat File stages 165
input links 170, 189 parallel engine configuration file 551 remove duplicates stage 277, 279
inputs page 44, 47 partial schemas 26 remove duplicates stage properties 279
columns tab 50 partitioning tab, inputs page 47 restructure operators
format tab 49 peek stage 395, 513 splitvect 481
general tab 47 Peek stage 395, 513 row generator stage 519
partitioning tab 47 peek stage properties 514 row generator stage output
properties tab 47 PFTP operator properties 524
restartability 383 runtime column propagation 25, 63, 98,
promote subrecord stage 465 423, 439
J promote subrecord stage properties 469
properties 279, 368
join stage 219
aggragator stage 209
join stage properties 223
change apply stage 344 S
combine records stage 460 sample stage 503
compare stage 361 sample stage properties 508
K compress stage 284 schema files 26
key source copy stage 297 screen readers 614
creating 401 data set stage input 69 sequential file input properties 78
deleting 402 data set stage output 71 sequential file output properties 88, 390
decode stage 371 sequential file stage 73
difference stage 353 shared containers 36
L expand stage 287
external fileter stage 327
shortcut menus in Transformer
Editor 169, 188, 241
legal notices 615 Slowly Changing Dimension stages
external source stage output 133
level number 50 column derivations 411
external stage input 145
link ordering tab, stage page 44 dimension update action 412
file set input 101
links editing 409
file set output 112
input 170, 189 job design 405
funnel stage 271
output 170, 189 mapping output data 412
generic stage 396
reject 170, 189 match condition 410
head stage 492
specifying order 177, 197, 245 overview 405
join stage 223
lookup file set stage 121 purpose codes
lookup file set stage output 128
lookup file set stage output selection 410
make subrecord stage 445
properties 128 types 410
make vector stage 477
lookup stage 235 usage 408
merge stage 229
range lookups 250 surrogate keys 408, 411
peek stage 514
promote subrecord stage 469 SMP systems 1
sample stage 508 sort stage 253
M sequential file input 78 sort stage properties 259
make subrecord stage 441 sequential file output 88, 390 split subrecord stage 449
make subrecord stage properties 445 sort stage 259 split subrecord stage properties 452
make vector stage 473, 477 split subrecord stage 452 split vector stage 481
make vector stage properties 477 split vector stage 484 split vector stage properties 484
mapping tab, outputs page 64 tail stage 499 splitvect restructure operator 481
merge stage 227 trnsformer stage 179, 251 stage editors 37
merge stage properties 229 write range map stage input stage page 41
meta data 25 properties 535 advanced tab 43
MPP systems 1 properties tab, inputs page 47 general tab 41
Must Do’s 384 properties tab, outputs page 62 link ordering tab 44
properties tab, stage page 42 properties tab 42
propertiesrow generator stage stage validation errors 41
N output 524
prperties
stages
editing
Nulls Sequential File 121
column generator stage 303, 528
handling in Transformer stage input FTP Enterprise 383
purpose codes
columns 176 sequential file 73
selection 410
types 410 state files 401
usage 408 creating 401
O deleting 402
output links 170, 189 updating 402
outputs page 62
columns tab 63
R subrecords 30
Surrogate Key Generator stages
range lookups 250 creating the key source 401
general tab 62
range partition properties 49 deleting the key source 402
mapping tab 64
readers’ comment form 614 generating surrogate keys 402
properties tab 62
reject links 170, 189 overview 401

620 Parallel Job Developer Guide

Surrogate Key Generator stages
(continued)
updating the state file 402
surrogate keys
creating the key source 401
deleting the key source 402
generating
in Slowly Changing Dimension
stages 408, 411
in Surrogate Key Generator
stages 402
overview 401
updating the state file 402
switch stage 375

T
table definitions 25
tagged subrecords 30
tail stage 497
tail stage properties 499
time format 34
timestamp format 36
toolbars
Transformer Editor 168, 187, 240
trademarks 617
Transformer Editor
link area 168, 188, 241
meta data area 169, 188, 241
shortcut menus 169, 188, 241
toolbar 168, 187, 240
transformer stage 167
transformer stage properties 179, 251
Transformer stages
basic concepts 170, 189, 242
editing 171, 190, 242
Expression Editor 198
specifying after-stage
subroutines 196
specifying before-stage
subroutines 196
type conversion functions 305
type conversions 303

U
UniVerse stages 73, 383
USS systems 1, 539

V
vector 30
visual cues 41

W
write range map stage 533
write range map stage input
properties 535

Z
z/OS systems 539

Index 621
622 Parallel Job Developer Guide


Printed in USA

SC18-9891-00
Spine information:

IBM WebSphere DataStage and QualityStage Version 8 Parallel Job Developer Guide