) To create a new subgraph:

1. From the Insert menu, choose Empty Subgraph.

The New Empty Subgraph dialog appears with Graph in the New Graph Name box.

2. In the New Graph Name box, enter the name you want to use for this subgraph.

3. Click OK.

The New Empty Subgraph dialog disappears, and an empty subgraph icon, labelled with the name you entered in

4. Double-click the empty subgraph.

The subgraph expands to become the subgraph drawing sheet.

5. Create the subgraph inside the drawing sheet by inserting components from the Component Organizer and

connecting them with flows. 6. Add ports to the subgraph.

Observe the following considerations that are specific to a subgraph:

Connect the input port(s) of the component(s) you want to receive the subgraph's input to the left edge of the drawing sheet.

An in port appears on the outside of the drawing sheet at the connection point. Connect diagnostic ports, which are on the bottom edges of the Ab Initio pre-built components, to the bottom edge of the drawing sheet.

An out port appears on the outside of the drawing sheet at each connection point.

Connect the output port(s) of the component(s) you want to produce the subgraph's output to the right edge of the drawing sheet.

An out port appears on the outside of the drawing sheet at the connection point. 7. If you want to, create parameters for the subgraph.

Creating a Subgraph from an Existing Graph

Saving a Subgraph as a Component

Creating Parameters for Subgraphs

Viewing Subgraphs

Editing Subgraphs

"

#

To create a subgraph from components in an existing graph:

1. In an existing graph, select the components you want to be part of the subgraph. 2. On the GDE menu bar, choose Edit > Subgraph > Create from Selection

The Create Subgraph from Selection dialog opens.

3. Enter a name for the subgraph in the New Graph Name box.

You can use alphanumeric characters, numbers, and special characters such as underscores in the name. NOTE: Non-alphanumeric characters are eliminated when you deploy the graph.

The GDE moves selected components from the active graph into a subgraph. Ports on the new subgraph replace interrupted flows. If the selected component is the outermost graph itself, this command wraps a new graph around it. Subgraph components have a double-line border for easy identification, as follows:

4. If you want to, create parameters for the subgraph.

Creating a New Subgraph

Saving a Subgraph as a Component

Creating Parameters for Subgraphs

Viewing Subgraphs

Adding Ports to a Subgraph

Editing Subgraphs

'

"

When you build a subgraph, it becomes a part of the graph in which you build it. If you want to use it in other graphs, or in other places in the original graph, you need to save it as a component.

To save a subgraph as a component:

1. If you do not have a components folder in your sandbox, do the following:

a. Create a components folder, and a parameter with which to reference it, in your sandbox.

b. Add the components folder to the Component Organizer as a top-level folder (see Add Top-level Folder for details).

2. Select the subgraph.

3. From the File menu, choose Save Component "subgraph_name" As.

4. Navigate to the components folder in your sandbox.

5. In the Save as type text box, choose Program Components (*.mpc, *.mp).

6. Click Save.

NOTE: This operation does not affect the containing graph, and does not save it. You must save the full graph separately. You may need to right-click the components folder you added to the Component Organizer and then click Refresh Folder on the shortcut menu before the subgraph will appear in the components folder. Once the subgraph appears, you can drag it from the Component Organizer into any graph in which you want to use it, just as you would a pre-built component.

NOTE: You can add custom help to a subgraph that you save as a component.

A subgraph you save in this way becomes a linked subgraph. If you insert an instance of such a subgraph into a graph from the Component Organizer and then double-click it, the GDE displays (linked) following the name of the subgraph. In GDE 1.5 and later, if you make changes to a linked subgraph, you can update the instances of that subgraph in existing graphs, as long as you originally inserted those instances from the Component Organizer.

1. Save the desired changes to the subgraph in the Component Organizer that you used to create the graph.

2. Select the instances of the subgraph you want to update in the graph. 3. From the GDE Edit menu, choose Update.

Creating a New Subgraph

Creating a Subgraph from an Existing Graph

Creating Parameters for Subgraphs

