Using GentranEx.dll to Debug Maps

Transcription

1 Using GentranEx.dll to Debug Maps Last revised: August 15, 2017 Licensed Materials - Property of IBM IBM Sterling Gentran:Server for Microsoft Windows Copyright IBM Corp. 1990, All Rights Reserved. US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. Page 1 of 7

2 TABLE OF CONTENTS PURPOSE... 3 BACKGROUND... 3 IMPLEMENTATION... 4 CREATING THE LOG FILE... 4 WRITING MESSAGES TO A LOG FILE... 5 DELETING MAP OBJECTS... 6 GENERATING AND VIEWING THE LOG FILE... 7 Page 2 of 7

3 Purpose In the process of translating data, a map may not always produce the desired output. When trying to determine the cause of the undesired output, it is necessary to determine exactly how the translator is processing the data through the map. At times the translator report alone is not enough to debug a map, the GentranEx.dll can be used also. This white paper is being written to document the steps required to setup a map to generate a log file that can be used to help debug a map. For more information regarding all the functionality and the command syntax for the GentranEx.dll, see the Using GentranEx.dll chapter located with the Gentran:Server Application Integration User s Guide. Background Undesired output can be generated during translation due to the following: Unexpected data from the partner or application file. Improper usage of mapping constructs (for example, groups, records, fields, and links). Logic errors in an extended rule. As mentioned in earlier, when trying to determine the cause of the undesired output, it is necessary to determine exactly how the translator is processing the data through the map and the translator report alone, at times, is not enough. There needs to be some way for the translator to indicate exactly where it is during the translation process. In the past, this could only be accomplished with a messagebox extended rule. When working with the messagebox extended rule command, a pop up message box is displayed during. By placing messagebox rules in key places in the map, users can see exactly what point in the map the translator is processing. There is a drawback to this solution; however, since the messagebox rule requires some interaction from the user (for example, clicking an OK button) before the translator proceeds with the translation. It becomes cumbersome for the user to click through several message boxes, especially when dealing with large amounts of repeating data. An alternative solution to working with one or multiple messagebox extended rules is to log status messages to a trace file. This can be accomplished with a system defined user exit that accesses the GentranEx.dll. The GentranEx.dll is an in-process automation server that extends the flexibility of the Gentran:Server Application Integration and translator programs by using COM technology and the IDispatch interface. The GentranEx.dll is installed and located within the GENSRVNT\Bin directory. Page 3 of 7

4 Calling GentranEx.dll from within a map is referred to as a type of user exit. In Gentran:Server for Windows, GentranEx.dll user exits are extended rules that invoke custom functionality that was created as an ActiveX Automation Server. User exits can create objects, access properties, or start methods. The type of GentranEx.dll user exit that is covered in this document is one that will write messages to a text file that can be used to debug a map. There are several advantages to using the GentranEx.dll s TraceLog object rather than using one or multiple messagebox extended rules: No interaction is required from a user during translation. Greater flexibility is allowed in the messages that can be reported. It can be left in the map indefinitely, unlike a messagebox extended rule, which needs to be removed once debugging is finished. Implementation Consider an inbound 850 that contains several line items. The 850 passes the compliance check and therefore resides in the In Documents tray with a status of OK. However, when the 850 is exported, several of the line items appear to be missing. A rudimentary review of his map reveals no apparent issues with the way the map is constructed. All the links appear to be valid. There is an extended rule in the map that performs some relatively complex calculations and rearranging of the data before it is mapped to the output side. Some logic error in this rule may be the culprit, but to check this rule would take time, and in the end it may not be the cause of the problem. Using the GentranEx.dll to generate a log file can assist in debugging the cause of such a problem and reduce the troubleshooting time needed. Creating the Log File To create the log file, an object must be created within the map that creates, and assigns parameters for the log file. This is setup within an extended rule. To setup a rule that creates a log file, follow the instructions below: 1. Open the Pet_850.map provided in the \\GENSRVNT\Tutorial directory. 2. Right-click on the INPUT Level, and select Properties. 3. Select the Loop Extended Rules tab. 4. Select the On Begin radio button. 5. Type the following rule into the Please enter the extended rule below: field: object objdebug; objdebug = createobject("gentranex.tracelog"); objdebug.openlog("c:\gensrvnt\debug file.txt ","User1",1); 6. Click on the Compile button to verify that the rule compiles correctly. 7. Click on the Apply button then click on the OK button to close the INPUT File Properties dialog screen. 8. Save the map, to save the changes made thus far. Page 4 of 7

