HOWTO: Collect internal trace records of a DataGate/400 Job

The information in this article applies to:

• DataGate/400, All versions
• AS/400

SUMMARY:

Sometimes it is necessary to obtain a 'trace' for a DataGate/400 run when trying to diagnose a problem. These are the steps needed to obtain such a trace. A debuggable version of DataGate/400 is shipped with DataGate/400 an resides on the CD. 

MORE INFORMATION:

To trace a DataGate run these following steps:

Note: Tracing does not work with the non-debuggable release version of the DataGate/400 program.

Install the debug version of DataGate/400 by performing the following steps:

1. Download and Unzip the DataGate/400 Debug Program.  Within this zip file is an AS/400 SAVF: ftp://ftp.asna.com/datagate/dg8debug.zip
2. Sign onto the AS/400 using an account with *SECOFR authority;



3. On the AS/400, create a library (temporary) called ASNADLVR: (NOTE: QTEMP must not be used).

CRTLIB ASNADLVR



4. Add this library to the library list:

ADDLIBLE ASNADLVR



5. Create a Save file.

CRTSAVF FILE(ASNADLVR/DG8SF)



6. Start FTP using the following FTP command

FTP as400tcpipaddress

NOTE: Where as400tcpipaddress is either a TCP/IP address such as 198.176.129.35, or a machine name that is registered either in a DNS or a HOSTS file. When prompted for a user name and password, enter the appropriate information that will give you privileges to upload data to the AS/400.

7. Upload the Save file containing the Debug programs to the 400 from the CD  using the following put commands

a) binary

b) put dg8debug  ASNADLVR/DG8SF   

NOTE: Where dg8debug is the file you downloaded and extracted from ASNA FTP site.

c) quit

8. End the DataGate service by entering the ENDDG8SVR command.  Verify that there are no active connections to DataGate. 



9. Rename the object DataGate, type *PGM in the DataGate installation library.


NOTE: The default DataGate installation library is called DG8_40. RNMOBJ OBJ(xxx/DataGate)  OBJTYPE(*PGM) NEWOBJ(DataGateBK)


10. Restore the DataGate debug program using the Restore Object command:

RSTOBJ OBJ(DATAGATE) SAVLIB(ADBTASS) DEV(*SAVF) SAVF(ASNADLVR/DG8SF) RSTLIB(XXX)

For DataGate/400 5.0, restore the DG8RISC SAVF within the DG8SF, then perform the following command:

RSTOBJ OBJ(DATAGATE) SAVLIB(ADBTASS) DEV(*SAVF) SAVF(ASNADLVR/DG8RISC) RSTLIB(XXX)

NOTE: XXX denotes the DataGate installation library

11. Create a data area called DGTRACE with the following command in the DataGate Installation Library. 

CRTDTAARA DTAARA(XXX/DGTRACE) TYPE(*char) LEN(1) VALUE('3')

NOTE: when XXX denotes the DataGate installation library

• The amount of tracing output can be varied with the value in the DGTRACE data area as follows:

'0' - no output ("tracing off")
'1' - almost no output ("API-level" trace, but not on DataGate)
'2' - produces a function-level trace (lots of stuff)
'3' - produces a function- and line-level trace (lots & lots of stuff) 

12. Start the DataGate service (STRDG8SVR) and run the application that makes a connection to the AS/400 using DataGate/400.

     A source-physical file named DGTRACE will appear in the installation library if it doesn't already exist.  Members will be added to the DGTRACE file whose names correspond to the job numbers for the trace-enabled DataGate jobs. Member names will have a prefix of "DG" followed by the job number for the DataGate job. (e.g., DG58435)




13. Get the trace:

Using ADBFM's CopyData, you can copy the file and along with the corresponding trace member to your local ADB database. The file can then be archived and attached to an email and sent to ASNA. You can also save the physical file on the AS/400 into a Save File and FTP the Save File to your pc. The Save File can then be attached to an email and sent to ASNA.

Notes for using tracing while replicating a bug:

• Tracing does NOT duplicate the information available in the job log. System errors and such will not occur in the trace log.  It may be necessary to obtain a job log output in addition to a trace log in many, if not most cases.
• The end user would need "object create" authority (or equivalent) over the installation library  as each new connection will cause a new member to be created in DGTRACE.
• Run-time output can be controlled.  The amount of tracing output can be varied with the value in the DGTRACE data area as follows:

'0' - no output ("tracing off")
'1' - almost no output ("API-level" trace, but not on DataGate)
'2' - produces a function-level trace (lots of stuff)
'3' - produces a function- and line-level trace (lots & lots of stuff)

• When used to trace a particular problem, it will be critical that the correct trace member is captured and transmitted to ASNA. Job numbers for running jobs are visible via WRKACTJOB. The problem of sorting out the members may be avoided altogether by deleting all members in the DGTRACE file prior to turning on tracing, and then turning off tracing immediately after the replication, so that only the replication produces a trace.
• Tracing may cause an overall performance drop. The debuggable DataGate/400 program object will be unoptimized and thus slower too.  Again, carefully timing the setting of the trace level can help.  The DataGate/400 program only examines the value of the DGTRACE data area once, at program startup. 



14. Terminate Tracing. In order to terminate tracing, you will need to stop the Datagate Service by issuing the ENDDG8SVR command. Verify that all connections have ended and restore the original Datagate program.

DLTPGM PGM(xxx/Datagate) - Delete Datagate trace program

RNMOBJ OBJ(xxx/DatagateBK)  OBJTYPE(*PGM) NEWOBJ(Datagate) - Restore original Datagate program.

15. Start the Datagate Service: DG8_40/STRDG8SVR

ASNA KB Articles:

• HOWTO: Collect internal trace records for Acceler8DB

Keywords: debug, Jobs, log, trace