Running locally

The Run Locally command that is on the menu for the map, is enabled for DataPower maps.

• The command is used to run DataPower maps locally on the system, instead of on IBM DataPower SOA Appliances.
• All of the map settings, MapAudit in File, MapTrace, and WorkSpace in File, in addition to the Backup card setting that IBM DataPower SOA Appliances do not support, are supported when you run DataPower maps locally.
• To troubleshoot and debug your map, you can specify the following options to generate the map audit and trace log files:
  • Set the Switch setting for the MapTrace map setting to ON in the Map Settings window.
  • Specify the audit context name in the ITX Audit Log map audit setting in the Appliance Configuration options in the DataPower preferences window.

    When you run maps locally, you must specify the ITX Audit Log map audit setting to generate the map audit log. You specify this setting in this same way whether you are testing DataPower maps by running them on a WebSphere DataPower SOA Appliance, or locally, or whether you are running them on a WebSphere DataPower SOA Appliance from the Map Designer.

    If the MapAudit > AuditLocation setting on the DataPower map is set to Memory, the map audit log is saved in the map directory and named after the executable map (map_name.log).

• To support map warnings, select Support ITX Warnings option under Appliance Configuration options for DataPower. The mapping process uses the values that you set for the Warnings property in the map settings. If the warning setting is not selected, the mapping process handles all map warnings as failures, unless the Warnings > Return setting is specified as Ignore. When you specify Warning > Custom, the mapping process handles those map warnings that are set as Warn or Fail as failures, while those map warnings set as Ignore, are ignored. To be able to use the Restart attribute and the REJECT function, the map warnings setting must be specified as Ignore. At run time, when the map detects invalid objects, it ignores them and continues processing.
• The mapping process sets the DocumentVerification setting to Well Formed for all input cards of the map and then runs the map with that setting. It calls the external parser for document verification only for the well-formed document. So there is no external schema validation for DataPower maps.
• When you locally run a DataPower map that is compiled with a static input file, the mapping process validates the static input file in the compiled map only once, when the map loads, and creates a trace file in the map directory only if the static file input fails validation.
• If the map input source and output target cards specify adapters other than ECHO, SINK, or STATIC FILE, you must use the -IE, -OE, or -OASINK command-line options to override the adapters. You can use the ECHOIN or HANDLEIN functions to override the adapters in the map input source cards. If you do not override the input source or output target adapters that are not supported for RUN maps, for example, the FILE adapter, the mapping process returns Source not available (12) or Target not available (9) errors.
• The following commands and command options are supported when you run DataPower maps locally even though they are not supported on IBM DataPower SOA Appliances:
  • -T (MapTrace) command
  • -W (WorkSpace) command
  • K (Backup) option with -OASINK command
  • U, +, !+, ={file|dir} options with -A (MapAudit) command
• The EN, EA, EF, ES (DocumentVerification) options with -IE, -OE, or -OASINK commands are ignored.
• When you run DataPower maps locally, the mapping process ignores the absolute map URL path that references a RUN map. Instead, the mapping process searches for the RUN map in the map directory. Absolute map URL paths start with local:///, store://, http://, or https://.
• Relative paths that contain the parent directory (..) notation, are not valid on IBM DataPower SOA Appliances and when you run the DataPower map locally. If you specify relative paths in this way, the mapping process returns Could not open map(3) error. The mapping process resolves the relative RUN map paths that are based on the map directory of the parent map.
• When you run DataPower maps locally, the mapping process ignores the absolute resource URL path that references a resource located either on the appliance or that is remotely accessible to the appliance when specified for the XML functions (such as XPATH, XSLT, or XVALIDATE). Instead, the mapping process searches for the resource in the map directory. Absolute map URL paths start with local:///, store://, http://, or https://.
• Relative resource paths that contain the parent directory (..) notation are not valid on WebSphere DataPower SOA Appliances when you run the DataPower map locally. If you specify relative resource paths in this manner for the XML functions, the mapping process returns an error. The mapping process resolves the relative resource paths that are based on the map directory of the parent map.
• DataPower maps that are run locally also support paths that start with current://. Resource paths starting with current:// are run like the relative resource paths defined above. In this scenario, current:// equates to the . (current directory) notation in relative paths and is substituted for the parent map path during transformation. DataPower maps do not support file:// URL paths in the XML functions.
• DataPower appliances use their own methods to process some XML functions (such as XPATH, XSLT, or XVALIDATE), and map runtime behavior differences may occur when running DataPower maps on an appliance against running them locally on the system. Errors reported with the LASTERRORMSG function might differ between appliance and local runs of DataPower maps.

Default map settings are set in the Run Options window that you open from Window > Preferences > Transformation Extender > Map > Run Options. After a map is created, select Map Settings from the Map menu to change the settings for the selected map.

You can override the original map and card settings of the DataPower map in the Map Designer. In the Extender Navigator view, right-click the DataPower (.dpa) map in the Map Executables folder, and on the menu, click Map Settings. Use this feature to test different combinations of map and card settings dynamically with the same DataPower (.dpa) map without recompiling the source map.

To run a DataPower map locally: