Map audit log

When the MapAudit Log Switch setting is set to ON, you can select to have either execution information or data information recorded. You can also specify to have both execution and data information recorded for a complete picture of what transpired during the execution of a map. The map audit logs can be enabled from the Map Settings window in the Map Designer, Command Server for Windows, or on any platform using execution commands on the command line.

The default name for an audit log that is not unique is the full name of the map with the .log extension. The default name for a unique audit log is Mer_mapname_processkey_mapcounter_hostname.log. The default audit log directory is the directory of the compiled map file.

The MapAudit log can contain three different sections: BurstAudit, SummaryAudit, and SettingsAudit. The sections produced depend on the settings for MapAudit.

BurstAudit

The information in the BurstAudit section of the MapAudit setting is configurable using the Data Audit Settings tab in the Organizer. See the Map Designer documentation for information about configuring these options and interpreting the information in the BurstAudit section.

SummaryAudit

When the SummaryAudit's Execution setting is Always, OnError, or OnWarningsOrError, an ExecutionSummary section is included in the log file. The ExecutionSummary section of the audit log file provides a summary of the return codes, sources, targets, and work areas for the map. This execution information also includes:

The command string to use if you were running the map from the command prompt.
The number of input and output objects.
Information about data and work files.
Execution time

See the Map Designer documentation for more information.

An ExecutionLog per burst

When the BurstAudit Execution setting is Always, OnBurstError, or OnBurstWarningOrError, the log file will contain a section for each burst within the map. If all inputs have a CardMode of Integral, there will be a single Burst section. The following excerpt is from the tryaudit.log file, created from running the tryaudit.mmc compiled map, which is included in the install_dir\examples\general\audit folder and presents the Burst section:


<Burst count="1">

<DataLog>

<input card="1">
   <object index="1" level="1"   size="10113" status="E00">
            DTX_MapAudit General Element
   </object>
   <object index="1" level="0" size="10113" status="V01">
            Audit_Log
   </object>
</input>

</DataLog>

<ExecutionLog   burstreturn="28" ElapsedSec="3.9280">

<inputstatus card="1" bytes="10113" adapterreturn="0" contentreturn="28"/>
<inputstatus card="2" bytes="1067"  adapterreturn="0" contentreturn="0"/>
<outputstatus card="1" bytes="610"  adapterreturn="0" contentreturn="0"/>
<outputstatus card="2" bytes="1055" adapterreturn="0" contentreturn="0"/>
<outputstatus card="3" bytes="10938" adapterreturn="0" contentreturn="0"/>
<outputstatus card="4" bytes="0" adapterreturn="0" 	contentreturn="0"/>

</ExecutionLog>

</Burst>

The ExecutionLog section identifies the return code and elapsed time for the burst, as well as the status of each input or output, including both an adapter return code, if applicable, and a content return code.

ExecutionSummary per map

The ExecutionSummary section provides information at the map level. The following excerpt presents the ExecutionSummary section:


<ExecutionSummary MapStatus="Valid" mapreturn="0" ElapsedSec="3.9610"
        BurstRestartCount="0">
   <Message>Input type contains errors</Message>

<CommandLine>'C:\install_dir\examples\general\audit\tryaudit.mmc'</CommandLine>
   <ObjectsFound>111</ObjectsFound>
   <ObjectsBuilt>10</ObjectsBuilt>

<SourceReport card="1" adapter="File" bytes="10113" adapterreturn="0">   
   <Message>Data read successfully</Message> 
   <Settings>C:\install_dir\examples\general\audit\goodaud.log</Settings>
   <TimeStamp>07:03:10 December 11, 2003</TimeStamp>
</SourceReport>

<SourceReport card="2" adapter="File" bytes="1067" adapterreturn="0">
   <Message>Data read successfully</Message>
   <Settings>C:\install_dir\examples\general\audit\maperrcd.dat</Settings>
   <TimeStamp>06:11:46 May 29, 2003</TimeStamp>
</SourceReport>

<TargetReport card="1" adapter="File" bytes="610" adapterreturn="0">
   <Message>Data written successfully</Message>
   <Settings>C:\install_dir\examples\general\audit\result.txt</Settings>
   <TimeStamp>09:27:11 January 23, 2004</TimeStamp>
</TargetReport>
.
.
.
<WorkArea type="File">
<inputarea  card="1"   Path="C:\install_dir\examples\general\audit\tryaudit.I01"
        TimeStamp="09:27:11 January 23, 2004" bytes="67522"/>
<inputarea  card="2"   Path="C:\install_dir\examples\general\audit\tryaudit.I02" 
        TimeStamp="09:27:11 January 23, 2004" bytes="67522"/>
<outputarea card="1"   Path="C:\install_dir\examples\general\audit\tryaudit.O01"
        TimeStamp="09:27:11 January 23, 2004" bytes="65536"/>
<outputarea card="2"   Path="C:\install_dir\examples\general\audit\tryaudit.O02" 
        TimeStamp="09:27:11 January 23, 2004" bytes="65536"/>
<outputarea card="3"   Path="C:\install_dir\examples\general\audit\tryaudit.O03" 
        TimeStamp="09:27:11 January 23, 2004" bytes="65536"/>
<outputarea card="4"   Path="C:\install_dir\examples\general\audit\tryaudit.O04" 
        TimeStamp="09:27:11 January 23, 2004" bytes="65536"/>
</WorkArea>

</ExecutionSummary>

As shown above, the execution log can provide some high-level debugging information, such as:

Map return code and message. The map return code and message indicate how the mapping operation completed and whether there were any problems. For example, a map return code of 0 and message of Map completed successfully indicate that no execution errors were encountered. This information helps in analyzing the source information in the log.
SourceReport and TargetReport. For each source or target, the ExecutionSummary includes information indicating the adapter, the size of the data for the source or target, the adapter return code and message, and so on. For example, if using a database adapter, a return code of -17 and a message of Failed to parse SQL statement for an input would indicate that some error occurred when the adapter attempted to execute the appropriate SQL statement to fetch the data from the database.
WorkArea. For each input or output for which a WorkArea is created, the ExecutionSummary includes information, such as the location and size.

The ExecutionSummary is a good place to start when diagnosing map execution problems because you can quickly determine the sources or targets in error. Using the information in the ExecutionSummary, you can produce more detailed troubleshooting information for only those sources or targets that experienced problems.

MapSettings section

The MapSettings section contains a list of all map settings, including the settings for MapAudit, MapTrace, WorkSpace, Century (SlidingCentury), Validation (CustomValidation), Retry (MapRetry), and Warnings. The following excerpt presents the MapSettings section:


<MapSettings>

<MapAudit switch="ON">
   <Log executionsummary="Always" databurst="Always" 
           databurst_sizevalidation="WrongSize" executionburst="Always" 
           mapsettings="Always" datasettings="OnError"/>
   <Location type="File" action="Create">
            <Directory type="Map">C:\install_dir\examples\general\audit</Directory>
            <FileName type="Default" prefix="MapName">tryaudit.log</FileName>
   </Location>
</MapAudit>

<MapTrace switch="OFF"></MapTrace>

<WorkSpace>
   <Location type="File" action="Delete">
            <Directory type="Map">C:\install_dir\examples\general\audit</Directory>
            <FileName type="Default" prefix="MapName"></FileName>
   </Location>
   <Paging>
            <PageSize>64</PageSize>
            <PageCount>8</PageCount>
   </Paging>
</WorkSpace>

<SlidingCentury switch="OFF"></SlidingCentury>

<CustomValidation switch="ON">
         <OnValidationError>Continue</OnValidationError>
         <RestrictionError>Validate</RestrictionError>
         <SizeError>Validate</SizeError>
         <PresentationError>Validate</PresentationError>
</CustomValidation>

<Retry switch="OFF"></Retry>

<BurstRestart switch="OFF"></BurstRestart>

<Warnings type="Every" action="Warn"></Warnings>

</MapSettings>

This information can be useful during debugging to determine why execution occurred in a certain way.

DataSettings section

The DataSettings section contains a list of all InputData and OutputData settings depending on the adapter used, including the FetchAs (CardMode), WorkArea , Backup, Command (SourceAdapterCommand or TargetAdapterCommand), OnSuccess, OnFailure, Retry (AdapterRetry), Scope (AdapterScope), and so on. The following excerpt presents the DataSettings section:


<DataSettings>

<InputData card="1"   CardMode="Integral"   WorkArea="!Reuse">
   <Backup switch="ON"   when="Always"   action="Create">
      <Path>C:\install_dir\examples\general\audit\
						Mer_tryaudit_10441074864820_5.I1.bak
</Path>
   </Backup>
   <Source adapter="File" OnSuccess="Keep" OnFailure="Rollback" Scope="Map" 
             Warnings="Ignore">
      <Resource>C:\install_dir\examples\general\audit\goodaud.log</Resource>
      <Retry switch="OFF"></Retry>
   </Source>
</InputData>
.
.
.
<OutputData card="1">
   <Backup switch="OFF"></Backup>
   <Target adapter="File" OnSuccess="Create" OnFailure="Rollback" Scope="Map"
             Warnings="Ignore">
      <Resource>C:\install_dir\examples\general\audit\result.txt</Resource>
      <Retry switch="OFF"></Retry>
   </Target>
</OutputData>
.
.
.
</DataSettings>

This information can be useful during debugging to identify whether data should be copied to a backup file, whether the changes to a database target should be committed if the map fails, and so on.