HP NonStop Data Transformation Engine Map Designer Reference Guide Abstract This guide tells you how to use the HP NonStop™ Data Transformation Engine (NonStop DTE) Map Designer, the application in the Mercator Design Studio that you use to specify your data transformation logic. Product Version NonStop Data Transformation Engine 6.7.
Document History Part Number Product Version Published 427557-001 NonStop Data Transformation Engine 1.0 December 2000 522443-001 NonStop Data Transformation Engine 5.0.3 November 2001 522443-002 NonStop Data Transformation Engine 6.7.
Contents About This Document Related References.......................................................................................... 12 Chapter 1 - Introduction Overview ...................................................................................................... 13 Using the Map Designer..................................................................................... 13 Installation....................................................................................................
Contents Menu Commands and Tools ................................................................................ 41 Menu Bar ...................................................................................................... 41 File Menu (Alt+F) ....................................................................................... 42 Edit Menu (Alt+E) ....................................................................................... 45 View Menu (Alt+V).............................................
Contents FetchAs ................................................................................................... 89 FetchAs > WorkArea.................................................................................... 90 FetchAs > FetchUnit.................................................................................... 91 GET........................................................................................................ 93 Source .............................................................
Contents Map Rules are Evaluated Independently in Sequential Order................................... 99 Unavailable Rule Cells ...................................................................................... 99 Map Rule for the Entire Output Object ............................................................. 99 Map Rule for Each Component ....................................................................... 99 Entering Map Rules .....................................................................
Contents Chapter 8 - Functional Map Basics Functional Maps.............................................................................................. 99 Input and Output Data May Reflect Each Other................................................... 99 Basic Steps in Using a Functional Map .............................................................. 99 The Functional Map and Execution Map are in the Same Map Source File ................... 99 Two Kinds of Maps...........................................
Contents BurstAudit > Data....................................................................................... 99 BurstAudit > Execution ................................................................................ 99 MapAudit > SummaryAudit ............................................................................ 99 SummaryAudit > Execution ........................................................................... 99 SettingsAudit ..................................................................
Contents Configuring Bursts for Error Recovery.................................................................... 99 Configuring the RUN Function and Bursts ............................................................... 99 Logical or Adapter-Specified FetchUnits ................................................................ 99 Chapter 12 - Managing Maps Standard Windows Capabilities ........................................................................... 99 Moving and Copying Objects by Dragging....
Contents Comparing Objects with Different Names.......................................................... 99 Viewing Map Source File Differences................................................................ 99 Resizing the Map Source File Differences window ................................................ 99 Map differences......................................................................................... 99 Chapter 13 - Building Maps Building Maps...................................................
Contents Data Content Information in the Audit Log ........................................................ 99 Auditing Data Content ...................................................................................... 99 Data Settings in the Audit Log........................................................................ 99 Map Settings in the Audit Log ........................................................................ 99 Auditing a Map ..............................................................
About This Document This document contains information about the Mercator Map Designer. This document assumes that the reader knows the Windows environment, has used the Mercator Design Studio, and understands words such as mapping, type trees, and other basic Mercator terminology. Related References The Mercator Online Library contains information about all products. Refer to the following references for more information about topics frequently discussed in this document.
Chapter 1 - Introduction The Map Designer is a client component of the Design Studio used to develop maps defining input and output specifications and mapping rules that perform data transformation as desired. Overview The Map Designer uses the definitions of data stored in the type trees (that are created using the Type Designer) to specify the transformation logic in the form of map rules. Map rules operate on input data objects and build output data objects.
Chapter 1 - Introduction Installation Installation This product is installed as one of the components of the Mercator installation program. Refer to the Getting Started book for details about the installation program or removing this product from your system. Basic Steps for Building the Desired Output Data Building the desired output data consists of two main steps: 1 Defining the data definitions in the Type Designer. 2 Creating maps in the Map Designer.
Chapter 1 - Introduction Basic Steps for Building the Desired Output Data 4 Create an output card that represents your desired output. 5 In the output card map rules, specify the logic necessary to transform the input data to the desired output data. 6 Build the map. This creates a compiled map file (.mmc). 7 Run the map.
Chapter 2 - Map Designer Basics This chapter introduces the Map Designer file structures, and provides information about working with the graphical user interface. File Name Extensions in the Map Designer The following is a list of the file name extensions used in the Map Designer: Extension File type .bak Map source backup .fnl Master work file .Ixx Input work .log Audit log .mopt Map source options file .mmc Compiled map .mme Map build analysis results .mms Map source .mtr Trace .
Chapter 2 - Map Designer Basics Map Designer Interface Startup window appears which allows you to select the way in which the Map Designer should open. Note The Mercator program folder may be installed and named whatever you choose, the Programs > Mercator > Mercator Design Studio path is the default installation location. The following options are available: ♦ Open an existing map source file Browse for the map source file (.mms). ♦ Create a new map source file Create a new map source file (.mms).
Chapter 2 - Map Designer Basics Map Designer Interface The map source files shown in the Navigator contain maps that include input cards (in the From window) and output cards (in the To window). Configurable toolbars Sizable color-coded Rule Bar that can be docked or floating Navigator window with List or Composition views Additional floating card windows When you create a map source file in the Map Designer, the Save As dialog box appears.
Chapter 2 - Map Designer Basics Navigator Window Navigator Window The Navigator window displays a list of open map source files, the maps contained in those files, and the cards contained in those maps. To view the Navigator, select Navigator from the View menu. The Navigator icons graphically represent all of your opened map source files and the maps that they contain. The Navigator provides a graphical representation of the input and output cards in the maps.
Chapter 2 - Map Designer Basics Navigator Window Navigator Context Menus You can right-click map source files, maps, and cards shown in the Navigator to view the context menus for command access.
Chapter 2 - Map Designer Basics Navigator Window Map Context Menus Card Context Menu Map Designer Reference Guide 21
Chapter 2 - Map Designer Basics Navigator Window Navigator > List view The List view shows the detailed contents of map source files and maps. The List view icons represent map source files, maps, and cards that are displayed alphabetically from top to bottom. The List view presents a detailed list of the open map source files, the maps contained in the map source file, and the input and output cards for each map. Each map source file can be expanded to view all of the maps it contains.
Chapter 2 - Map Designer Basics Navigator Window Navigator > Composition view The Composition view of the Navigator shows how maps are related. The Composition view displays the map source files and maps arranged in a compositional hierarchy. Functional maps appear underneath the executable map that calls them. Map source file Executable map Functional maps Notice that the maps in Composition view are not alphabetically arranged (as they are in List view), but are arranged in a compositional hierarchy.
Chapter 2 - Map Designer Basics Navigator Window To access the context menu, right-click the top border. Showing the Navigator The Navigator can be shown or hidden using the Navigator command on the View menu or from the Navigator’s context menu. To show the Navigator 1 From the View menu, select Navigator. A check mark appears next to Navigator in the View menu indicating that the Navigator is displayed.
Chapter 2 - Map Designer Basics From Window To dock or float the Navigator window 1 Right-click on the Navigator’s top border. 2 From the context menu, select Allow Docking. If a check mark is displayed next to the Allow Docking option in the context menu, the Navigator window can be docked. After selecting Allow Docking, you can toggle between a docked window and a floating window by double-clicking the top border of the Navigator.
Chapter 2 - Map Designer Basics To Window ♦ Access shortcut menus by clicking the areas shown in the following example: Right-click the card title bar to view the context menu to: Edit, Delete, Copy, Convert to Output, Find a type, Print this input card, or get Help. Right-click a data object to view type Properties, Copy the data object name, Show All data objects, Open Type Tree in the Type Designer, or get Help.
Chapter 2 - Map Designer Basics To Window ♦ Float additional output cards in the main window to view different parts of the same card, or two or three different cards. This enables you to: Tip ! View multiple input or multiple output cards of a map at the same time. ! Drag a map rule from one card to another. To map an object from card #1 to card #2, display both cards by dragging one card to the main window. Then drag the data object from card #1 into a rule cell of card #2.
Chapter 2 - Map Designer Basics 2 To Window When splitter cursor appears, drag column to desired size. To Window Shortcut Menus Shortcut menus on the output card provide access to commands for data objects. Three areas of the output card on the To window provide access to the following shortcut menus: ♦ Right-click the title bar of the card. ♦ Right-click the data object name in the Output column. ♦ Right-click the map rule in the Rule column.
Chapter 2 - Map Designer Basics To Window Right-click the title bar of the card to view the context menu to: Edit, Delete, Copy, Convert to Input, Find a type, Print this output card, or get Help.
Chapter 2 - Map Designer Basics To Window To Window Data Object Context Menu To Window Rule Cell Context Menu Floating Additional Cards in the Main Window If the selected map has more than one card displayed in the To window or From window of the Map Designer, cards may be displayed simultaneously by using the float window feature. To float additional cards in the main window 1 Display the cards for the selected map by double-clicking the map in the Navigator.
Chapter 2 - Map Designer Basics 2 To Window Drag a card from the To or From window into the main window. Note Floated cards are view-only. To edit a map rule on an output card, select that card in the To window, not the floated window. Tabs in the Organizer window may also be floated in separate windows. Viewing Choice Groups in the To Window For choice group components that have no rules, but have subcomponents with rules, the component’s rule field appears with a grid pattern.
Chapter 2 - Map Designer Basics Organizer Window Organizer Window The Organizer window contains information about the selected map. The information includes unresolved rules, remarks, audit settings, the trace file, the audit log, and build errors. To view the Organizer window 1 In the Navigator, select the map. 2 From the Map menu, choose Organizer. Each Organizer window displays information about the selected map.
Chapter 2 - Map Designer Basics Organizer Window Remarks Tab You can enter general comments or comments for particular data objects in a map by using the Remarks tab in the Organizer window. Trace Tab A map can be configured to produce a trace file. Use the Trace tab on the Organizer window to view the trace file. Data Audit Settings Tab You can specify that you want to audit a particular object by including that object in the Organizer window on the Data Audit Settings tab.
Chapter 2 - Map Designer Basics Rule Bar Rule Bar The Rule Bar is one of the main components of the Map Designer user interface. The Rule Bar is used to display and enter map rules for the selected object on the output card in the To window. Rule Bar By default, color coding is enabled in the Rule Bar. By default, the Rule Bar is docked beneath the toolbar. The Rule Bar can be resized or it can be undocked (floated) and moved. The Rule Bar is where you enter the map rules for each output data object.
Chapter 2 - Map Designer Basics Rule Bar ♦ To move the Rule Bar, first disable docking (right-click on the Rule Bar border and click Allow Docking to remove the checkmark.) You can then move the Rule Bar window anywhere on the desk top. ♦ To enter the object name of any data object, drag it from the map card into the Rule Bar. You can type in extra spaces in a map rule to make it easier to read. Line feeds are not required, but may improve the way the rules are displayed.
Chapter 2 - Map Designer Basics 2 Movable Windows From the context menu, select Allow Docking. If a check mark is displayed next to the Allow Docking command on the context menu, the rule bar can be docked. 3 After selecting Allow Docking, you can toggle between a docked rule bar and a floating window by double-clicking the top border of the rule bar. 4 Double-click the title bar of the rule bar so that the rule bar is again docked.
Chapter 2 - Map Designer Basics Toolbar To adjust the docking of a window that is docked 1 Right-click on the docked window border and click Allow Docking to turn docking on or off from the context menu. Toolbar The toolbar is a part of the Map Designer window that provides you with quick access to various tools to invoke Map Designer actions while you work with map files and map cards. The left side of the toolbar provides the tools generally available in Window applications.
Chapter 2 - Map Designer Basics Command Tool Toolbar Menu Description Undo Edit Undoes multiple actions Cut Edit Deletes the selection and places a copy on the clipboard Copy Edit Copies the selection to the clipboard Paste Edit Inserts the contents from the clipboard Find Edit Displays the Find dialog box which allows you to locate specified information in the active window New Map Activates the Create New Map dialog box to provide a name for a new map Build Map Builds the selecte
Chapter 2 - Map Designer Basics Command Tool Title Bar Menu Description What’s This? Help Activates the Help cursor so that you can position it over any menu command or object in a window and click, which displays the associated context-level help Use Ellipses none Enables and disables the use ellipse option. The use ellipses option uses ellipses instead of long path names when data objects are dragged to the rule bar.
Chapter 2 - Map Designer Basics Menu Commands and Tools Menu Commands and Tools Actions can be performed in the Map Designer using menu commands, tools, and shortcut keys. Not all menu commands have corresponding tools, and not all tools are represented in the command menus.
Chapter 2 - Map Designer Basics Menu Bar File Menu (Alt+F) The File menu provides the commands that are generally available in Windows applications. Command Shortcut Key Description New Ctrl+N Creates a new map source file (.mms) Open Ctrl+O Opens an existing map source file (.mms) Close Tool none Save Closes the selected map source file (.mms) Ctrl+S Save As none Source Control > none Saves the selected map source file (.
Chapter 2 - Map Designer Basics Command Tool Menu Bar Shortcut Key Description Remove from Source Control Alt+L, R Removes selected file from the source control Show Workfiles Alt+L, F Shows all work files in the project Show History Alt+L, H Shows the history for the selected files Show Alt+L, P Shows properties for the selected file Alt+L, S Refreshes the status on all the files Alt+F, M Shows the results of a comparison of selected map source files Ctrl+P Displays a dialog box that
Chapter 2 - Map Designer Basics Menu Bar Edit Menu (Alt+E) The Edit menu provides the editing commands generally available in Windows applications. It also contains the Find and Replace commands, which are very useful for modifying map attributes.
Chapter 2 - Map Designer Basics Menu Bar View Menu (Alt+V) The commands on the View menu enable you to control what is displayed in your Map Designer environment.
Chapter 2 - Map Designer Basics Menu Bar Command Tool Key Description Copy Data Audit Settings none Alt+M, A Displays the Copy Data Audit Settings dialog box in which you can copy the data audit settings of the selected map to another map Ctrl+B Builds the selected map(s) Alt+M, S Builds the selected map(s) for the specified platform Run Ctrl+R Runs the selected map(s) Run Results Alt+M, T Displays the Run Results dialog box in which you can view the run results of the selected map(s) Cl
Chapter 2 - Map Designer Basics Menu Bar Card Menu (Alt+C) The Card menu provides commands that are performed on input and output cards.
Chapter 2 - Map Designer Basics Menu Bar Command Tool Key Description Delete none Delete Clears all text from the selected rule bar Properties none Alt+R, P Displays the Rule Properties dialog box in which you can view the properties for objects, maps, and functions for the current rule Alt+R, A Expands the output card display to show all the components that have map rules Alt+R, G Calls up all associated functional maps associated with the currently selected map source file Alt+R, W Disp
Chapter 2 - Map Designer Basics Menu Bar Window Menu (Alt+W) The Window menu contains the commands that provide control of open windows.
Chapter 2 - Map Designer Basics Configuring the Map Designer Environment Mercator on the Web > Mercator Home Page none Alt+H, M, H Launches your internet browser and displays the Mercator home page (http://www.mercator.
Chapter 2 - Map Designer Basics 4 Configuring the Map Designer Environment Click OK. Options > General In the General options dialog box, you can specify values concerning the backing up and saving of your map files, map rule compare preferences, and the font for the Select Type window. The fields in this dialog box are as follows: ♦ Auto-save files every n minutes (where n represents a number) This number n is the time interval (in minutes) for automatically saving open map files.
Chapter 2 - Map Designer Basics Configuring the Map Designer Environment ♦ Suppress build warnings Use this check box to specify whether to suppress the checking of warning conditions and generation of build warnings during map compilation. The Suppress build warnings check box is disabled by default. ♦ Rule Differences > Ignore white spaces and tabs Use this check box to specify whether to ignore white spaces and tabs in map rules when using the Map Source File Differences command.
Chapter 2 - Map Designer Basics Configuring the Map Designer Environment ♦ Active card Color Click to display the Color palette to change the color of the active card in the From window. ♦ Max. no. of cards viewed Enter the maximum number of cards to display in the From window. ♦ Show floating component type Enable or disable this check box to control the display of floating component types. The Show floating component type check box is disabled by default.
Chapter 2 - Map Designer Basics Configuring the Map Designer Environment ♦ Active card color Click to display the Color palette to change the color of the active card in the To window. ♦ Max. no. of cards viewed Enter the maximum number of cards to display in the To window. ♦ Show all rules Enable or disable this check box to expanded or collapsed display of map rules in the To window. When enabled, rule cells that contain map rules are automatically expanded when a map is displayed.
Chapter 2 - Map Designer Basics Configuring the Map Designer Environment General Tab ♦ Font button Click this button to select the font and font size to be used for text in the rule bar. ♦ Commit rules with drop-down list Select to use the Enter (the default value), Tab, or both (Enter & Tab) key to commit a map rule. ♦ Use ellipses Enable this check box to use ellipses instead of long path names when dragging or copying objects.
Chapter 2 - Map Designer Basics Configuring the Map Designer Environment Color Coding Tab ♦ Use color coding check box Enable or disable this check box to specify the use of color-coded display of elements in map rules. ♦ Show errors with underline check box Enable or disable this check box to specify the use of underline on invalid portions of map rules.
Chapter 2 - Map Designer Basics Configuring the Map Designer Environment ♦ Lines group box Select any of these three option buttons (None, Solid, and Dotted [the default value]) to determine the appearance of the lines in the Navigator window. ♦ Show tool tips check box Enable this check box to display the name of each object when the cursor is held over it and the Navigator window is sized too small for the name to be completely displayed. The Show tool tips check box is enabled by default.
Chapter 2 - Map Designer Basics Configuring the Map Designer Environment Options > Organizer Window In the Organizer Window options dialog box, you can specify how to display objects in the Organizer window. The fields in this dialog box are as follows: ♦ Tab drop-down list Select which tab of the Organizer window on which you want to change the Font. ♦ Font button Click this button to select the font and font size to be used for text in the tab currently shown in the Tab field.
Chapter 2 - Map Designer Basics Configuring the Map Designer Environment Options > Run Results In the Run Results dialog box, you can specify how to display objects in the Run Results window. The fields in this dialog box are as follows: ♦ Font button Click this button to select the font and font size to be used for text in the Organizer window.
Chapter 2 - Map Designer Basics Configuring the Map Designer Environment Options > Run Options In the Run Options dialog box, you can specify default map settings, display settings, and the default resource Configuration File. The map settings you specify in this dialog are assigned to a map when it is created.
Chapter 2 - Map Designer Basics Configuring the Map Designer Environment DisplaySettings The DisplaySettings apply to any map that is run from the Map Designer. The DisplaySettings are used to configure how often to refresh the command server window when a map is running and when to close the command server window when a map completes. DisplaySettings > RefreshRate The RefreshRate specifies how often to refresh the command server window during map execution.
Chapter 2 - Map Designer Basics Configuring the Map Designer Environment DisplaySettings > AutoClose The AutoClose options control when the command server window is closed after map execution. Value Description Never The command server window never closes and remains open after the map execution is complete. Always The command server window closes automatically after the map execution is complete. Success The command server window closes only if a map ran successfully.
Chapter 2 - Map Designer Basics Help Options > Properties In the Properties dialog box, you can specify how to display objects in the Properties window. The field in this dialog box is: ♦ Font button This button allows you to select the font and font size to be used for text on the properties window. Help Comprehensive Help is available for the Design Studio, which includes the Map Designer.
Chapter 2 - Map Designer Basics Help ♦ Dialog box - The use of each dialog box is explained in a step-by-step fashion providing the information you need to complete the dialog box. Some tips and helpful hints or examples may also be provided. ♦ Table of Contents - Help topics are listed in the Table of Contents with a searchable index providing comprehensive information about using the Design Studio and related software components.
Chapter 3 - Map Files This chapter discusses how to use the Map Designer to create and manage map files. The tasks involved in creating and managing map files include: ♦ Creating map source files (.mms) ♦ Creating maps in the map source file ♦ Creating input and output cards for the map ♦ Building compiled maps (.mmc) ♦ Running maps ♦ Viewing run results Maps and Map Source Files A map defines how to generate a data object of a certain type or multiple independent data objects, each of a certain type.
Chapter 3 - Map Files Maps and Map Source Files After starting the Map Designer, the Navigator lists one or more map source files depending on whether you selected to create a new map source file or to open one or more existing map source files. The full path and filename of the map selected in the Navigator appear in the title bar of the Map Designer window.
Chapter 3 - Map Files Maps and Map Source Files Creating a Map Source File Map source files contain one or more maps. It is logical to organize your maps in map source files according to use or purpose. To create a map source file 1 From the File menu, choose New. The Save As dialog box appears. 2 Specify the location of the map source file by browsing your file structure. 3 In the File name field, enter the name of the map source file. 4 Click Save. The map source file displays in the Navigator.
Chapter 3 - Map Files 4 Maps and Map Source Files Click OK. The map appears in the Navigator with the functional map icon ( ). The icon is gray until the input and output cards specify a data source and a data target. Map Name Guidelines The guidelines to follow when naming a map are: ♦ A map name can be up to 32 characters in length. ♦ A map name cannot be a reserved word. See Chapter 8 of Introduction to the Design Studio. ♦ A map name cannot contain only digits and/or periods.
Chapter 4 - Input and Output Cards A map defines how to generate data objects of a certain type. A map contains input and output cards that transform data content from source formats to target formats. This data transformation occurs according to mapping rules on the data objects in the output card in the map. Input and output cards represent data objects. Each card represents one data object, which is defined as a particular type. There are two types of map cards: input cards and output cards.
Chapter 4 - Input and Output Cards Card Overview Each input of data and each output of data requires content definition settings. The content of each card is specified as a type in a type tree.
Chapter 4 - Input and Output Cards Card Overview Card Specifics ♦ More than one card in a map can reference the same type but the cards must have different card names. ♦ Each card is assigned a number when it is created. Cards are numbered sequentially, beginning at 1. The card numbers determine the order in which the cards and the data in those cards is evaluated. The card number is important when a map is used as a functional map. To reorder the cards, use the Reorder command on the Card menu.
Chapter 4 - Input and Output Cards Card Overview On the light blue title bar of the card: ♦ ♦ Click the card you want to view. Double-click the card you want to edit ♦ Scroll through them using the arrows at the lower right corner of the window. ♦ Double-click a card in the List view in the Navigator. Compositional Hierarchy The compositional view of the cards shows the contents of the type definitions.
Chapter 4 - Input and Output Cards Card Overview For example, the ContactFile input card #1 shown in the following map source file represents the input data of the map. The Contact(s) group type contains the item types that together make up the contact record. The Label output card represents the output data of the map. The Label group type contains the item types that together make up the output data.
Chapter 4 - Input and Output Cards Creating Input and Output Cards View of an Output Card CardName TypeName: the data object this card represents Rule column Rule cells Card number Structure of the data object the card represents Number of output cards Creating Input and Output Cards The create card function relates directly to which window is active when the new card is created. To create an input card, the From window must be active. To create an output card, the To window must be active.
Chapter 4 - Input and Output Cards Creating Input and Output Cards 3 Define the card by entering the appropriate information for each setting. 4 Click OK. To create an output card 1 To create an output card, select the To window.
Chapter 4 - Input and Output Cards 2 Creating Input and Output Cards From the Card menu, choose New. The Add Output Card dialog box appears. 3 Define the card by entering the appropriate information for each setting. 4 Click OK.
Chapter 4 - Input and Output Cards Editing an Input or Output Card Editing an Input or Output Card Any card setting may be changed: the card name, the card type, or the card source or target information. To edit a card 1 Select the card you want to edit. 2 From the Card menu, choose Edit. The Edit Input Card or Edit Output Card dialog box appears. 3 Make necessary changes to the card setting values. 4 Click OK.
Chapter 5 - Card Settings You configure how to run a map by specifying map settings in the Map Settings dialog box, defining SourceRule card settings on the input card, and defining TargetRule card settings on the output card. All of the card settings are on the Add (or Edit) Input Card and Add (or Edit) Output Card dialog boxes. Each input of data and each output of data require content definition settings. Card settings define the data object the card represents, and how the data is retrieved or routed.
Chapter 5 - Card Settings Schema To specify the CardName 1 For the CardName setting, enter the desired card name. The name of the card displays next to the card number in the light blue card title bar and as the top-level type icon in the card. CardName Guidelines Card names follow these guidelines: ♦ A card name can be up to 32 characters in length. ♦ A card name cannot be a reserved word. ♦ A card name cannot contain only digits and/or periods.
Chapter 5 - Card Settings SourceRule Input Card Settings TypeName The TypeName setting specifies the name of the type within the type tree, which describes the data represented by the card. This type must exist in the type tree specified with the TypeTree setting. To select the TypeName for the card 1 For the TypeName setting, click (browse). The Select type dialog box displays. 2 Select the desired type or use the Find button to search the type tree for a particular type. 3 Click OK.
Chapter 5 - Card Settings SourceRule Input Card Settings The content of an input card is defined with the CardName, TypeTree and Type settings. These settings define what the data is, but does not specify how to retrieve the data. The Source, FetchAs, WorkArea and FetchUnit card settings are some of the SourceRule settings that define how the data is retrieved for each input card. To define SourceRule settings 1 Select the input card. 2 From the Card menu, choose Edit.
Chapter 5 - Card Settings SourceRule Input Card Settings The SourceRule card settings and their override execution commands are listed in the table below: SourceRule Card Setting Override Execution Command FetchAs Not available Backup Not available WorkArea Available (-W) Source Available (-IA), (-ID), (-IE), (-IF), (-IM) FilePath Available (-IA), (-ID), (-IE), (-IF), (-IM) OnSuccess Available (-I…X) OnFailure Available (-I…B) Retry Available (-I…XRcount:interval) Warnings Not availabl
Chapter 5 - Card Settings SourceRule Input Card Settings Value Description Burst Data is retrieved in incremental units from the data source. The unit of data retrieved for each burst is adapter-specific, and is specified as the Source FetchUnit. When an input FetchAs is Burst, the data is retrieved once per burst. Note When an input FetchAs is Integral, any failure action causes the entire map to fail. ♦ When FetchAs is Integral, the maximum size of a file that a map can process is 2 GB.
Chapter 5 - Card Settings SourceRule Input Card Settings Guidelines for Reusing Work Areas Use the following guidelines when defining whether to reuse workareas. The WorkArea card setting depends upon the map setting for WorkSpace > Location and PageSize and PageCount settings. ♦ WorkSpace > Location setting. If the map setting for WorkSpace is File, the input card’s work area can be reused.
Chapter 5 - Card Settings SourceRule Input Card Settings Value Description S Get all objects, database rows, messages on a messaging queue, or files. 1 - nnnn Positive integer representing the logical or physical unit of data. For messaging adapters, FetchUnit defines the number of messages to retrieve. For File or Echo, FetchUnit defines the logical unit of data. For database adapters, FetchUnit defines the number of rows. FetchUnit Details The unit of data is adapter-specific.
Chapter 5 - Card Settings SourceRule Input Card Settings FetchUnit with Multiple Input Cards In a case where more than one input card in a map references the same data object, the values of the FetchAs and FetchUnit card settings must be the same on all cards that reference that data object. Only one instance of the type tree component structure is stored with the compiled map, therefore the card settings that control that component structure must be the same on all cards using that data object.
Chapter 5 - Card Settings SourceRule Input Card Settings Note The maximum size of a file that a map can process in integral mode is 2 GB. In burst mode, the maximum size is much larger, but can only be 2 GB in one burst. Source > FilePath When Source = File, the FilePath setting specifies the name and path of the input data file. Enter the filename or click (browse) to display the Select Data File dialog box in which you can navigate your file system to select the input file.
Chapter 5 - Card Settings SourceRule Input Card Settings Transaction The Transaction settings include the input data OnSuccess, OnFailure, and Scope settings. OnSuccess The OnSuccess setting specifies the location of the source data when a map, a burst, or a card successfully completes. The availability of the OnSuccess setting is adapter-specific. The OnSuccess setting works with the Scope setting, which defines when to apply the action specified with the OnSuccess setting.
Chapter 5 - Card Settings SourceRule Input Card Settings OnFailure The OnFailure setting specifies the location of the source data if the map, burst, or card does not successfully complete. Note The exact meaning and availability of the options for this setting is adapterspecific. See your adapter documentation for more information. The OnFailure setting works with the Scope setting, which defines when to apply the action specified with the OnFailure setting.
Chapter 5 - Card Settings SourceRule Input Card Settings Scope The Scope card setting tells the source or target adapter at what point during map execution to apply OnSuccess and OnFailure actions. The default setting is Map. Value Description Map Apply the OnSuccess and OnFailure settings based on the success or failure of the entire map execution (which may be one or more bursts). Burst Apply the OnSuccess and OnFailure settings based on the success or failure of each burst.
Chapter 5 - Card Settings TargetRule Output Card Settings TargetRule Output Card Settings The TargetRule settings define how the output data is routed. The data object specified in the output card defines what data is output. To define card-specific output data routing, define the TargetRule settings for each output card. TargetRule settings specify where to send the data, and what to do when an error occurs. An output card represents an output target.
Chapter 5 - Card Settings TargetRule Output Card Settings The TargetRule card settings and their override execution commands are listed in the table below: TargetRule card setting Override Execution Command Backup Not available Target Available (-OA), (-OD), (-OE), (-OF), (-OM) OnSuccess Available (-O…X) OnFailure Available (-O…B) Retry Available (-O…Rcount:interval) Warnings Not available Scope Not available PUT The PUT settings define all of the output data settings.
Chapter 5 - Card Settings TargetRule Output Card Settings DatabaseQueryFile When Target = Database, the DatabaseQueryFile settings are used to specify the database specific settings: the name of the desired database/query file, the database name, and the query. DatabaseQueryFile > File Specify the database/query file (.mdq) which contains the desired target database and query definition. DatabaseQueryFile > Database Specify the database that contains the desired query definition.
Chapter 5 - Card Settings TargetRule Output Card Settings The OnSuccess setting works in conjunction with the Scope setting, which defines when to apply the action specified with the OnSuccess setting. Value Description Create Output data should be sent by the target adapter to its target. For example, if the map completes successfully, the message adapter should put the message on the specified queue. CreateOnContent Output data should be sent only if content exists.
Chapter 5 - Card Settings TargetRule Output Card Settings The OnFailure setting works in conjunction with the Scope setting, which defines when to apply the action specified with the OnFailure setting. Value Description Rollback Any changes made during map processing are rolled back and the original state of the data is restored. If the map, burst, or card does not complete successfully, rollback any changes that were made to the target data during map execution.
Chapter 5 - Card Settings Input and Output Card Settings Input and Output Card Settings The Retry and the Backup settings appear on both input and output cards. Retry The Retry settings are defined for each input and output card. The Retry setting is compiled into the map, but may be overwritten by the execution settings defined in the Integration Flow Designer and the AdapterRetry (-Y) execution command.
Chapter 5 - Card Settings Input and Output Card Settings Retry > MaxAttempts The MaxAttempts setting specifies the maximum number of times to try access to a source or target for a map. The default value for the MaxAttempts setting is 0. Value Description nnnnn A number that represents the maximum number of times an attempt is made to access the source or target for a map. After the maximum number of attempts has been attempted without access, the map returns a return code and message.
Chapter 5 - Card Settings Input and Output Card Settings ♦ The Document Type > Metadata value must be set to either DTD or Schema. ♦ A DTD or schema file location must be specified (Document Type > Location). In the Map Designer, the following should apply in the map input card: ♦ The Schema > Type is set to the object you associated with the Document Type above. ♦ The SourceRule > GET > Source > DocumentVerification setting is set to Always, OnSuccess, or OnFailure.
Chapter 5 - Card Settings Input and Output Card Settings Based on these settings, when the map runs, an external parser (document verification program) validates the XML document. If there are no errors, the map completes successfully. If there are errors, the map fails and the error information is written to the map trace file if it is enabled. Because this setting is at the card level, you can set different options for different input and output cards.
Chapter 5 - Card Settings Input and Output Card Settings Using DocumentVerification for Output Data For output data, the DocumentVerification option only works if the MapAudit > SettingsAudit > Data setting is enabled for the output.
Chapter 5 - Card Settings Input and Output Card Settings If you selected Custom, the Value field appears under Directory. If you selected Map, proceed to step 5. 4 In the Value field, click (browse) to navigate your file structure and select a directory for the backup file. 5 For the FileName setting, select Custom to create a filename, or Unique for a system-generated file name. If you selected Custom, the Action and Value fields appear.
Chapter 5 - Card Settings Input and Output Card Settings Backup > BackupLocation The BackupLocation value indicates that backup data is copied to a file. There are subsettings that enable you to select information about the file, such as where and when it is created. BackupLocation > Directory BackupLocation > Directory enables you to specify the directory into which the backup file is written. The file is written to the Map directory by default.
Chapter 5 - Card Settings Value Input and Output Card Settings Description ♦ mapname is the executable map name. ♦ process_key is a unique, per process value. ♦ map_counter is a unique, per map instance value (within the same process). ♦ extension is the backup filename extension, which is .Inn.bak (for input cards) or .Onn.bak (for output cards), where nn represents the card number. BackupLocation > FileName > Action The BackupFileAction setting specifies how data should be written to the backup file.
Chapter 6 - Map Rules This chapter introduces map rules. Map rules are used in output cards of a map to define how output data is built. Map rules are required for output data generation. If there is no map rule, there is no output data. When no output is desired for a given data object, a map rule of =NONE is required. A map is not complete until each rule cell has a map rule, or appears dimmed (the map rule is unavailable). Empty rule cells generate a build error when the map is built.
Chapter 6 - Map Rules Color Coding of Map Rules Color Coding of Map Rules To aid in readability, map rules can be colored with user-configured colors. When color-coding is enabled, each element of a map rule can be configured with a different color. The elements of map rules are categorized to allow color specification by category.
Chapter 6 - Map Rules A Map Rule is an Expression To disable color coding 1 Disable the Use color coding check box. A Map Rule is an Expression Each map rule begins with an equal sign (=), followed by an expression. A map rule is an expression that evaluates to data. An expression is any valid combination of literals, data object names, operators, functions and map names. The expression in a map rule generates the desired data.
Chapter 6 - Map Rules A Map Rule is an Expression An expression can be complex and have simpler expressions nested within it.
Chapter 6 - Map Rules A Map Rule is an Expression The output CompanyName is defined with an Item Subclass of Text. The following map rule: CompanyName = “Pop’s Pizza Co.” assigns the value of a text literal to the output. A text literal is text enclosed in double quotes and is interpreted as a text item. A rule that evaluates to something other than text, for example, CompanyName = 24 would be invalid.
Chapter 6 - Map Rules Unavailable Rule Cells Unavailable Rule Cells The output of a map produces each output card object. To produce a card object, the required objects that compose the card object must be produced. There is a rule cell for each object within the card object. If an output object is an item, you must supply a rule for it. If an output object is a group, you have two options.
Chapter 6 - Map Rules Entering Map Rules Map Rule for Each Component You could enter map rules for each component of Summary. Or you could enter a map rule for all three components Or you could enter a rule for the entire object Product Record.
Chapter 6 - Map Rules Entering Map Rules 2 If necessary, click in the rule bar in the specific place where you want to insert the function. 3 From the Rules menu, choose Insert Function. The Insert Function dialog box appears. 4 If you know the function category, select the Category. 5 Select the function you want to insert. 6 Click OK. The function is inserted into the rule bar. 7 Tip Insert another function or click Close.
Chapter 6 - Map Rules Entering Map Rules The symbol appears within literal quotation marks in the map rule. Entering a Restriction into a Map Rule If you want to enter a map rule that includes those restriction values, you can drag the restrictions from the Properties window into the rule bar. To enter a Restriction in a map rule 1 Select the rule cell where you want to insert the restriction. 2 Right-click on the item whose restriction(s) you want to enter, and choose Properties.
Chapter 6 - Map Rules Comments in Map Rules Special Characters in Map Rules To enter a Hexadecimal value of a special character in a map rule, enter the Hex value for the characters in double brackets (open and close carets).
Chapter 6 - Map Rules Comments in Map Rules The following map rule has two comments, which are indicated by blue text: = EXTRACT (Record:Customers /*Extract the Records */, State Field:.:Customers = "FL" /* Get only the customers in Florida */ ) Tip Using comments for map rules, or portions of map rules, is a convenient way to retain complex and lengthy map rules for future use without deleting them. Syntax Errors in Map Rules Syntax errors are reported when the map rule is committed.
Chapter 6 - Map Rules Comments in Map Rules Data Object Appears in map rules as: Description Index Note[3]:Report specific occurrence appears in square brackets [n] immediately after the type A particular occurrence of a data object indicated by the index Partition Customer<>Record separated by <> When a type is partitioned, its subtypes, or partitions, appear in the card with <> which resembles the diamond-shaped icon of the partitioned type. Shortened data object name Company Field:.
Chapter 6 - Map Rules Comments in Map Rules A unique name for each card in the map provides the ability to distinguish between card objects. For example, if two input cards are defined by the same type, these two input cards may exist with the same type, but their card names are different. If the name of the first card is Input1 and the second input card is Input2.
Chapter 6 - Map Rules Comments in Map Rules The name of the component Quantity in the input card shown below is Quantity:Record:OrderFile When you see a colon, you can read "of". You could read the data object name for Quantity as "The Quantity of Record of OrderFile". In the previous examples, OrderFile is the name of the input card and the name of the type. The card name always appears last in each object name to provide the ability to distinguish between card objects.
Chapter 6 - Map Rules Use Ellipses For example, the partition CallRecord of the group type SetofCallRecords is CallRecord<>SetofCallRecords. Think of a partition as a particular kind of the partitioned type. For example, in the name Detail<>Record, you can think of it as a Detail kind of Record. An object name includes component references and partition references.
Chapter 6 - Map Rules Viewing Properties in the Map Designer Using Ellipses to Shorten an Object Name To allow object names entered into map rules to use the ellipses option, put current focus on the rule bar and click below. or change your options as described To have new object names appear with ellipses 1 From the Tools menu, choose Options. 2 Choose Rule Bar. 3 Enable the Use Ellipses check box. 4 Click OK.
Chapter 6 - Map Rules Viewing Properties in the Map Designer To view the properties of a type 1 Right-click the type in a map card. 2 From the context menu, choose Properties. 3 Click the Properties tab to view type properties. You may also view attributes, component rules, and restrictions by clicking the Attributes, Rule, and Restrictions tabs. To expand the view of a specific setting on the Properties tab, click the plus (+) next to the property.
Chapter 6 - Map Rules Viewing Properties in the Map Designer To update the view on the Rule tab 1 When the properties window is already open, update the view by clicking the data object in the map card. Viewing Component Attributes Three attributes can be assigned to a component in the type tree: identifier, restart, and sized. These attributes are viewed in the Map Designer on the Attributes tab of the Properties window. To view the attributes of a component 1 Right-click the component in a map card.
Chapter 6 - Map Rules Viewing Properties in the Map Designer Viewing Function Syntax You can view the syntax of a function in the Insert Function dialog box. To view function syntax 1 Click in any rule cell in an output card to enable the Insert Function command. 2 In the Insert Function dialog box, select the function whose syntax you want to view. The syntax of the function with the inputs and outputs appears in the Description pane of the Insert Function dialog box.
Chapter 6 - Map Rules Formatting a Map Rule Viewing Functional Map Inputs and Outputs The inputs and output of a functional map are in the map rule properties. Opening the Type Tree You may want to edit a type when you are designing maps in the Map Designer. You can easily open a type tree in the Type Designer. The group or item window and the Properties window for the selected type are opened. To open a type tree 1 In an input or output card, right-click the type whose tree you want to open.
Chapter 6 - Map Rules Formatting a Map Rule Creating a new line in the rule bar depends on what key is used as the Commit key (default is the Enter key). New lines may not be added in literal text strings. Extra spaces in a map rule may be added to improve readability. Note Spaces cannot be added within an object name or function name. To create a new line in the rule bar if Enter is the Commit key 1 Place the cursor where you want to create a new line in the rule bar. 2 Press Ctrl + Enter.
Chapter 7 - Formulating Map Rules This chapter provides information on implementing map rules to build the desired output results. Generating No Output If an output is optional, you may not want to generate the output for that data object. In situations in which you do not want to generate output for a data object on an output card, enter a special rule. The rule for generating none of an output is simply: = NONE Note The word NONE is case-sensitive.
Chapter 7 - Formulating Map Rules When Input Data Is Missing When Input Data Is Missing If you map an input to an output, but the input is missing, either the output will have no content or it will not exist. The existence of the output depends on how the output is defined. When Portions of an Input Series are Missing When portions of an input series are missing, the output to which it is mapped built according to the Track property of the type in the Type Designer.
Chapter 7 - Formulating Map Rules Output is Defined in This Manner When Input Data Is Missing Context Output is Built in This Manner Occurs within a delimited explicit group The group’s delimiter appears in the output. If a special value for NONE has been assigned, NONE is built as the special value. Or, if a pad property is specified as applied in any context, NONE is built. Otherwise, NONE is not built.
Chapter 7 - Formulating Map Rules Output is Defined in This Manner Mapping an Input Item to an Output Item Context Output is Built in This Manner Occurs within a delimited explicit group The group’s delimiter appears if data with the same delimiter follows. Occurs within an implicit group No output is built. Note An item within a fixed group must have the Padded to = Fixed Size property specified, or the size minimum must equal the size maximum.
Chapter 7 - Formulating Map Rules Mapping an Input Item to an Output Item If an input type is defined as a decimal number, with no pad character, no separator, and two decimal places, the following table shows an example of input and output types of an item type definition.
Chapter 7 - Formulating Map Rules Mapping a Group to a Group Mapping a Group to a Group Desired output of an input group may be the same as an input group. If the output group is the same type and is defined in the same type tree as the input group, drag the input group into the map rule cell of the output group. If the input group is a partition of the output group, you can drag the partition into the rule cell of the output group.
Chapter 7 - Formulating Map Rules Outputs with a Maximum Range Greater than 1 When the number of output objects is based on the number of some other object, create a map rule that maps the output according to the number of occurrences of an input. Indexing an Output When the number of objects to generate for each map execution is known, index the number of occurrences of that output object. To index an output is to generate a specific number of occurrences of that output.
Chapter 7 - Formulating Map Rules Outputs with a Maximum Range Greater than 1 Map to the first occurrence of an indexed object by dragging that object from the input card to the map rule of the item on the output card. Define the second occurrence of the output by dragging the desired object from the input card to the map rule of the item on the output card. If you do not want a third indexed data object, enter the map rule = NONE.
Chapter 7 - Formulating Map Rules Mapping to Multiple Occurrences of a Group All of the map rules nested within that object are moved. Mapping to Multiple Occurrences of a Group When an output group has a range with a maximum greater than 1 and you want to map a certain input group to that output group, there are two possibilities: ♦ If the input group is the same as the output group, drag the input object from the input card to the map rule of the object on the output card.
Chapter 7 - Formulating Map Rules Mapping from a Floating Component Type Mapping from a Floating Component Type If an input card data object is a group that has a floating component type, you can map from the floating component type. A floating component must be distinguishable from every component of the group it is assigned to. On input, a floating component can appear after the initiator and after each component.
Chapter 7 - Formulating Map Rules Mapping from a Floating Component Type The object name and the @ symbol indicate the component that the floating component type follows. In this example map rule, Text Field:Note is the floating component that follows Discussion:Presentation.
Chapter 8 - Functional Map Basics This chapter explains the basics of creating and using functional maps. For information on using the Functional Map Wizard to automatically create a functional map, see Chapter 9 - Functional Map Wizard. A functional map and the executable map that calls it must be in the same map source file (.mms). Functional Maps A functional map is like a sub-routine; it maps a portion of data at a time. A functional is a map that is used like a function.
Chapter 8 - Functional Map Basics Functional Maps Note Use a functional map when the number of a certain output group that you want to create is based on the occurrences of some input or output data - and the types are different types. Input and Output Data May Reflect Each Other Frequently, your input and output data contain very similar information, but the data is arranged differently.
Chapter 8 - Functional Map Basics Functional Maps The following example shows a data source of three input records. A functional map provides a way to map one input record to one output record. The functional map defines the first input record that generates the first output record. Next, the second input record generates the second output record. The third input record generates the third output record. The result is three output records.
Chapter 8 - Functional Map Basics Functional Maps Basic Steps in Using a Functional Map The basic steps to follow in using a functional map are listed below: 1 Determine that you want or need to use a functional map. 2 Determine the input argument(s) of the functional map. 3 Enter the map rule that references the functional map. 4 Create the functional map. 5 Create the input card(s). 6 Create the output card(s). 7 Enter map rules in the functional map.
Chapter 8 - Functional Map Basics Functional Maps The objective is to map this data to a file containing delimited records. The delimited record has only the car name and the weight. In the delimited record, the weight is in decimal format. The desired output data result is: Marlin,29.30 Pacer ZSX,33.50 Wildcat,26.40 Fantasia DX,28.30 La Vella,20.70 Blue Baron,26.50 Cavalino,32.50 You want to generate one delimited record for each fixed record in the input file.
Chapter 8 - Functional Map Basics Two Kinds of Maps Ask yourself “how many CarRecord(s) do I want to generate?” If you want a specific number, the answer would be that number. To generate two CarRecord(s), index two occurrences of CarRecord, expand each occurrence, and map to its components. For more information on indexing, see the Indexing an Output section. If the number of CarRecord(s) is based on the number of FixedRecord(s) in the input, generate one CarRecord for each FixedRecord.
Chapter 8 - Functional Map Basics Syntax of a Functional Map Expression ♦ Functional Map A functional map is referenced by another map through a map rule. A functional map maps just a portion of the entire data. Data sources and targets are not specified in the cards of functional maps. Functional maps are not compiled and run. In the Navigator, the icon for a functional map is gray . Note A given map can be used both as an executable and as a functional map.
Chapter 8 - Functional Map Basics Syntax of a Functional Map Expression Each of these expressions evaluates to data. For example, the following expression evaluates to the data object FixedRecord: FixedRecord:Input The following expression evaluates to StoreInfo data objects: EXTRACT (StoreInfo:Inventory, StoreName:Inventory = “Lee Furniture”) The INDEX (Record:File) expression evaluates to an integer. The “Mercator” expression evaluates to text.
Chapter 8 - Functional Map Basics Entering the Map Rule that References the Functional Map In the following map rule, the OrderMap functional map is specified with the (DetailRecord:Order:Input, SummaryRecord:Order:Input) arguments: OrderMap (DetailRecord:Order:Input, SummaryRecord:Order:Input) The data object SummaryRecord has an optional component range of (0:1). For the first Order, SummaryRecord is present. The functional map OrderMap is evaluated. In the second Order, SummaryRecord is missing.
Chapter 8 - Functional Map Basics Entering the Map Rule that References the Functional Map A functional map on the CarRecord(s) data object can generate one CarRecord for each FixedRecord. A suitable name for the functional map can be RecordMap, because the functional map maps one record at a time.
Chapter 8 - Functional Map Basics Creating a Functional Map Creating a Functional Map The functional map RecordMap maps a single FixedRecord to a single DelimitedRecord. Fixed Record1 Fixed Record2 Fixed Record3 Fixed Record1 RecordMap Delimited Record1 Fixed Record2 RecordMap Delimited Record2 Fixed Record3 RecordMap Delimited Record3 . . .
Chapter 8 - Functional Map Basics Creating a Functional Map The new map is created and appears in the Navigator. In List view, the functional map is at the same level as the executable map. In Composition view, the functional map appears at a level beneath the executable map that calls it. To create input and output cards in the functional map 1 Create the required input cards. Each input card represents a single data object.
Chapter 8 - Functional Map Basics Input Card Types of a Functional Map Input Card Types of a Functional Map The input and output cards in a functional map must be in the same order as the data objects are specified in the map rule argument. The input card type(s) in a functional map must be coordinated with the input argument(s).
Chapter 8 - Functional Map Basics Output Card Type of a Functional Map Functional maps do not require InputData and OutputData settings. Note If InputData and OutputData settings exist in input and output cards in a functional map, they are ignored when the executable map is compiled. Output Card Type of a Functional Map The type of the output card in a functional map is the type whose map rule includes the functional map name.
Chapter 8 - Functional Map Basics Using Multiple Inputs in a Functional Map The input PO is composed of one Header and multiple Details. You want to generate one ItemRecord for each Detail. Header Detail1 ItemRecord1 Detail2 ItemRecord2 Detail3 ItemRecord3 .. . .. . The functional map MakeItemRecord takes one Detail at a time, along with the Header, and creates one ItemRecord.
Chapter 8 - Functional Map Basics Using Multiple Inputs in a Functional Map ♦ The input arguments must match the input card types, in the same order. ♦ The order of the arguments does not affect the number of times a rule is evaluated. However, it may affect the order in which the output objects appear and the performance at run-time. For more information on how rules are evaluated, see the Functions and Expressions Reference Guide.
Chapter 8 - Functional Map Basics Going to a Functional Map Referenced in a Map Rule Going to a Functional Map Referenced in a Map Rule You can easily go to a functional map whose name is in a map rule. To open and view the functional map referenced in a rule 1 Right-click the rule containing the name of the functional map. 2 From the context menu, choose Goto Functional Map. 3 Select the functional map to which you want to go. 4 Click OK.
Chapter 8 - Functional Map Basics Functional Maps in the Navigator A map is identified as an executable map when a data source or target is specified for each card. If a data source or target is not specified for each card, the map has a functional map icon. Note A map may appear both as an executable and as a functional map. Functional Maps that Do Not Exist If a map rule includes a map name that does not exist in that map source file, the map name appears in the Navigator with a pink icon ( ).
Chapter 9 - Functional Map Wizard The Functional Map Wizard automatically creates a functional map (or maps) based on a map rule (or rules). The maps that the Wizard creates contain input cards and an output card, but do not contain map rules. Using the Functional Map Wizard The functional map creation requires a map rule on an output card of an executable map. To use the Functional Map Wizard 1 In the executable map, enter the map rules for the functional map.
Chapter 9 - Functional Map Wizard Using the Functional Map Wizard Name of map that will be created Definition of output card Definition of input card After you click Create, the map is created in the active map source file. You can then modify the functional map and enter the appropriate map rules.
Chapter 9 - Functional Map Wizard Using the Functional Map Wizard Functional Map Wizard Icons The status icons that appear next to card and map names in the Functional Map Wizard dialog box are shown in the following table. The action to take to change the status is provided. Symbol (gray face) (yellow face) Meaning Action to Take Appears next to an input card name and a map name. Close the Functional Map Wizard and change the invalid input argument in the map rule.
Chapter 9 - Functional Map Wizard Properties of the Functional Map Properties of the Functional Map The Functional Map Wizard creates maps based on the map rules selected when the wizard is activated. Map Name The name of the functional map to be created is specified in the map rule. The name of the functional map must be unique within the map source file. Tip To easily identify functional maps, you may use a specific naming convention.
Chapter 9 - Functional Map Wizard Properties of the Functional Map Input Card Names The Functional Map Wizard creates cards with generic names. Edit the card names to reflect that data object it represents. The default name of each input card created by the Functional Map Wizard is In and the number of the card. For example, the second input card has the name In2. Output Card The Functional Map Wizard creates one output card. There is only one output card in a functional map.
Chapter 9 - Functional Map Wizard Editing Card Definitions in the Functional Map Wizard Editing Card Definitions in the Functional Map Wizard You can edit card definitions in the Functional Map Wizard dialog box. It is a good idea to assign meaningful names to the cards. Note It is not a good idea to change the type of a card that the wizard has created. After all, the wizard chooses the correct types, based on the map rule.
Chapter 9 - Functional Map Wizard When an Argument Is Invalid When an Argument Is Invalid If an argument of a functional map in a rule is invalid, no card is created for that argument. You must fix the map rule and try the wizard again. For example, the following invalid rule for DelimitedRecord(s) is entered: =RecordMap (FixedRecord) The object name for FixedRecord is invalid because FixedRecord is a component of Input.
Chapter 9 - Functional Map Wizard When an Argument Returns an Object of a Known Type When an Argument Returns an Object of a Known Type Sometimes an argument of a map is not simply an object name; it is a more complex expression. The Functional Map Wizard creates maps that have complex arguments only if the type of the object the argument returns can be determined. For example, in the following map rule: = F_ResponseMap (EXTRACT (Customer Record:ResponseList:.
Chapter 9 - Functional Map Wizard Using an Output As an Argument If a Map Already Exists If the map names in the rules you specify in the map rule to generate a functional map already exist, the maps are not created and a message indicating that there are no unknown maps appears. To create the specified map when a map with that name already exists, rename the map in the rule, or rename the existing map. Using an Output As an Argument You can use an output data object as an argument of a functional map.
Chapter 9 - Functional Map Wizard Using a Functional Map to Increment Data The BatchMap executable map maps the entire input of multiple POs to the output set of Invoices. This map will call the POToInvoice map which maps each PO. In addition, POToInvoice calls the functional map ItemMap which maps each item.
Chapter 9 - Functional Map Wizard Referring to the Current Output in a Map Rule Referring to the Current Output in a Map Rule A map rule can include the name of the output object to which it applies. For example, to use the INDEX function on LineItem, the map rule on LineItem will include LineItem. Instead of using the entire object name for LineItem, use the dollar sign shorthand symbol $. The dollar sign $ refers to the object to which the expression applies.
Chapter 9 - Functional Map Wizard Using a Functional Map to Re-order Data In the input data, the object called Flower indicates the flower type. Use the UNIQUE function on Flower as the first input argument to the map F_MakeReport. This will cause the map F_MakeReport to be executed once per flower type. In the input data, the unique flowers are alstromeria, daisy, snapdragon, lily, and iris.
Chapter 10 - Map Settings Map settings specify properties for map executions that are not specific to a particular input or output. These include settings for auditing a map, tracing data content, performance settings, validation settings, and map-specific warnings and errors. Map settings are defined for a map and compiled with a map. ♦ In the Map Designer, the map settings defined in the Tools > Options > Run Options > MapSettings dialog box are the default settings that apply when a new map is created.
Chapter 10 - Map Settings Defining Default Map Settings Defining Default Map Settings Map settings are compiled with a map. In the Map Designer, the map settings defined in the Map Settings dialog box are the default settings that apply when a map is created. Each new map created uses the default map settings specified in the Run Options. To define default map settings 1 From the Tools menu, choose Options. 2 In the Options dialog, select Run Options.
Chapter 10 - Map Settings MapAudit Settings If the MapAudit Switch is set to ON, the audit log is created and can be appended. In addition, there are flexible sub-switches that allow for the audit log to be created or appended based on the following conditions: ♦ When a map fails. ♦ If the map has an error. ♦ If the map has a warning or error. MapAudit > Switch The Switch setting enables or disables the map audit feature. The default value for the Switch setting is OFF.
Chapter 10 - Map Settings MapAudit Settings BurstAudit > Data The Data setting is used to include or exclude data information in the audit log. The burst audit data information includes a burst count, the card number, the object index, the audit log status code, the object level, the size of the object, and the object name. You can specify that you want to audit a particular object by including that object in the Organizer window on the Data Audit Settings tab.
Chapter 10 - Map Settings Value MapAudit Settings Description following example: "data at offset xx ('DATA…')is the wrong size for the TYPE X'(02) (typename)" When using the TooLong TooShort value for the BurstAdit > Data > SizeValidation setting and the data fails the minimum size requirement, the input trace file entry will look similar to the following example: (Level 1: Offset 41, len 6, comp 5 of 7, #1, DI 00000005:) Data at offset 41 ('SYNTAX...
Chapter 10 - Map Settings MapAudit Settings MapAudit > SummaryAudit Expand this setting to define the summary audit Execution settings. Summary audit provides audit information on map execution without the detailed burst information. SummaryAudit > Execution The Execution value determines whether to include summary audit execution information in the audit log. Summary audit provides audit information on map execution without the detailed burst information.
Chapter 10 - Map Settings MapAudit Settings SettingsAudit > Data The Data value determines whether to include data settings in the audit log. The SettingsAudit > Data settings are listed in the following table. The default setting is Never. Value Description Always Include data settings in the audit log, regardless of the map execution outcome. Never Do not include data settings in the audit log, regardless of the map execution outcome.
Chapter 10 - Map Settings MapAudit Settings MapAudit > AuditLocation The AuditLocation setting is used to specify where the audit information is stored. The availability of additional settings (such as Directory, FileName > Action LogFileAction or Sized) varies according to the Location setting. The MapAudit > AuditLocation values are listed in the following table. The default value is File. Value Description File Audit information is stored in a file.
Chapter 10 - Map Settings MapAudit Settings FileName Use the FileName setting to specify a default or custom name for the audit log file. Value Description Default The file is automatically assigned an audit log file name based on the compiled map name with the file name extension .log. Unique Generates a unique audit log name in the following format: Mer___.log Run___.
Chapter 10 - Map Settings MapAudit Settings FileName > Action The Action setting is used to create a new audit log file or to append the audit log to an existing audit log file. The default value for the LogFileAction setting is Create. Value Description Create The audit log file is created each time the map is run. Append The audit log is appended to an existing audit log file each time the map is run. If no audit log file exists at the start of map execution, an audit log file is created.
Chapter 10 - Map Settings MapTrace Settings MapTrace Settings MapTrace settings specify properties for a trace file used to diagnose invalid data or incorrect type definitions. ContentTrace Specifies that the trace information is written to a file. ContentTrace > Switch Define whether map tracing is enabled. A trace file can be used for diagnosing invalid data or incorrect type definitions. Value Description OFF Trace data for the map will not be created. ON Trace data for the map will be created.
Chapter 10 - Map Settings MapTrace Settings Directory The Directory setting is used to specify the same directory as the map or a userdefined directory. The default value for the Directory setting is Map. Value Description Map The same directory as the map. Custom The directory you specify using the Value setting. Value When the Directory setting is Custom, enter the full path of the directory in the Value setting or click the button to select the directory by using a Select Directory dialog.
Chapter 10 - Map Settings MapTrace Settings InputContentTrace Specify options of which input data is traced. The default value for the Detail setting is All. Value Description Off Trace input data for the map will not be created All Trace all inputs. Card# Trace a single input. Specify the input map card by typing the number of the map card into the value field of the Card# setting. Range Trace a range of input objects.
Chapter 10 - Map Settings WorkSpace Settings RulesTrace The Detail setting specifies options of which output data is traced. The default value for the Detail setting is All. Value Description OFF Trace output data for the map will not be created. All Trace all objects built. Card Trace a single output. Specify the output map card by typing the number of the map card into the value field of the Card# setting. CardNumber To trace a single output trace, enter the card number.
Chapter 10 - Map Settings WorkSpace Settings When a map is run, a paging scheme to access information about the data as efficiently as possible is used. Portions of both working data and actual data are paged, as needed. The workspace can be a combination of files and memory, or simply memory-based. When file-based workspace is used, the amount of memory accessed at a given time depends on the number of pages and the count of pages configured for a map to run.
Chapter 10 - Map Settings Century Settings PageCount The PageCount setting specifies the number of memory pages to use for work files. For large data files, you may want to increase the number of pages used. The default value for the PageCount setting is 8. Value Description n Enter a number that represents the number of memory pages to use for workspace. Valid numbers are 1 to 9999 (an integer greater than 0).
Chapter 10 - Map Settings Validation Settings Century The Century setting specifies the current or sliding century. The default value for the Switch setting is Current. Value Description Current Missing century numbers are derived based on the current system date. Sliding Enables SlidingCentury options. Missing century numbers are derived based on the value of the CCLookup setting.
Chapter 10 - Map Settings Validation Settings Validation During map execution, the input data is validated to assure it matches the definition of that input. Specify how strictly the data is validated by specifying response behavior for types of validation errors. Value Description Standard Standard validation occurs when the map is run. Custom Enables custom validation options. Define these options in the OnValidationError, RestrictionError, SizeError, and PresentationError settings.
Chapter 10 - Map Settings Validation Settings Value Description Ignore (no warnings) Allows restrictions to be fully ignored, in all situations other than when ignoring is required for object identification, such as when an item is partitioned by a restriction list. Note Restrictions of syntax items are not ignored, because these are used in determining the value of the syntax object. SizeError Define whether to validate the data with size at run-time.
Chapter 10 - Map Settings Retry Settings Retry Settings The Retry map settings define whether to try again if compiled map files, work files, audit log files, or trace files that are needed during map execution cannot be opened. Specify the Interval and MaxAttempts to define how many times and at what interval attempts are made to access an unavailable file.
Chapter 10 - Map Settings Warnings Settings Retry > MaxAttempts Use the MaxAttempts setting to specify the maximum number of attempts to access an unavailable file referenced by the map. The default value for the MaxAttempts setting is 10. Value Description n Enter a number that represents the maximum number of attempts to access an unavailable file referenced by the map. After the maximum number of attempts has been exhausted unsuccessfully, a return code and message are returned by the map.
Chapter 10 - Map Settings Warnings Settings Note Define your audit settings for each map, as the audit log of the main map may not reflect all failed map information if the failed maps are called with a RUN, PUT, or GET function. Value Description Every Map fails when any of the warning codes are returned. This setting treats every warning the same way, depending on the value of the Return setting. For Return, you can select Warn, Ignore or Fail.
Chapter 11 - Configuring Bursts For input card settings that have a FetchAs mode of Burst, the type of input object (as defined in the Source setting) and the FetchUnit work together to achieve the desired results. For example, if an input type is one message, the FetchUnit should be 1. If the input type is a series of messages, the FetchUnit can be any integer. ♦ When the Source is a File of Messages When the map is run, the first message in the file is found, and converted as specified.
Chapter 11 - Configuring Bursts Using Bursts for Large Files If the input type has no components, or has more than one component, the type of that input is not automatically adjusted. In this case, if the amount of data retrieved for a burst does not match the input type definition, the input is either invalid or a burst warning is issued Input valid, but unknown data found.
Chapter 11 - Configuring Bursts Configuring the RUN Function and Bursts If the following error occurs… Card fails Burst fails The type of an input is invalid √ If "stop on first error" is set, input validation fails, causing the burst to fail. If "stop on first error" is not set, input validation continues until all inputs are validated. Input validation as a whole causes a burst failure if any input type is invalid.
Chapter 11 - Configuring Bursts Logical or Adapter-Specified FetchUnits If the Scope of a source or target is set to burst or card, that resource will act based on the appropriate completion status of the card or burst configured in the referenced RUN function. When using nested RUN functions, if a source or target contained in a nested RUN has a Scope set to Map, any higher failure will cause that source or target to exercise its OnFailure action.
Chapter 12 - Managing Maps This chapter explains how to edit maps and cards within maps. It also explains the search facilities in the Map Designer. The Map Designer enables work to be reused. Anything that you have done once, you do not have to do again. Input and output cards are managed by copying, deleting, and editing. Standard Windows Capabilities The Map Designer supports standard Windows mouse and keyboard capabilities.
Chapter 12 - Managing Maps Standard Windows Capabilities Deletion The Map Designer supports Windows’ standard deletion capability. ♦ To delete an object, select it and press the Delete key. Objects that May Be Deleted with the Delete Key The following objects may be deleted by pressing the Delete key: ♦ Maps in the Navigator ♦ Cards in the Navigator ♦ Unresolved rules ♦ Map rules Cut, Copy and Paste The Map Designer supports standard cut, copy and paste features.
Chapter 12 - Managing Maps Additional Mouse Shortcuts Additional Mouse Shortcuts The following list describes other features in the Map Designer: ♦ To merge a map, select the map in the Navigator, press the Shift key and drag the map name to the destination folder. ♦ To reorder index occurrences in an output card, press Ctrl and Shift keys while dragging an index occurrence to the desired location.
Chapter 12 - Managing Maps 2 Managing Maps ! The map is active when the name of the map displays in the Map Designer title bar. ! Or select the map in the Navigator. From the Map menu, choose Copy. The Copy Map dialog box appears. 3 In the Copy to field, enter a map source file name or click (browse) to display the Select map file dialog box in which you can navigate your file system and select the map source file to which you want to copy the map. 4 Click Open. 5 Click OK.
Chapter 12 - Managing Maps Managing Maps Merging a Map You can merge a map from one map source file to another map source file. Merging a map copies the map itself and all of the maps that are related by functional map references to that map. Note When you merge a map, if any of the related maps already exist in the target map file, a prompt warning appears, giving you the option to overwrite the existing maps. To merge a map by dragging 1 In the Navigator, select the map(s) you want to merge.
Chapter 12 - Managing Maps Managing Maps Exporting a Map Source File Exporting a map source file enables you to store map definitions in xml format in a repository directory. The resulting xml file contains information on map settings, card settings, and map rules. The Map > Export command converts a map source file definition from the internal map format to the xml document form. To export a map source file 1 Select the map source file you would like to export.
Chapter 12 - Managing Maps Managing Maps The mapname.xml file generated with the Export command includes detailed information about the map: ♦ Map information and map settings ♦ Input card name and input card settings ♦ Output card name, output card settings, and map rules Note To view the exported XML file in a browser, use the mapsettings.dtd and the mms.dtd files provided in the install_dir\Examples directory.
Chapter 12 - Managing Maps Managing Maps A sample of exported card settings is shown here: Contact.txt
Chapter 12 - Managing Maps Printing in the Map Designer A sample of exported map rules is shown here: CityStateZip Field:Label City Field:Contact:ContactFile + ", " + State Field:Contact:ContactFile + " " + ZipCode Field:Contact:ContactFile FullName Field:Label Last Name Field:Contact:ContactFile + ", " + First Name Field:Contact:Con
Chapter 12 - Managing Maps ! Trace file ouptut ! Build results Printed Map Details ♦ Input cards (CardName, TypeTree, and Type) ! Detail of data objects on the card ♦ Output cards (CardName, TypeTree, and Type) ! Detail of data objects on the card and related map rules ♦ Compositional display of data objects on the card Printing a Map in the Map Designer Details can be printed for a map in the Map Designer: To print map details 1 Select a map in the Navigator.
Chapter 12 - Managing Maps Printed Map Details Printing Input and Output Cards The input and output cards can be printed as displayed. The Show All command should be used to print all data objects on the card. To print an input or output card 1 Place current focus on the input or output card. 2 Right-click and choose Show All to show all nested data objects. 3 Right-click the card title bar and choose Print. You can also export a map to obtain card settings documentation.
Chapter 12 - Managing Maps 3 Managing Cards Click OK. The output card run results window appears. 4 Right-click the desired run results window and choose Print from the context menu. The run results are printed. Managing Cards You can move, convert, copy, delete, and reorder cards. When using the Navigator to manage cards, use the List view. Moving a Card You can move a card from the input to the output (or from the output to the input) of the same map.
Chapter 12 - Managing Maps Managing Cards Copying a Card Cards can be copied to a different map source file or to the same map source file. You can copy a card within the same map by adjusting the new map name in the Copy Card dialog box. To copy a card by dragging 1 In the Navigator, press the Ctrl key while you drag the card name(s) to the input or output card icon ( or ) in the target map. To copy a card using the Copy command 1 In the Navigator, click the List tab.
Chapter 12 - Managing Maps Managing Cards 7 For the Copy Card As option, enable either the Input or an Output option button. 8 If desired, enter the name of the new card in the Name field. 9 Click OK. Deleting a Card Input and output cards can be deleted from maps. To delete a card using the Delete key 1 In the Navigator, click the List tab. 2 Select the card(s) you want to delete. 3 Press the Delete key. To delete a card using the Delete command 1 In the Navigator, click the List tab.
Chapter 12 - Managing Maps Editing a Card Editing a Card When you edit input and output cards, the map rules that were not affected by the change are retained. You can change anything specified in a map card: the card name, the type tree, the type of the card, and the data source or target. Changing a Card Name When a card name is changed, any reference to that card in any map rule is automatically changed to the new name.
Chapter 12 - Managing Maps Editing a Card The instances of Input in the map rule are automatically changed to GrowthReport. All instances of the card name are changed in all map rules where it appears. Changing the Type of an Input Card You can change the type (TypeName) of an input card. Note that when you change the type of an input card, if an object within that card is referenced in a map rule, the object name may now be invalid.
Chapter 12 - Managing Maps Editing a Card Not all modifications to an input type will affect map rules. For example, if you add a component to an input type, map rules are not affected. Also, if you delete an input component that is not referenced in a map rule, the map rules are not affected. Changing the Type of an Output Card You can change the type (TypeName) of an output card.
Chapter 12 - Managing Maps Effects of Modifying a Type Tree Effects of Modifying a Type Tree When you modify a type tree or any type definitions in that type tree, the next time you open a map that uses that type tree, the map is updated. If the map is currently open when you make changes to the type tree, a prompt appears asking if you want to update the map. Note Even if you saved the type tree, but did not make changes to the tree, you are still prompted to update the map.
Chapter 12 - Managing Maps Search Facilities in the Map Designer Search Facilities in the Map Designer The Map Designer supports standard search facilities. There are two Find commands: Find searches the selected object and More Find/Replace searches an entire map source file.
Chapter 12 - Managing Maps Search Facilities in the Map Designer If a match is located, the match is selected. Otherwise, there may be a message asking whether you want to continue searching. Using the Replace Command The Replace command replaces the found text in the Unresolved Rules tab in the organizer window, and the map rule in the rule bar. To replace text 1 Select the window where you want to do the search. For example, the Unresolved Rules tab in the organizer window.
Chapter 12 - Managing Maps Map Source File Differences 5 Optionally, enable the Match whole word only and/or the Match case check boxes. 6 Click Find All. To replace text within an entire map source file Tip 1 In the Replace with field, enter the text you want to replace. 2 In the With field, enter the text with which to replace it. 3 Disable the check box for the cards in which you do not want to replace text. 4 Click Replace. 5 Click Close.
Chapter 12 - Managing Maps Map Source File Differences Map source files are considered different if: ♦ A map exists in one map source file and does not exist in the other map source file. ♦ Any of the maps are different.
Chapter 12 - Managing Maps Map Source File Differences The Select First File dialog box appears. 2 Navigate your file system and select the first map source file to be compared. 3 Click Open. The Select Second File dialog box appears. 4 Navigate your file system and select the second map source file to be compared. 5 Click Open. The progress of the comparison is shown briefly in the Map Source File Differences Analysis dialog box and then the Map Source File Differences window appears.
Chapter 12 - Managing Maps Map Source File Differences To view map source file differences 1 Place current focus in the Map Source File Differences window. 2 Select any map or card to view the differences. The settings display in the lower windowpanes. Settings that have differences are indicated in red. 3 Press F8 to view the next difference. Press F7 to view the previous difference.
Chapter 12 - Managing Maps Map Source File Differences If any remarks in the Organizer window of the compared map files are different, the name of the map with differences appears red in the Map Source File Differences window. The Remarks tab in the lower windowpane is red. ♦ Data Audit Settings If any data audit settings defined in the Organizer window of the compared map files are different, the name of the map with differences appears red in the Map Source File Differences window.
Chapter 13 - Building Maps This chapter explains how to build a map and the errors that may occur when you build a map. Building Maps After you have entered map rules in an executable map, created necessary functional maps, and entered map rules for the desired output data objects, the next step is to build the executable map. A compiled map file is created when no build errors occur when the executable map, and all referenced maps, are analyzed.
Chapter 13 - Building Maps Building a Map Building a Map The Build command on the Map menu is used to build the active executable map. The Build command analyzes the logical interfaces within map rules, and if the analysis is successful, compiles the map. Analysis includes checking for missing rules, invalid rules, invalid card definitions, verifying map references, and verifying the arguments of functions. Analysis also looks for circular map references - maps that reference one another.
Chapter 13 - Building Maps Using the Organizer Window The error message shown above refers to an empty rule cell. A map rule is required for each rule cell on an output card. Edit the output card and enter a map rule. If a map rule is not required, no data transformation must occur for that output object. Use the = NONE map rule. Using the Organizer Window The Organizer window contains information about a selected map.
Chapter 13 - Building Maps Using the Organizer Window Modifying Unresolved Rules Unresolved rules may result from modifying the output type tree such that some output names have changed. You can modify the output names in the organizer window to match the new output names, and use the unresolved rules again. This is useful if there are many unresolved rules on output names that have changed in a similar way. After you modify the output names, the map rules are no longer unresolved.
Chapter 13 - Building Maps Using the Organizer Window Remarks Tab General comments or comments for particular data objects in a map can be entered on the Remarks tab in the organizer window. For example, to make your map user-friendly for another developer enter a comment about a particular map rule. Enter comments about a particular data object by dragging that object into the Topic field on the Remarks tab.
Chapter 13 - Building Maps Using the Organizer Window Entering a Remark for a General Topic You can enter a remark for a topic not associated with a particular object. For example, suppose you want to enter a general remark about when the map should be run. You can enter When to Run as the Topic, by simply typing it in. To enter a new remark, click on the last remark and press Enter. To enter a general remark 1 Select an empty Topic cell. 2 Enter the topic. 3 Enter the remark in the Remark field.
Chapter 13 - Building Maps Using the Organizer Window Trace Tab To view the trace file for the selected map, click the Trace tab on the organizer window or use any text editor to view the mapname.mtr file in the specified directory. The trace file is a text file that records map execution progress. Input data, output data, or both input and output data may be included in a trace file. The trace file should only be used for debugging purposes, because performance is impacted.
Chapter 13 - Building Maps Type Tree Errors See Chapter 17 - Debugging a Map for more detailed information on using the trace file. Type Tree Errors Each card in the map specifies a type and a type tree. Type trees referenced by the map must be analyzed and saved. If you build a map, and a type tree referenced by that map has not been analyzed, or it has been analyzed but produced at least one error, an error message to that effect appears. For example, if the type tree address.
Chapter 13 - Building Maps Map Build Analysis Errors Map Build Analysis Errors If a build error occurs, a map cannot be compiled until the problem is corrected. Build errors are written to the Build Errors tab on the Organizer window and to a map build analysis results file with the .mme file name extension. This .mme file is written to the folder where the map source file is located. If build errors occur, view the errors, correct the problem(s), and build the map again.
Chapter 13 - Building Maps Map Build Warning Messages Searching in the Organizer Window To search for text on the Trace, Audit Log, or Build Results tab, right-click on the desired tab and choose Find from the context menu. Map Build Warning Messages A build warning alerts you about a potentially problematic condition. If you build a map with warnings, but no errors, the map is successfully compiled. You can ignore warnings. To ignore warnings 1 From the Tools menu, choose Options. 2 Select General.
Chapter 13 - Building Maps Compiled Map Files 2 From the Map menu, choose Organizer. 3 Click the Build Results tab. Compiled Map Files If no errors occur, executing the Build command creates a compiled map file. The compiled map file is written to the folder where the map source file (.mms) is located. The name of the compiled map file is the name of the map that was built, with the .mmc file name extension. For example, successfully building a map called MyMap, creates the MyMap.
Chapter 13 - Building Maps Building a Map for Another Platform Platform-Specific File Name Extensions Maps built for execution on Windows platforms use the default .mmc compiled map file name extension. Maps built for specific platforms may have a platformspecific file name extension, as assigned in the Select Platform dialog box. The compiled map file name extension may be specified or changed as required. Tip Platform Extension HP Alpha Open VMS .mmc HP Alpha Tru64(UNIX) .
Chapter 13 - Building Maps Building a Map for Another Platform The Build for Specific Platform command creates a compiled map file in the format required for a given platform, which accounts for byte-order and character set differences on that platform. To build a map for a specific platform 1 Select the map you want to build. 2 From the Map menu, choose Build for Specific Platform. The Select Platform dialog box appears. 3 For the Platform, select the platform on which you plan to run the map.
Chapter 13 - Building Maps Building Maps from the Navigator Specific Platform command when your target platform has a different byte order or character set than the one in your map development environment. ♦ A platform-specific build is not required if you select a platform whose byte order and character set are the same as those on your development machine. If you do select one of these platforms, a message indicates that this platform does not require a platform-specific build.
Chapter 14 - Running a Map From the Map Designer After a map has been compiled, it can be run. When you run a map, the information in the compiled map file is used to create the output data. To run a map, use a the Map Designer, a Transformation Server, an Event Server, or an API. The Design Studio components include a Windows Command Server. You may also have a command server for another platform, such as AIX, Sun Solaris, HP-UX, or MVS. Some command servers have different command options.
Chapter 14 - Running a Map From the Map Designer Maps Error and Warning Messages Note Default map settings are set in the Run Options dialog box. After a map is created, select Settings from the Map menu to change the settings for the selected map. Maps Error and Warning Messages Map Designer error and warning messages provide information about map execution return codes, map build errors, map compile errors, and warning messages, and run time map return codes.
Chapter 14 - Running a Map From the Map Designer Run Results Closing Run Results Windows You can close multiple data windows at once.. To close all run results windows for a selected map 1 Select the map in the Navigator. 2 Click on the toolbar. To close all data windows 1 From the Window menu, choose Close All. Viewing Run Results with Shortcut Access Methods You can view run results for the selected map.
Chapter 14 - Running a Map From the Map Designer Run Results Viewing Run Results in Hex Mode You can view run results in hexadecimal mode. To view run results in hex mode 1 In the Run Results dialog box, enable the Display in Hex Mode check box. If you want the offset to be displayed by the decimal value, from the Tools menu, choose Options. For the Run Results, enable the Show offset in decimal values check box.
Chapter 15 - Managing Invalid Data This chapter explains how to map invalid data. You can map invalid data to an output, just like any other data. For example, you can place all invalid data in a separate output for editing or debugging purposes. You can map invalid data to an error report. To map invalid data, it must be contained in a valid object. A map does not run unless all input card objects are valid.
Chapter 15 - Managing Invalid Data Using the REJECT Function Error Report Example The following purchase order data is invalid: H 1422,04/23/97,TSI,Bennison’s Bakery M Urgent,Please hurry D Turtle,10,1.27 D Choc Chip Cookie,20,.34 T Lewis,042497 Bad data H 1379,05/09/97,TSI,Alpha Water Sports D Jet Skis,3,135.75 D Snorkle,4,13.35 D Inflatable boat,1,145.55 T Valerie,05/16/97 H 1770,05/10/97,TSI,Saxon's M Not urgent,Deliver in back D Backpack,3,12.
Chapter 15 - Managing Invalid Data Using the REJECT Function ♦ After the heading will be the invalid purchase orders. ! Define a BadPO item type to represent an invalid PO. ! Define BadPO as a text item with a minimum size of 0 and no maximum size. ! BadPO must be defined as a text item because the output of the REJECT function is a series of text items. ! Assign a restart attribute to the BadPO item type.
Chapter 15 - Managing Invalid Data Using the REJECT Function Create an output card for the invoice data. In addition, create an output card to represent the error report with the TypeName = ErrorReport. In the Orders input card, the PO type has the restart attribute.
Chapter 15 - Managing Invalid Data Using the ISERROR Function In the map rule for BadPO(s), use the REJECT function. The input argument of the REJECT function is a PO from the input. Shown below are the map rules used on the error report output card. When you run the map, you may see the message Attempting Restart and then Restart complete if an input is a UFO (unidentified foreign object).
Chapter 15 - Managing Invalid Data Using the CONTAINSERRORS Function In this input file of customers, the third customer record is invalid. Bad Gisela,1252 S. Broward/Ft. Lauderdale,523-2622,22 Dede,1513 Palatine Rd./Boca Raton,252-6560,86 Lewis,74099 S. 67th Ave/Ft. Lauderdale,332-8665,3.3 Eric,6933 Main St./South Miami Beach,291-7281,56 To generate a report that indicates whether each customer object is valid, assign a Restart attribute to Customer(s) in the input.
Chapter 15 - Managing Invalid Data Using the CONTAINSERRORS Function The map rule on CustomerEntry(s) uses the CONTAINSERRORS function to check if the entire List contains any errors. If List contains an error, no output is produced. If List does not contain errors, the Customer(s) will be mapped to CustomerEntry(s). The result is no output, because List does contain an error - the third Customer record is invalid.
Chapter 16 - Map Audit This chapter discusses map audit logs, including information about audit log contents, how to view the audit log, and so forth. Overview A map audit log is created when a map is executed. An audit log is based on a particular map and provides information about map execution, map settings, card settings, and specific data objects.
Chapter 16 - Map Audit Audit Log Contents Viewing the Audit Log If you have configured your map settings to include an audit log, you can view the audit log results from the Organizer window. To view the audit log 1 After the audit is configured in the map settings and the map is executed, select the map in the Navigator. 2 From the Map menu, choose Organizer. 3 Click the Audit Log tab. If the value of the AuditLocation map setting is File, the audit log file can also be viewed with a text editor.
Chapter 16 - Map Audit Audit Log Contents Some information is optional, and does not always appear in the ExecutionSummary element of the audit log. For example, information about objects found and built is provided only when using a command engine. WorkArea data is provided only when a work area is used during map processing. Elapsed Execution Time in the Audit Log The execution audit log records the elapsed time.
Chapter 16 - Map Audit Audit Log Contents Work Area Information By Card In the audit log, the work area information includes: ♦ Work area type (file or memory) ♦ Work area file name and time stamp if applicable ♦ Work area byte count Execution Summary Audit Log Sample The following is a sample of the execution summary portion of the audit log. PAGE 245Chapter 16 - Map Audit Audit Log Contents BurstAudit Execution in the Audit Log The MapAudit > Switch = On and the BurstAudit > Execution = On map settings produce an audit log with burst execution information. The burst element provides information on the performance of the burst. ♦ If all input cards have the FetchAs mode of Integral, there is one burst element in the audit log. ♦ If any input card has the FetchAs mode of Burst, there is one element for each burst.
Chapter 16 - Map Audit Auditing Data Content A sample of the burst audit data information is: Data Content Information in the Audit Log You can audit input and output data. The data audit settings determine what information about the data is written to the audit log. Auditing data keeps track of specified objects in the input(s) and/or output(s) of a map.
Chapter 16 - Map Audit Auditing Data Content 2 From the Map menu, choose Settings. 3 For the MapAudit setting, set the Switch to ON. 4 For the BurstAudit > Data setting, select ON. 5 Click OK. After you run the map, you can view the audit on the Audit Log tab in the Organizer. Data Settings in the Audit Log The MapAudit > Switch = On and the SettingsAudit > Data = On map settings produce an audit log with input and output card setting information.
Chapter 16 - Map Audit Auditing Data Content Data Settings in the Audit Log Sample A sample of the input and output data settings is: C:\mercator\Examples\stores.
Chapter 16 - Map Audit Auditing Data Content Map settings as seen in the audit log are: C:\mercator\Examples CallsSummary.
Chapter 16 - Map Audit Mapping from the Audit Log The audit log file is created as specified on the next map execution. After you run a map, the audit log file can be viewed on the Audit Log tab in the Organizer or from a text file (map_name.log) in the map directory. Mapping from the Audit Log Mapping information from the audit log can provide useful performance statistics and information about the content of your data. For mapping purposes, the audit_2.
Chapter 16 - Map Audit Mapping from the Audit Log ExecutionSummary element in the audit log provides performance data for the map as a whole. This information appears in the audit log when the SummaryAudit > Execution map setting = ON. As defined and viewed in the audit_2.
Chapter 16 - Map Audit Mapping from the Audit Log Summary source and target reports the adapter used for each, the total number of bytes processed over all bursts, and the final adapter return code. Configuring a Data Audit Use the Data Audit Settings tab in the Organizer window to specify what information about the data to include in the audit log. Audit logs are for a single map. To specify that you want to audit a particular object, drag that object from a card into the Data Audit Settings tab.
Chapter 16 - Map Audit Mapping from the Audit Log Detail In the Detail list on the Data Audit Settings tab in the Organizer window, specify what information to include about an object’s nested components. Value Description Occurrence A line appears in the audit log for each occurrence of that object of each nested component. Warning A line appears in the audit log for any nested component that causes a warning. Error A line appears in the audit log for any nested component that causes an error.
Chapter 16 - Map Audit Mapping from the Audit Log Elements in the Data Audit Log The audit log is in XML format. The audit_2.mtt type tree in the examples directory describes the audit log data. When BurstAudit > Data map setting is ON, and there is audit data, each burst in the audit log has a element. General data elements are defined as ZZ_Other DataLog.
Chapter 17 - Debugging a Map This chapter discusses various debugging aids and can assist you in situations where when running a map, the following types of errors occur regarding input or output data: ♦ data is invalid ♦ data contains invalid objects ♦ unknown data exists When you run a map, the input data is validated. Input data validation occurs by comparing the data to its definition in the type tree. After validating data, the output card map rules are evaluated and the output objects are built.
Chapter 17 - Debugging a Map Trace File For example, if you mistakenly defined an item to be an integer but the data is actually a decimal number, that data object is considered invalid because it does not match its type definition. To validate data, the data is compared to its definition. If data is determined to be invalid, either the data is bad or the definition is wrong. In addition, the command server window shows the progress as the data is mapped.
Chapter 17 - Debugging a Map Trace File The next time you execute that map, the trace file is created. If you ran a map and got a message that an input was invalid, turn on the input trace only. If you got a message that an output was invalid, turn on the output trace only. If you trace both input and output, the input messages are at the beginning of the file, followed by the output messages.
Chapter 17 - Debugging a Map Trace File For example, shown below is trace message for the Name data object: A sample portion of a trace file follows: (Level 2: Offset 0, len 6, comp 1 of 2, #1, DI 00000001:) Data at offset 0 ('Nicole') was found to be of TYPE X'0004' (Name Data). The level of an object indicates the position of the data object with respect to the entire card object. A card object has level 0; a component of the card object has level 1, and so on.
Chapter 17 - Debugging a Map Trace File Group Validation A group is valid if the syntax is valid and all of its components are valid. A group is validated component-by-component. A component is valid if its type is valid, its component range is valid, and, if the component has a rule, the rule evaluates to TRUE. Note When a component rule is evaluated, any invalid data used in a component rule is evaluated with a value of NONE.
Chapter 17 - Debugging a Map Trace File For the Database object of an input card, the type Database is composed of Row(s), and Row is composed of Name and Phone#. The data for the entire input database is: Nicole,352-2929 David,377-8098 In the trace file, there are messages for each Row and then there is a message for the entire card object, Database.
Chapter 17 - Debugging a Map Trace File Invalid Data When a data object does not match the definition of the type to which it presumably belongs, it could be invalid.
Chapter 17 - Debugging a Map Existence of Data Finding the Important Messages The best way to read the trace file is open it in a word processor and use the search facilities. The following table explains the trace options to choose and what to look for in the trace file, based on the run-time message. If You Get this Run-time Message One or more inputs was invalid. Input valid, but unknown data found.
Chapter 17 - Debugging a Map Existence of Data Record is partitioned into A, B, and C, the three types of records. Each record begins with a letter followed by an asterisk. The letter indicates the kind of record. This value is defined as the initiator for each record type. For example, an A Record begins with A*.
Chapter 17 - Debugging a Map Existence of Data It is known that B Record exists. When B Record is found to be invalid, validation continues with the following records. Shown below is part of the trace file, illustrating how validation continues: B Record is known to exist (Level 1: Offset 13, len 0, comp 1 of 1, #2, DI 00000001:) Type X'0007' (B Record Data) is known to exist.
Chapter 17 - Debugging a Map Unknown Data Unknown Data When input data is validated, additional data that does not validate as part of the input may also be found. This data is unknown data. An example input is composed of Product(s) and Product is not defined with properties that allow its existence to be predetermined. The second Product is invalid because the Quantity field is missing.
Chapter 17 - Debugging a Map Negative Messages Not Fatal Negative Messages Not Fatal Sometimes validation of a given data object interprets the given data object as belonging to a type to which it does not really belong. In this situation, the data object will fail to belong to that type - but that is because the data does not belong.
Chapter 17 - Debugging a Map Negative Messages Not Fatal The optional Message is missing from the data. After finding the Header, the next data object searched for is Message. However, the next object in the data is not a Message, it is a LineItem. This data object is first assumed to be a Message H D D D T 1379,05/09/97,TSI,Alpha Water Sports Jet Skis,3,135.75 Snorkle,4,13.35 Inflatable boat,1,145.
Chapter 17 - Debugging a Map Negative Messages Not Fatal Example of Partitioned Types Another case in which a data object may fail to belong to a certain type is when the type is partitioned and is validated as the object as a certain partition. If an object that is presumably a partition is validated, the validation process goes down the list of partitions and to determine the partition to which the object belongs. You may see a message that indicates an object failed to be a certain partition.
Chapter 17 - Debugging a Map Using the Audit Log as a Debugging Aid Shown below is a portion of the trace file, illustrating how the validation process determines that the record is a C Record: It does not have the initiator of an A Record (Level 1: Offset 34, len 0, comp 1 of 1, #4, DI 00000001:) Data at offset 34 ('C*sweater,15\r\nB*...') does not match INITIATOR 'A*' of TYPE X'0006' (A Record Data ).
Chapter 17 - Debugging a Map Run Results Windows Run Results Windows By viewing the results of a map execution, you may gain important information about how the data was mapped. For example, if no output objects are built, your input data may have been invalid. If you see only a small amount of output data, but you expected much more, it may be that your input data was valid, but it contained unknown data. Validation Map Settings You can selectively validate data.
Chapter 18 - Error and Warning Messages This chapter discusses map error and warning messages. Map Execution Error and Warning Messages After a map is executed, map execution messages indicate the execution results. If audit is enabled, these messages are also recorded in the appropriate audit log for the map. The following table lists all the codes and messages that can be returned as a result of running a map. Note The return codes marked with an asterisk (*) are warning codes.
Chapter 18 - Error and Warning Messages Map Execution Error and Warning Messages Return Code Message 6 Invalid map handle Contact Mercator Technical Support. 7 Invalid card number was specified Your map may be corrupt. Contact Technical Support. 8 One or more inputs was invalid Turn the input trace on, run the map again and read the trace file. 9 Target not available An incorrect file name or path for a target may be specified. 10 Internal error Contact Mercator Technical Support.
Chapter 18 - Error and Warning Messages Return Code Message 17 Disk read error Map Execution Error and Warning Messages An attempt may have been made to access a file on a shared resource that is not accessible. Also, check the amount of available disk space. 18* Page usage count error Your data mapped correctly; however, an internal paging problem exists. Contact Mercator Technical Support. 19 Internal calling error Contact Mercator Technical Support.
Chapter 18 - Error and Warning Messages Map Execution Error and Warning Messages Return Code Message 26* Output type in error The entire card object is in error. 27* Output type contains errors One or more components failed restrictions or a component rule. 28* Input type contains errors This occurs when mapping data of a component that has a RESTART assigned to it, and at least one instance of the component in the input data is invalid.
Chapter 18 - Error and Warning Messages Map Execution Warning Messages Map Execution Warning Messages The following table lists the return codes that are warnings only – meaning that the map did complete, but some problems occurred. You can change the default behavior for the warning codes by specifying Fail on Warnings or Ignore Warnings through the map settings or by using the –F or –Z execution command.
Chapter 18 - Error and Warning Messages Map Build Error Messages Return Code Message 29* Output valid, but unknown data found This occurs when enough of the output data is recognized to conform to the card definition, but there was more data at the end of the output stream. 34 Too few pages requested, more allocated The map can complete but it can be better optimized by increasing the page count. Map Build Error Messages Build errors prevent a map from being compiled.
Chapter 18 - Error and Warning Messages Return Code Message M102 Map: x Output: y Map Build Error Messages Functional map referenced in rule must have one (and only one) output. Map referenced: map-name. Hint: Go to the functional map. Delete the extra card(s). M103 Map: x Output: y Number of arguments for functional map map-name is incorrect. Number specified: #specified Number required: #required Hint: Add or delete arguments from the rule, or add or delete input cards in the functional map.
Chapter 18 - Error and Warning Messages Return Code Message M107 Map: x Output: y Map Build Error Messages Rule syntax is invalid starting at character position: position#. Rule Hint: This error may occur if a previous Mercator version did not catch the syntax error. Generally, syntax errors are caught as rules are entered. Refer to the Release Notes for any changes in rule syntax. M108 Map: x Output: y Rule references unknown map: map-name. Hint: Re-enter the map name in the rule.
Chapter 18 - Error and Warning Messages Return Code Message M112 Map: x Output: y Map Build Error Messages Argument #w for map map-name does not match item sub-class of card #z. Hint: Change argument #w so that it matches the item sub-class of input card #z, or change the type of input card #z so that its item sub-class matches argument #w. M113 Map: x Output: y Argument #w for function function name is invalid. Hint: Select the rule for output, y.
Chapter 18 - Error and Warning Messages Return Code Message M117 Map: x Output: y Map Build Error Messages Cannot assign an output to itself. Hint: You might have accidentally dragged and dropped an output into its own rule cell. Edit the rule. M118 Map: x Output: y Rule references unknown comment: commentname @ inputname Hint: The input card type does not have a floating component, or you have incorrectly typed in the name.
Chapter 18 - Error and Warning Messages Map Build Warning Messages Return Code Message M123 Map: x Card: cardname Card updates input, but card type and data file do not match an input. Hint: Edit the card and re-define the update information. M124 Map: x Output: y Rule references type later in output: rule Hint: If possible, enter an equivalent rule in a later output. An output referenced in a rule must appear above the rule within the output card.
Chapter 18 - Error and Warning Messages Map Compile Error Messages Map Compile Error Messages The compile errors display on the Build Results tab of the Organizer. Maps with compile errors may not be run. Correct all compile errors to run a map. The following table lists the errors than can result when a map is built: Return Code Message M1001 Compile aborted by user. Hint: You cancelled the build process before it completed. M1002 Not enough memory available to compile.
Chapter 18 - Error and Warning Messages Map Compile Error Messages Return Code Message M1009 Unable to open the type tree for output card. Hint: The type tree may not exist in the directory specified or the type tree may be corrupt. M1010 Unable to find a type in an input tree. Hint: If you get this error, please contact Technical Support. M1011 Unable to find a type in an output tree. Hint: If you get this error, please contact Technical Support. M1012 Could not retrieve query information.
Chapter 18 - Error and Warning Messages Map Compile Error Messages Return Code Message M1021 Error writing to the compiled map file. (Disk full?) Hint: Delete unnecessary files from your hard disk. M1022 Unable to resolve type references in audit. Hint: If you get this error, please contact Technical Support. M1023 Unable to open .MDQ file. Hint: The .mdq file does not exist or is otherwise inaccessible. M1024 Database not found. Hint: The named database is not defined in the specified .mdq file.
Chapter 18 - Error and Warning Messages Audit Log Status Codes Audit Log Status Codes The status attribute in the Audit Log is a letter followed by a code number. The letter of the status attribute tells whether the data is valid V, or caused an error E, or caused a warning W. Valid Audit Log Status Codes The following table explains the number in the status code if the letter is V.
Chapter 18 - Error and Warning Messages Audit Log Status Codes Status Code Description E03 Object failed size check E04 Invalid or missing initiator E05 Invalid or missing terminator E06 Object missing required component E07 Object is invalid because it contains components in error E08 Object failed partitioning E09 Object failed component rule E10 This required object is missing E11 Invalid or missing delimiter E12 More instances of an object exist than have been specified (Only impl
Index Delete, 46 Edit, 38, 46 New, 38, 46 Reorder, 46 card settings, 77 CardName, 77 differences, 215 exporting, 197 input and output cards, 77 TypeName, 79 CardName, 78 card setting, 77 guidelines for naming, 78 cards, 71 compositional hierarchy, 71 converting, 202 copying, 203 deleting, 204 editing, 204, 205 icons, 70 managing, 202 moving, 202 multiple in a functional map, 149 name changing, 205 names in map rules, 114 naming guidelines, 78 specific details, 70 Century map settings, 180 choice groups, 31
Index D cards, 204, 205 editing a type tree effects on a map, 208 ellipses, 117 error audit log status codes, 285 errors data, 234 tracking with the audit log, 269 evaluation of map rules, 107 executable map definition of, 140 expression examples, 105 EXTRACT function, 124, 142 copying a map, 193 cards, 203 creating map in a map source file, 66 map source file, 66 customization options, 49 D data errors tracking with the audit log, 269 evaluating to NONE, 125 incrementing using a functional map, 162 inva
Index G input and output card settings, 77 input card, 69 definition of, 68 specific details, 70 view of an input card, 72 interface, 17 Interval card setting, 96 Introduction, 13 invalid data recovering from, 234 tracking with the audit log, 269 ISERROR function, 238 item automatic item conversions, 127 map rule for, 127 name in a map rule, 141 syntax of, 141 using to increment data, 162 using to re-order data, 163 when data is missing, 142 functional map wizard icons, 155 Functional Map Wizard, 153 func
Index N functional, 135, 153 map build errors, 276 map build warnings, 281 map compile errors, 282 map execution errors and warnings, 271 map execution warnings, 275 merging, 195 messages, 271 moving, 193 name guidelines, 67 porting, 226 valid audit log status codes, 285 warning audit log status codes, 285 MapTrace settings, 175 MaxAttempts card setting, 96 menus Card, 46 Edit, 43 File, 41 Help, 48 Map, 44 Rules, 46 Tools, 47 View, 44 Window, 48 merge command, 195 merging maps, 195 missing data, 125 when a
Index P run command, 230 run options, 231 run results printing, 201 shortcut access method, 232 viewing, 231 OnSuccess card setting, 92 Options dialog box, 49 Organizer window, 32 output referring to in a map rule, 163 with a range map rule for, 129 output card, 69 definition of, 68 specific details, 70 view of an output card, 73 Overview, 13 S Scope card setting, 89, 94 FetchAs and Scope actions, 89 searching in the organizer window, 225 selecting TypeName for card, 79 selecting objects, 191 selection c
Index U Toolbar(s), 44 viewing build results, 224 floating component type, 133 trace file, 257 viewing, 222, 257 trace file, 256 trace files, 177 ranges for InputContentTrace, 177 Transaction card setting, 87, 92 type editing a type referenced in a card, 208 type properties viewing, 118 type tree analyzing, 223 TypeName card setting, 79 TypeTree card setting, 78 W warning audit log status codes, 285 warnings build, 225 Warnings settings, 185 Window menu, 48 Window menu commands Arrange Icons, 48 Cascade,