5 This rule creates an object instance named objdebug that uses the TraceLog object of GentranEx.dll. The object then uses the OpenLog method to open a file to which the messages will be written. The OpenLog method has 3 parameters: The first parameter is a file name and path to the file. o A file name must be specified, along with a valid path to the file. The second parameter is the Owner. o The Owner can be any value up to 20 characters. This value appears in the log file next to each message and is useful for identifying messages for specific maps or users. The last parameter is the WriteMode. o The WriteMode controls if the file will be appended to or over written during subsequent calls to it. o WriteMode of 1 will append all messages to the named file o WriteMode of 2 will overwrite the file if it already exists. Writing Messages to a Log File Now that the log file can be created during translation, next messages need to be written to it. Writing to the file is accomplished by using the WriteLog method. This method is inserted into the map where the status message is desired. To setup a rule that writes to the log file generated in the steps above, follow the instructions below: 1. Open the Pet_850.map that was being used earlier, and locate the PO1 group. 2. Right-click on the PO1 group, and select Properties. 3. Click on the Loop Extended Rules tab. 4. Select the On Begin radio button. 5. Type the following rule into the Please enter the extended rule below: field: objdebug.writelog("po1 Group On Begin","Start of Line Item Detail"); 6. Select the On End radio button. 7. Type the following rule into the Please enter the extended rule below: field: objdebug.writelog("po1 Group On End","End of Line Item Detail"); 8. Click on the Compile button to verify that the rule compiles correctly. 9. Click on the Apply button then click on the OK button to close the INPUT File Properties dialog screen. 10. Save the map, to save the changes made thus far. The WriteLog method has 2 parameters: The first parameter is the message source. Page 5 of 7

6 o This can be any string value up to 20 characters. The string value may be a literal constant (as in the example), a string variable, or a reference to a string type field in the map. The second parameter is the message itself o The message can be up to 256 characters in length. This value may be a literal constant, sting variable, or a reference to a string type field in the map. These two rules, both on the PO1 group, will write a message to the log indicating when the start and end of a PO1 loop is processed. If the translator stops processing a line item for some particular reason, it is easy to spot by looking at the messages generated by this rule. If the number of messages in the log does not correspond to the number of items known to be in the 850, there is a problem. Deleting Map Objects When objects are created within a map, they should always be closed and then deleted once processing of the object is completed. This frees the memory area being used by the object. To setup a rule that deletes the object that creates and writes to the log file, from the steps above, follow the instructions below: 1. Open the Pet_850.map that was being used earlier. 2. Right click on the INPUT Level, and select Properties on the pop-up menu. 3. Select the Loop Extended Rules tab. 4. Select the On End radio button. 5. Type the following rules into the Please enter the extended rule below: field: objdebug.closelog(); deleteobject(objdebug); 6. Click on the Compile button to verify that the rule compiles correctly. 7. Click on the Apply button then click on the OK button to close the INPUT File Properties dialog screen. 8. Save the map, to save the changes made thus far. The CloseLog method is used to close the log file. The deleteobject command is used to delete the object after the CloseLog method has closed the file. Page 6 of 7

7 Generating and Viewing the Log File Now that the rules required to generate and write to the log file are in place within the map, the map needs to saved, compiled and registered into Gentran:Server. Once the updated map has been registered, an export session needs to be run. During the export session, the sample log file will be generated in the file path specified in earlier steps, and should appear similar to below: DATE TIME LOG OWNER LOG SOURCE MESSAGE ===== ==== =========== =========== ========= This log file can become much more explicit if more WriteLog rules are inserted in key places within the map. Well-placed messages can be of great aid in debugging a map that is not producing the correct output. For more information regarding all the functionality and the command syntax for the GentranEx.dll, see the Using GentranEx.dll chapter located with the Gentran:Server Application Integration User s Guide. Page 7 of 7