Replication Guide and Reference

Capture program problem determination facilities

The Capture program has a trace table, a log file, and trace file generated when the trace invocation parameter is used to start the Capture program.
Note for AS/400: The Capture program on AS/400 does not support tracing facilities. To trace problems, view the job logs of the control and journal jobs. See Capture for AS/400 problem determination facilities for more information.

Capture program trace table

The trace table is located in source server databases where the Capture program maintains change tables for replication sources. The trace table, ASN.IBMSNAP_TRACE, contains basic information about the activities of the Capture program instance. For a description of the ASN.IBMSNAP_TRACE table, see Table structures.

You can query the ASN.IBMSNAP_TRACE table with normal SQL (such as SELECT) or query tools. For example:

SELECT * FROM ASN.IBMSNAP_TRACE

Capture program trace file

The Capture program can be started with the trace invocation parameter. This parameter specifies that problem determination records be recorded in standard output to the screen or to a file, which contains the Capture program internal logic flows. When starting the Capture program, on workstation systems, precede the output file name with a pipe symbol (>).

To start the Capture program with trace on a workstation system:

\CAPTURE>asnccp mysrcdb x x trace > cap.trc

Where:

mysrcdb: is the source server database for this Capture program instance.
x x: indicates that no parameters are provided for the type of start (WARM, WARMNS, COLD) and pruning (PRUNE or NOPRUNE) so the defaults are assumed.
trace: indicates that the Capture program traces all error and flow information.
cap.trc: is the file to which the output is directed.

The trace file is located in the same directory from which the Capture program is started.

Capture program log

The Capture program creates a log file, named by the source database that is specified when the Capture program is started; the file extension is *.CCP. If the Capture program is started with asnccp mysrcdb, the log file is named mysrcdb.ccp. The Capture Program log file is located in the same directory from which the Capture program is started.

Capture for OS/390 problem determination facilities

The Capture program for OS/390 provides you with the following tools to assist you if a severe error occurs:

Alert generation
Trace buffer
Trace output
Storage dump

This section provides information on these tools.

Alert generation

If a severe error occurs, the Capture program for OS/390 alerts NetView if NetView is active. The alert uses the NMVT format for a generic alert defined by the SNA generic alert architecture. If NetView is unavailable, diagnostic information is still available because the Capture for OS/390 program error messages are sent to the MVS console.

Trace buffer

The Capture for OS/390 program puts a small amount of critical diagnostic data in a wraparound trace buffer during processing. Each trace buffer entry describes current data capture status. If a severe error occurs, the Capture program prints the trace buffer before terminating. The printing of the trace buffer supplements the Capture program error message.

Trace output

When an error occurs, you can run Capture for OS/390 with the TRACE option. When you use this option, the Capture program writes trace information logic flow to SYSPRINT. This information can be used by IBM Service to diagnose operational problems.

Storage dump

When the Capture for OS/390 program terminates with a severe error, it saves critical diagnostic data in the CEEDUMP data set. This information is more detailed than the information in the Capture program trace buffer and can be used by IBM Service to diagnose operational problems.

Capture for VM and VSE problem determination facilities

The Capture program provides you with the following tools to assist you if a severe error occurs:

Trace buffer
Trace output
Storage dump

This section provides information on these tools.

Trace buffer

The Capture program puts a small amount of critical diagnostic data in a wraparound trace buffer during processing. Each trace buffer entry describes current data capture status. If a severe error occurs, the Capture program prints the trace buffer before terminating. The printing of the trace buffer supplements the Capture program error message.

Trace output

When an error occurs, you can run the Capture program with the TRACE option. When you use this option, the Capture program writes trace information logic flow to the VM console (for VM) or STDOUT (for VSE). This information can be used by IBM Service to diagnose operational problems.

Storage dump

When the Capture program terminates with a severe error, it saves critical diagnostic data in the CEEDUMP data set. This information is more detailed than the information in the Capture program trace buffer.

Capture for AS/400 problem determination facilities

Capture for AS/400 has unique problem determination facilities because of its dependency on journals and journal receivers as its primary source of input. The following section describes Capture program for AS/400 problem determination facilities and problem recovery methods.

Where to start looking for information

The first place to start looking for currently active jobs is the jobs running in the DPROPR/400 subsystem. Issue the work with submitted jobs command WRKSBSJOB QZSNDPR to receive a list of all the active jobs in that subsystem. If you fail to find the job, use the WRKSBMJOB command to locate and view the job log for the job. The name of the Capture program control job is QZSNCTL5. The name of the journal job is the same as the journal name (either QSQJRN (the default journal name for SQL collections) or a name that you specified for your journal).

As you go along, record the 6-digit job numbers. They might be needed in the following steps.

Journal job does not start

You might start the Capture program only to find out that only one job, the job QDPRCTL5, is running. If this persists longer than 5 minutes, you can check the following conditions:

