HP NonStop Data Transformation Engine Execution Commands Reference Guide Abstract This document provides information about using execution commands to control how a map is run by an HP NonStop™ Data Transformation Engine (NonStop DTE) Command Server or by using the NonStop DTE API. Product Version NonStop Data Transformation Engine 6.7.
Document History Part Number Product Version Published 427620-001 NonStop Data Transformation Engine 1.0 December 2000 522439-001 NonStop Data Transformation Engine 5.0.3 November 2001 522439-002 NonStop Data Transformation Engine 6.7.1 June 2004 522439-003 NonStop Data Transformation Engine 6.7.
Contents About This Document Related References........................................................................................... 5 Chapter 1 - Executing Maps Command Server Overview ................................................................................. 6 Coordinating Execution Commands with Compiled Settings ..................................... 7 Compiled Map Files...................................................................................... 8 Command Files ...................
About This Document Related References Using a Run Function and Echoed Outputs in Memory ................................................ 55 Audit Log in Memory ........................................................................................
About This Document This document contains information about the Mercator Execution Commands. This document assumes that the reader knows the Windows environment, has used the Mercator Design Studio, and understands words such as mapping, type trees, source, target, rollback, retry and other basic Mercator terminology. Related References The Mercator Online Library and the SDK Online Library contain information about all products.
Chapter 1 - Executing Maps This chapter discusses the various ways to use execution commands and their options when executing maps. Execution commands are used to specify how to execute a map.
Chapter 1 - Executing Maps Command Server Overview Coordinating Execution Commands with Compiled Settings The following table lists valid execution commands and the MapSetting or input/output card settings that they override.
Chapter 1 - Executing Maps Command Server Overview Card Settings Execution Command Card Setting Input Overrides (-I) WorkFiles (W) SourceRule > FetchAs > WorkArea Retry (R) SourceRule > GET > Retry Rollback (B) SourceRule > GET > Transaction > OnFailure Delete (X) SourceRule > GET > Transaction > OnSuccess Output Overrides (-O) Retry (R) TargetRule > PUT > Target > Retry Append (+) TargetRule > PUT > Transaction > Target > OnSuccess Delete (X) TargetRule > PUT > Transaction > OnSuccess Rol
Chapter 1 - Executing Maps Command Server Overview Integration Flow Designer Using the Integration Flow Designer, you can create systems of maps and define execution settings, map settings, and input/output settings. These settings are recorded into the compiled map file that results from building the map within the Integration Flow Designer. If the system has an execution mode of Command, a command file can be generated that can be executed with a Command Server.
Chapter 1 - Executing Maps Using Command Server Commands Command Files You can create command files that contain listings of maps to execute with execution commands that specify how you want each map to run. A command file is a text file that can contain multiple maps to run, as well as multiple execution commands and options for each map; however, a command file cannot run another command file.
Chapter 1 - Executing Maps Using Command Server Commands From a Command Line You can execute a particular map or a command file containing a list of maps to execute from the command line of the system hosting your Command Server. The syntax is: MERCATOR|MERCNT {map [exec_command…]|@command_file}… Note Ensure your current directory is where the Command Server is located or specify the relative path or full path, as applicable, when entering the command.
Chapter 1 - Executing Maps Using Command Server Commands From the Platform API To run the server using a Platform API, as part of an argument to the RunMap() function, specify: map [exec_command…]|@command_file Option Description map Specify the name of the compiled map (.mmc) file to run. If applicable, include the full path or a relative path to the directory that contains the map file.
Chapter 2 - Execution Commands This chapter discusses the execution commands and associated options, including the syntax of each command and its particular usage. List of Execution Commands The following is a list of execution commands and the command syntax.
Chapter 2 - Execution Commands Name List of Execution Commands Syntax Message -IM[alias]card_num[W|!W][X|X0][Rc:i][B] [K['filename']|[+'filename']|[U'filepath']|[U]| [1'filename']|[1+'filename']|[U1'filepath']|[U1]] {src-adptr-cmd|.} List -L Output (Target) Overrides Application -OA[alias]card_num[Rc:i][B] [K['filename']|[+'filename']|[U'filepath']|[U]| [1'filename']|[1+'filename']|[U1'filepath']|[U1]] {target-adptr-cmd|.
Chapter 2 - Execution Commands List of Execution Commands MapAudit (-A) Use the MapAudit execution command (-A) to control the creation of audit log information. Using this command, audit information is recorded which can include data audit information and execution audit information. When used with other specified options, the MapAudit settings specified with the MapAudit command (-A) override all MapAudit settings compiled into the map.
Chapter 2 - Execution Commands List of Execution Commands Option Description 1|2 1 is the audit code for fail size (WrongSize). 2 is the audit code for fail minimum size or fail maximum size (TooLongTooShort). Note If using the 1 or 2 option as well as the R or W option with the D sub-option, the 1 or 2 must follow the R or W. For example: -AEDW2 This example represents SummaryAudit Execution, SummaryAudit Data, OnWarning, and TooLongTooShort.
Chapter 2 - Execution Commands List of Execution Commands Option Description C The card (data) settings audit information includes: ♦ the data settings for sources and target cards P The map settings audit information includes: ♦ the map settings M The memory setting can be used only when the map is run by the RUN() function or an API. If memory is set, audit information is stored in memory and appended to the last set of data returned during map execution.
Chapter 2 - Execution Commands List of Execution Commands Option Description U Generate audit files with unique names each time the map is run. The name of the audit log for top-level maps is mer___.log, where map_counter is a value representing each unique instance of a map within the same process. Run maps use run___.log. Unique names are globally unique; each process has a unique value.
Chapter 2 - Execution Commands List of Execution Commands -AD2 BurstAudit Data, TooLongTooShort -AB BurstAudit Execution -AE SummaryAudit Execution -AC SettingsAudit Data -AP SettingsAudit Map -ABD BurstAudit Execution and BurstAudit Data -AEB SummaryAudit Execution and BurstAudit Execution -ABDE BurstAudit Execution, BurstAudit Data, and SummaryAudit Execution -AEDW2 SummaryAudit Execution, SummaryAudit Data, OnWarning, and TooLongTooShort -AER SummaryAudit Execution and OnError -ADW
Chapter 2 - Execution Commands List of Execution Commands -D[ccyy|0] Option Description ccyy A missing century for a Date & Time item is derived based on the ccyy value. 0 Turn off the Century execution command. For example, if you specify -D1960, a YYMMDD-formatted date between 60mmdd and 99mmdd is interpreted as having a century value of 19. Dates between 00mmdd and 59mmdd are interpreted as having a century value of 20.
Chapter 2 - Execution Commands List of Execution Commands -F! A map-failed message is not returned when any of the warning codes is encountered. -F18 A map-failed message is returned when a Page Usage Count Error (18) is encountered. -F!18 Excluding the Page Usage Count Error (18), a map-failed message is returned for all of the other warning codes. -F18:27:28 A map-failed message is returned when any of the specified warning codes is encountered (18, 27, or 28 in this case).
Chapter 2 - Execution Commands List of Execution Commands Option Description R Ignore restrictions for all items appearing in the input data. Note Restrictions of syntax items are not ignored because they are used in determining the value of a syntax object. Ignore the presentation settings of items. P For example, if a number is defined as an integer but it appears in the data as a decimal number, it validates anyway.
Chapter 2 - Execution Commands Option List of Execution Commands Description adapter. For example, FTP is the adapter alias for the FTP adapters. See the appropriate adapter documentation in the Resource Adapters Reference Guide. card_num This is the card number of the input to override. W After a map runs for the first time, the work area created for the input card is not deleted.
Chapter 2 - Execution Commands List of Execution Commands Option Description K+'filename' When the map, burst, or card runs, a backup file will always be appended to filename. Note If 'filename' is not an absolute path, the map directory will be pre-pended. KU'filepath' When the map, burst, or card runs, a backup file will always be created using a unique backup name in the directory filepath. Note If 'filepath' is not an absolute path, the map directory will be pre-pended.
Chapter 2 - Execution Commands List of Execution Commands Option Description src-adptr-cmd This option provides the adapter-specific commands (up to 260 characters) to connect to the data source and retrieve the input data. See the adapter-specific documentation in the Resource Adapters Reference Guide. . Use Command in the compiled map file.
Chapter 2 - Execution Commands Option List of Execution Commands Description compiled into the map are used. To eliminate adapter retry, specify R0:0. B If the map, burst, or card does not complete successfully, roll back any changes that were made to this data source. Note If this option is not specified, the OnFailure setting compiled into the map is used. K When the map, burst, or card runs, no backup file will be created.
Chapter 2 - Execution Commands List of Execution Commands Option Description K1+'filename' If the map, burst, or card does not successfully complete, a backup file will be appended to filename. Note If 'filename' is not an absolute path, the map directory will be pre-pended. KU1'filepath' If the map, burst, or card does not successfully complete, a backup file will be created using a unique backup name in the directory filepath.
Chapter 2 - Execution Commands List of Execution Commands Option Description !W The WorkArea for input is created when map execution begins. source This is the data to be used for the input.
Chapter 2 - Execution Commands List of Execution Commands Option Description W After a map runs the first time, the WorkArea created for the input card is not deleted. For subsequent executions of the same map, the data for this input card is not validated and the WorkArea information for the card is retrieved from the existing WorkArea. !W The WorkArea of the input is created when map execution begins. X If the map, burst, or card completes successfully, the input data file is deleted.
Chapter 2 - Execution Commands List of Execution Commands Option Description K'filename' When the map, burst, or card runs, a backup file will always be created to filename. Note If 'filename' is not an absolute path, the map directory will be pre-pended. K+'filename' When the map, burst, or card runs, a backup file will always be appended to filename. Note If 'filename' is not an absolute path, the map directory will be pre-pended.
Chapter 2 - Execution Commands List of Execution Commands Option Description KU1 If the map, burst, or card does not successfully complete, a backup file will be created using a unique backup name in the map directory. source Specify the name of the input file (up to 260 characters). If the input file is not located in the same directory as the map file, the full path must be specified using the platform-specific syntax. . Use the FilePath in the compiled map file.
Chapter 2 - Execution Commands List of Execution Commands Option Description X0 If the map, burst, or card completes successfully, the message is deleted from its source, only if it has no content. Note If neither delete option (X or X0) is specified, the OnSuccess setting compiled into the map is used. Rcount:interval Specify Retry settings.
Chapter 2 - Execution Commands List of Execution Commands Option Description KU'filepath' When the map, burst, or card runs, a backup file will always be created using a unique backup name in the directory filepath. Note If 'filepath' is not an absolute path, the map directory will be pre-pended. KU When the map, burst, or card runs, a backup file will always be created using a unique backup name in the map directory.
Chapter 2 - Execution Commands List of Execution Commands List (-L) When using a Command Server on a platform other than Windows, use the List execution command (-L) to display a list of the data sources and targets that are compiled into a map file. Note This command does not execute the map; it displays the list of sources and destinations. For example, to display the sources and destinations for the sample SDQ map, enter the following: ./mercator sdq.
Chapter 2 - Execution Commands Option List of Execution Commands Description adapters. See the appropriate adapter documentation in Resource Adapters Reference Guide. card_num This is the card number of the output to override. Rcount:interval Specify Retry settings. If the target is unavailable, the adapter attempts to access the target as many times as specified by the count setting at the interval specified by the interval setting.
Chapter 2 - Execution Commands List of Execution Commands Option Description KU When the map, burst, or card runs, a backup file will always be created using a unique backup name in the map directory. K1'filename' If the map, burst, or card does not successfully complete, a backup file will be created to filename. Note If 'filename' is not an absolute path, the map directory will be pre-pended.
Chapter 2 - Execution Commands List of Execution Commands -ODcard_num[Rcount:interval][B] [K['filename']|[+'filename']|[U'filepath']|[U]| [1'filename']|[1+'filename']|[U1'filepath']|[U1]] {target-adptr-cmd|.} Option Description card_num This is the card number of the output to override. Rcount:interval Specify Retry settings. If the target is unavailable, the adapter attempts to access the target as many times as specified by the count setting at the interval specified by the interval setting.
Chapter 2 - Execution Commands List of Execution Commands Option Description KU'filepath' When the map, burst, or card runs, a backup file will always be created using a unique backup name in the directory filepath. Note If 'filepath' is not an absolute path, the map directory will be pre-pended. KU When the map, burst, or card runs, a backup file will always be created using a unique backup name in the map directory.
Chapter 2 - Execution Commands List of Execution Commands Output Target Override – Echo (-OE) Use the Output Target Override – Echo execution command (-OE) to override specifications in the compiled map file for a specific output card for a single execution of a map. Use this command when you want the data resulting from one or more output cards passed back to a calling application or a map, rather than being directed to a file, database, application, or message.
Chapter 2 - Execution Commands List of Execution Commands Output Target Override – File (-OF) Use the Output Target Override – File execution command (-OF) to override data destination specifications for a specific output card in a compiled map file for a single execution of a map. -OFcard_num[+|!+][X|X0][Rcount:interval][B] [K['filename']|[+'filename']|[U'filepath']|[U]| [1'filename']|[1+'filename']|[U1'filepath']|[U1]] {target|.
Chapter 2 - Execution Commands List of Execution Commands Option Description K'filename' When the map, burst, or card runs, a backup file will always be created to filename. Note If 'filename' is not an absolute path, the map directory will be pre-pended. K+'filename' When the map, burst, or card runs, a backup file will always be appended to filename. Note If 'filename' is not an absolute path, the map directory will be pre-pended.
Chapter 2 - Execution Commands List of Execution Commands Option Description KU1 If the map, burst, or card does not successfully complete, a backup file will be created using a unique backup name in the map directory. target Specify the name of the output file (up to 260 characters). If the output file is not located in the same directory as the map file, the full path must be specified using the platformspecific syntax. . Use the FilePath in the compiled map file.
Chapter 2 - Execution Commands List of Execution Commands Option Description Rcount:interval Specify Retry settings. If the target is unavailable, the adapter attempts to access the target as many times as specified by the count setting at the interval specified by the interval setting. number of attempts to access the message queue. count interval number of seconds to wait between attempts Note If this option is not specified, the Retry settings compiled into the map are used.
Chapter 2 - Execution Commands List of Execution Commands Option Description KU When the map, burst, or card runs, a backup file will always be created using a unique backup name in the map directory. K1'filename' If the map, burst, or card does not successfully complete, a backup file will be created to filename. Note If 'filename' is not an absolute path, the map directory will be pre-pended.
Chapter 2 - Execution Commands List of Execution Commands If this execution command is used without a corresponding WorkSpace execution command (-W), the WorkSpace settings in the compiled map are used. Generally, for large data files, you may want to increase the number of pages by specifying a large count. For maps that include a large number of type references, you may want to increase the page size.
Chapter 2 - Execution Commands List of Execution Commands Note If you specify the MapTrace execution command (–T), you must specify all desired MapTrace settings because the settings in the MapTrace execution command override all MapTrace settings in the compiled map. -T[I|ICcard_num|Ifrom[:to]][O|OCcard_num][S][=dir] Option Description I This produces detailed trace information for all input cards. Iccard_num This produces detailed trace information for a single input card.
Chapter 2 - Execution Commands List of Execution Commands Stop Validation (-V) The Stop Validation execution command (-V) specifies to stop validation at the card where the first error is detected. When this command is used, validation occurs only through the input card where the first error is encountered. Map execution is stopped after validating that input card, even if there are multiple input cards. Under certain circumstances, multiple errors are detected during validation.
Chapter 2 - Execution Commands List of Execution Commands Option Description D A file-based WorkSpace is used. The work files are deleted after a map is executed. All work files are deleted, except those being saved for reuse as specified on the input cards for each map. U A file-based WorkSpace is used. A unique name is generated for each work file created and the files are automatically deleted after the map is executed.
Chapter 2 - Execution Commands List of Execution Commands Ignore Warnings (-Z) The execution Ignore Warnings execution command (-Z) specifies for a map that selected warning codes should be ignored and a 0 return code should be issued. When –Z is used with one or more warning codes, a 0 return code is issued for those warning codes. When used without other options specified, all warning codes result in a 0 return code Using this command impacts OnSuccess settings, OnFailure settings, and so on.
Chapter 2 - Execution Commands Command Availability If the Ignore Warnings command (-Z) is enabled and a map encounters the condition for any warning code as specified, the execution section of the audit log includes a Valid map status with a 0 return code and the associated warning message. For example: 0.1026 Input type contains errors. 'C:\Merc20\EXAMPLES\ANSIACK\ReceiveEDI.
Chapter 2 - Execution Commands Command Availability Command Server Function Platform API Echo (-IE) √ √ √ File (-IF) √ √ √ Message (-IM) √ √ √ Execution Command List Sources/Targets (-L) RUN √ Platform Availability Non-Windows only Target Overrides * Application (-OA) √ √ √ Database (-OD) √ √ √ Echo (-OE) √* √ √ File (-OF) √ √ √ Message (-OM) √ √ √ WorkSpace PageSize (-P) √ √ √ Refresh Status (-R) √ MapTrace (-T) √ √ √ Stop Validation (-V) √ √ √ Wor
Chapter 3 - Examples This chapter presents a variety of examples involving the execution of maps using various execution commands in a RUN() function and from the command line in UNIX and Windows environments. Running a Map Located in a Different Directory From a UNIX command line, enter: /mercator/mercator /x12/edi.mmc -TIO -IF2!WXR5:1 dtin -OF1B out.txt Option Description /X12/edi.mmc This specifies the full path and name of the map to be executed.
Chapter 3 - Examples Creating Work Files in an Alternate Directory Creating Work Files in an Alternate Directory From a Windows command line, enter: c:\\mercnt k:\maps\invoices.mmc -AE -T WD=c:\tmp Option Description k:\maps\invoices.mmc This specifies the name of the map to be executed. -AE This produces an execution audit log using the AuditLocation settings for MapAudit compiled into the map file. -T This specifies that no trace information is to be produced.
Chapter 3 - Examples Overriding a Database Target Option Description that precede it on the command line. -F Fail on the return of any warning code. -Y10:2 If any non-data file resource is unavailable, such as the map file, audit log file, work file, and so on, up to ten attempts should be made at two-second intervals to access the unavailable resource. Overriding a Database Target Suppose you want to run the map multitran.
Chapter 3 - Examples Executing a Command File Executing a Command File As an alternative to typing execution commands on the command line, you can run maps using maps and execution commands in a command file. To use a command file named cmd_file.txt, from a UNIX command line, enter: mercator @cmd_file.txt A command file can contain spaces and/or new lines to separate arguments and maps to be run. The following is an example of a command file to be executed on a UNIX platform: /x12/edi.
Chapter 3 - Examples Audit Log in Memory The most common use for this feature of echoed outputs is when the data for an output card is needed only during the execution of the map, perhaps for use on a later output card, and can be discarded after the map has completed execution. Note For another example of using an echoed data destination, see the Platform API Reference Guide.
Index - help, 11 command options examples of using creating work files in a different directory, 53 mapping from an application, 54 running a map from a different directory, 52 running multiple maps from a single command, 53 using a command file, 55 Command Server, 6 commands,using, 10 compiled map files, 8 A execution command, 15, 56 B execution command, 19 D execution command, 19 F execution command, 20 G execution command, 21 IA execution command, 22 ID execution command, 25 IE execution command, 27 IF
Index F memory page size and count explanation, 44 Stop Validation (-V), 47 when running from a map rule, 12 when running from a platform API, 12 WorkSpace (-W), 47 WorkSpace PageSize (-P), 44 O OnError SummaryAudit setting, 15 OnWarningsOrError SummaryAudit setting, 15 output stored in memory, 55 Output Target Override – Application (-OA), 34 Output Target Override – Database (-OD), 36 Output Target Override – Echo (-OE), 39, 55 Output Target Override – File (-OF), 40 Output Target Override – Message (-