Viewing Subgraphs

Adding Ports to a Subgraph

Editing Subgraphs

"

You can create parameters for a subgraph by: Using the Graph Parameters Editor

Using the Create button on the Parameters tab of the Properties dialog

Exporting parameters from a component within the subgraph.

When you export a parameter from a component in a subgraph, the GDE creates a new parameter for the containing subgraph. The value you set for this parameter determines the value of all internal parameters exported under that name. Components in a subgraph can share exported parameters.

%/

1 (##1 . 1# *#1#

-#

1 2

You can use parameters in a subgraph to make the subgraph reusable. For example, suppose:

You have a subgraph that reads a file of records, performs some complex transformation on the records, and generates a log file within the subgraph to keep track of how many records it processes.

You want to use this subgraph in several different graphs, and want each instance of the subgraph to produce a separate log file with a unique name.

To accomplish this, create a formal parameter for the subgraph, and use a $ reference to that parameter as the URL of the log file within the subgraph. Then, when you construct a graph using the subgraph, the GDE will prompt you for a value for the formal subgraph parameter. The value you supply becomes the URL of the log file.

To create the parameter and the $ reference, do the following:

1. In the Graph Parameters Editor, add a parameter named logname to the subgraph. 2. In the Scope column, specify Formal, and leave the Value column blank.

This creates a parameter that requires a value from the user or developer of the graph.

3. On the Description tab of the File Properties dialog for the log file, specify the URL as $logname.

For each instance of the subgraph, you can set logname to a different pathname. The $ reference in the log file will use this pathname as the URL for the file.

1# .-0%/

1 (#*#1 1#+#1#/ #

To resolve parameter references, the GDE uses the first value it finds as it progresses through the following: The component containing the referencing parameter

The containing graph and any of its container graphs A top-level graph parameter

A project parameter

A parameter of any common projects included by the project A shell variable defined in a Host Profile's Setup commands A Unix environment variable

NOTE: In releases 1.7 and earlier, $ identifier referred to a shell environment variable not a subgraph parameter. If the GDE detects a possible conflict, it uses Legacy 1.7 Code Generation by default. To disable this, select Run > Settings and

click the Script tab. Clear the Legacy 1.7 Code Generation checkbox.

For additional information on references, refer to $ substitution and ${} substitution.

Creating a New Subgraph

Creating a Subgraph from an Existing Graph

Saving a Subgraph as a Component

Viewing Subgraphs

Adding Ports to a Subgraph

Editing Subgraphs

0 )

To view the contents of a subgraph:

1. On the Description tab of the Graph Properties dialog for the subgraph, in the Protection area, select Permit View.

2. Double-click the icon for the subgraph in the graph.

A new window opens with the subgraph in it, looking as it does in the following figure:

3. To return to the graph, with the subgraph in its original state, click the Close button in the top right corner of the window.

Creating a New Subgraph

Creating a Subgraph from an Existing Graph

Saving a Subgraph as a Component

Creating Parameters for Subgraphs

Adding Ports to a Subgraph

Editing Subgraphs

To add ports to a subgraph:

1. If it is not open, open the subgraph so you can see its contents.

2. Click a port of a component in the subgraph just as you would to connect a flow. 3. Drag the mouse to the outer frame of the subgraph

A port appears on the outside of the frame of the subgraph. 4. Release the mouse button.

1 2 .1* %/!%/

A port binding associates ports of components in a subgraph with ports of the subgraph itself. You create port bindings automatically when you add ports to a subgraph. In the example below, the dotted gray lines represent the port bindings. The outer port always has the same properties as the inner port.

Creating a New Subgraph

Creating a Subgraph from an Existing Graph

Saving a Subgraph as a Component

Creating Parameters for Subgraphs

Viewing Subgraphs

Editing Subgraphs

#

To edit a subgraph, follow these steps:

1. On the Description tab of the Graph Properties dialog for the subgraph, in the Protection area, select Permit Edit.

2. Do one of the following:

Double-click the subgraph

Select the subgraph and choose Edit > Subgraph from the shortcut menu.

3. Make the changes you want to the contents of the subgraph.

4. On the GDE menu bar, choose File > Save Subgraph or File > Save Subgraph As to save this subgraph for use as a component in another graph.

5. Choose File > Close Subgraph to finish.

Creating a New Subgraph

Creating a Subgraph from an Existing Graph

Saving a Subgraph as a Component

Creating Parameters for Subgraphs

Viewing Subgraphs

Adding Ports to a Subgraph

(

% (

A macro consists of two parts:

A program specification file, also known as an .mpc file

A .ksh script that builds a graph fragment, using the mp commands of the Shell Development Environment. If a macro is the proper solution to your task (see Do I Need a Custom Component, a Subgraph, or a Macro?), see the

following topics:

The Program Specification File

The .ksh script

Example macro

Note that creating a macro is more complicated than creating a subgraph, although there are similarities.

*

"

+

The program specification file (also called the .mpc file) for a macro provides the Co>Operating System with the information it needs to run the macro's .ksh script. Write program specification files as files with .mpc extensions. All program specification files must start with <mpcfile>. The <mpcfile> line is followed by a series of attribute: value lines that describe the attributes of your .ksh script.

See Describing Custom Components in Program Specification Files for detailed descriptions of program specification files and how to write them.

Following are some details that distinguish a program specification file for a macro:

In the program specification file for a macro, you must use the mpname line. The value for this line must begin with @, which tells the Co>Operating System that this is a macro, and then it must specify the complete path to the .ksh script that the macro uses.

You do not use the mpname line for a custom component.

In almost all cases, you will want the port lines to define soc ports, since this is the default Ab Initio interface. The majority of the Ab Initio built-in components, from which you are building the macro, use this interface.

Place the completed program specification file on both the computer running the GDE, and on the run host running the Co>Operating System.

In the GDE, do the following:

a. If you do not have a components folder in your sandbox, create one and a parameter with which to reference it.

b. Place the program specification file in the components folder.

c. Add the components folder to the Component Organizer as a top-level folder (see Add Top-level Folder for details).

NOTE: You can add custom help to a macro that you save in the Component Organizer.

You may need to right-click the components folder you added to the Component Organizer and then click Refresh

Folder on the shortcut menu before the macro will appear in the components folder. Once the macro appears, you

can drag it from the Component Organizer into any graph in which you want to use it, just as you would a pre-built

component.

On the run host, place the file in $AB_HOME/lib, or set the $AB_LAYERED_COMPONENTS_PATH environment variable to the directory where the file resides.

Creating a Macro

The .ksh script

* :

The .ksh script provides the code a macro uses to accomplish its task. In Example macro, there is a sample .ksh script with comments that indicate some points to consider when writing a script.

When you complete the .ksh script, save it on the run host in a directory that is accessible to any Ab Initio graph. This directory must be the one specified in the mp name line of the program specification file.

The simplest way to create the .ksh script for a macro is as follows:

1. In the GDE, construct a graph that performs a function similar to what you want to accomplish with the macro. 2. From the Edit menu, choose Script > Generated Script.

If the "Errors were detected during compilation..." message appears, click No.

The generated script for your graph appears. 3. Modify the generated script as needed.

The lines in the script beginning with mp provide you with the basic mp commands you need for the macro. For more details about writing .ksh scripts, see the Shell Development Environment User's Guide.

Creating a Macro

The Program Specification File

Example macro

# "

"

This section contains an example of a macro that partitions input data records into output files based on the date field in the input record format.

*2# 1. 1 (

# %+% *%./ +%-#

Following is the program specification file that describes to the Co>Operating System the .ksh script used by the macro: <mpcfile>

label: "dynamic function partition to files" mpname: "@$RUNDIR/func-part.ksh"

image: "func-part.ksh"

author: "Ab Initio Software" version: "1.0"

comment: "dynamically function partitions into multiple files by month/year pairing"

port: soc in in 1 1 argument: literal $1

parameter: positional layout special "$layout" "layout of this node" parameter: positional metadata special "$metadata.in" "input metadata"

parameter: positional data_dir literal "" "directory to land files to" required parameter: positional num_files literal "" "number of files to generate (not including overflow)" required

Note the following:

In the mp name line, the @ tells the Co>Operating System that this is a macro. $RUNDIR is an environment variable set to the graph's run directory — at runtime it provides the complete path to the .ksh script.

The argument: literal line tells the Co>Operating System to pass the string from the label line to the .ksh script. The layout and metadata parameters are special parameters that you must use in every macro script. They allow the layout and metadata to propagate from the graph to the macro, so that the components defined in the macro can use the same layout and metadata as the components defined outside the macro.

The other three parameters — data_dir, num_files, and key — will appear as parameters on the Parameters tab of the Properties dialog for the macro in the GDE. The values you enter in these parameters control the following:

data_dir — the destination directory of the data records

num_files— the number of files into which the macro partitions the data records key — the field(s) according to which the macro partitions the records

*2#:7 2

1% *

Following is the .ksh script this macro uses to partition the data records into the number of output files specified in the num_files parameter, according to the key specifier in the key parameter. The program specification file above describes this script — together they create the macro.

This script performs the task given as an example in When to Use a Macro . It creates one output file more than the number in the num_files parameter — the extra file holds all the records from the months earlier than the months specified in the num_files parameter.

The comments in the script indicate some points to consider when writing a script for a macro.

######################################################################### #!/bin/ksh

# Show some usage information in the event that a user forgets one # of the parameters.

######################################################################### if [[ $# -ne 6 ]], then

echo "usage: func-part.ksh <name> <layout> <metadata file> <datadir> <# of months> <key>"

exit 1 fi

######################################################################### # Add the parameters that the Co>Operating System will pass to the

# macro. Note that these are in the order that the parameter lines # are declared in the .mpc file.

######################################################################### macroName=$1 layout=$2 metadata=$3 datadir=$4 num_months=$5 key=$6 ######################################################################### # There are three tasks we need to acomplish in the macro:

# 1- Generate the partition by key expression

# 2- Generate the list of filenames we wish to create

# 3- Define the Ab Initio components that make up the macro #

# 1- ret_string will contain the list of filenames, ie: Mar2000, # Feb2000, etc.

# 2- select_string will contain the function for partitioning, # which will wind up being a large if/else statement that # checks the key field against the year and month for each file # we wish to generate.

######################################################################### set -A month_strings nul Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec select_string="" mon=$(date +"%m") year=$(date +"%Y") ret_string="" count=0 idx=$mon

while [[ $count -lt $num_months ]] do

if [[ $idx -eq 0 ]], then idx=12

year=$((year - 1)) fi

ret_string="$ret_string ${month_strings[$idx]}$year" select_string="if ((date_month($key) == $idx) &&

(date_year($key) == $year)) $((count + 1)) else $select_string" count=$((count + 1))

idx=$((idx - 1)) done

select_string="$select_string 0" set -A filenames $(echo $ret_string)

######################################################################### # Now we begin the actual macro.

######################################################################### mp begin-macro $macroName

######################################################################### # There are a few static components, for which there will always

# be exactly one copy of the component. We include an extra output # file here, for any records that fall outside of the range we're # separating into.

######################################################################### mp function-partition functionPartition "$select_string" -layout $layout mp ofile overflow $datadir/overflow.dat

mp straight-flow flow-ov functionPartition.out overflow.write -metadata $metadata

######################################################################### # Now we iteratively declare all the specific month-associated

In document 39189489 Beyond the Basics 4 (Page 48-76)

"

#

'

"

"

%/

1 (#*#1 *. 1# *#1#

-#

1 2

1# .-0%/

1 (#*#1 1#+#1#/ #

0 )

1 2 .1* %/!%/

#

(

% (

*

"

+

* :

# "

"

*2# 1. 1 (

# %+% *%./ +%-#

*2#:7 2

1% *

1 (##1 . 1# *#1#