If you are using WRKSBSJOB or WRKACTJOB command to display active jobs, enter option 7 on the command line for job QZSNCTL5. Message ASN2017 might be waiting for a reply.
Run the command WRKJOB QSQJRN (or the name of the journal job on your system). The journal job might have started, but ended right away for some reason (for example, because the lag limit was exceeded). If you find a recent journal job, display its job log to first confirm it is the right job and then to determine why it ended.
The QDPRCTL5 control job might not have found any replication sources that are eligible for replication. Two conditions make a replication source eligible for replication:
- The replication source must have at least one replication subscription defined.
- The Apply program must start a full refresh to copy the original contents of the source table to the target table, even if the source is empty. The full refresh brings the target table in synchronization with the source table. At the time the Apply job starts the full refresh, the pruning control table row for this replication pair has its SYNCHPOINT column set to hex zeroes.
When you first issue the STRDPRCAP command, there may be replication pairs that meet the first condition but not the second one. No journal job will be started at that time if none of the replication sources meet both conditions.
Every two minutes thereafter (or at the frequency you specify on the WAIT parameter of the STRDPRCAP command), the QZSNCTL5 job wakes up to determine if any replication source exists that meet both conditions listed above. If it finds one, it starts the journal job.
To see if a replication pair's pruning control table row has a SYNCHPOINT set to hex zeroes, issue the following statement on the source server:
```
   SELECT HEX(SYNCHPOINT) FROM ASN/IBMSNAP_PRUNCNTL
                     WHERE SOURCE_TABLE='xxx' AND SOURCE_OWNER='yyy'
                     AND SOURCE_VIEW_QUAL=z
```
where xxx is the library name, yyy is the table name, and z is the source view qualifier of the replication source in question. The contents of xxx and yyy are case-sensitive.

Collecting data for Capture program problem determination

Following is a list of items that are needed for Capture program problem determination, in order of importance:

The job log of the Capture control job QDPRCTL5.
The job log of the Capture journal job in question.
Keeping the journal receivers is very important because they contain important time sequence information. Save the journal receivers in a file or make sure the receivers are kept if a remote sign-on by IBM service is likely to occur. The journal receivers of the following tables are useful in problem determination:
The control tables
The register table, the register extension table, the pruning control table, the unit-of-work table, the critical section table, and the warm start table. The journal for these tables is ASN.QSQJRN.
The source table in question
These journal receivers are kept as long as the Capture program needs them. Make sure they are not deleted automatically by the system if problem determination is to take place.
The change data table of the replication source in question
Usually the journal is named QSQJRN and is in the same library as the source table. If it is not, find the library and the name of the journal by issuing a DSPFD xxx/yyy command (where xxx is the library, and yyy is the system name of the change data table in question). To find the system name of the change data table, issue the following statement:
```
   SELECT DBXFIL FROM QSYS/QADBXREF
                     WHERE DBXLFI = 'sqlname' AND DBXLIB = 'xxx'
```
where sqlname is the SQL name of the subject change data table. The contents of sqlname and xxx are case sensitive.
The formatted dump of the user index QDPR/QZSNINDEX5. Issue the following command before the Capture program ends:
```
   DMPOBJ QDPR/QZSNINDEX5 *USRIDX
```
If you have questions about the behavior of a certain replication sources, it is important to collect the contents of the corresponding rows in the register table and the register extension table. You can collect them by issuing the following statements:
```
   SELECT A.*, HEX(CD_OLD_SYNCHPOINT), HEX(CD_NEW_SYNCHPOINT)
                     FROM ASN/IBMSNAP_REGISTER A
                     WHERE SOURCE_OWNER='xxx' AND SOURCE_TABLE='yyy'
 
   SELECT * FROM ASN.IBMSNAP_REG_EXT
                     WHERE SOURCE_OWNER='xxx' AND SOURCE_TABLE='yyy'
```
where xxx is the library name and yyy is the table name of the replication source in question. The contents of xxx and yyy are case sensitive.

At times, you need to retrieve the contents of the global row in the register table with the following statement:

   SELECT A.*, HEX(SYNCHPOINT)
                     FROM ASN/IBMSNAP_REGISTER A
                     WHERE GLOBAL_RECORD = 'Y'

The Capture program trace table has entries that record the significant job events. To find entries for the Capture program control job or the Capture program journal job, enter the following statement (assuming the job number of the job you want to investigate is 011932):
```
   SELECT * FROM ASN/IBMSNAP_TRACE
                     WHERE SUBSTR(JOB_NAME, 21, 6) = '011932'
                     ORDER BY TRACE_TIME
```
The DESCRIPTION column provides important information about the job.
The following statement can be used to gather trace table entries after a certain time (at 7 a.m., March 31, 1999, for example):
```
   SELECT * FROM ASN/IBMSNAP_TRACE
                     WHERE TRACE_TIME > '1999-03-31-07.00.00.000000'
                     ORDER BY TRACE_TIME
```
The following statement retrieves all of the ASN0303 (data capturing is interrupted ...) trace entries after 7 a.m., March 31, 1999:
```
   SELECT * FROM ASN/IBMSNAP_TRACE
                     WHERE TRACE_TIME > '1999-03-31-07.00.00.000000' AND
                           SUBSTR(DESCRIPTION, 1, 7) = 'ASN0303'
                     ORDER BY TRACE_TIME
```
The warm start table has one entry for every journal that is used by one or more replication sources. You can retrieve the row for the journal job by entering the following statement:
```
   SELECT * FROM ASN/IBMSNAP_WARM_START
                     WHERE JRN_LIB='xxx' AND JRN_NAME='yyy'
```
where xxx is the library name and yyy is the table name of the journal. The contents of xxx and yyy are case sensitive.
In some cases, it is necessary to collect data from the target server to determine how and why the Apply program fails to replicate to the target table:
- The audit trail table.
- The job log of the Apply jobs.
- The subscription set table and its journal receivers (since it may be necessary to find out how some columns changed along the time line).
The formatted dump of the user spaces for the journal jobs. They are in library QDPR, and they have the name of QDPRxxxxxx, where xxxxxx is the job number of the journal job. Issue the following command before Capture ends:
```
   DMPOBJ QDPR/QDPRxxxxxx *USRSPC
```

[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]

[ DB2 List of Books | Search the DB2 Books ]