LOGSCAN statement
- The types of output BMC AMI Log Master generates (reports or output files)
- Whether BMC AMI Log Master creates a log mark
- Other important characteristics
LOGSCAN statement syntax diagram
The following figure shows the basic, high-level syntax of the LOGSCAN statement.
LOGSCAN statement option descriptions
To define a valid log scan, you must specify at least one form of output or one form of action on the Repository. You can specify multiple LOGSCAN statements, but BMC AMI Log Master scans the Db2 log only once for each work ID, no matter how many log scans, reports, or other forms of output you define.
Option | Description | |||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
REPORT | Directs BMC AMI Log Master to create reports using the information obtained in the log scan. For more information about the available reports, see LOGSCAN-report-definition. | |||||||||||||||||||||||||||||||||||||||||||
LLOG | Directs BMC AMI Log Master to create a logical log file by using the information obtained in the log scan. A logical log is a readable version of the Db2 log that contains before and after images of database changes. For more information about generating a logical log, see LOGSCAN-logical-log-output-definition. | |||||||||||||||||||||||||||||||||||||||||||
SQL | Directs BMC AMI Log Master to create an SQL output file by using the information obtained in the log scan. An SQL output file contains ANSI-standard SQL statements that either duplicate or reverse changes recorded in the Db2 log. For more information about generating an SQL output file, see LOGSCAN-SQL-file-definition. | |||||||||||||||||||||||||||||||||||||||||||
LOAD | Directs BMC AMI Log Master to create a load file that contains the log records specified in the log scan, formatted for a Db2 Load utility. Although BMC AMI Log Master uses the Db2 Load utility format to create the load file, the content is not the same as a load file created by a Db2 Unload utility. (The BMC AMI Log Master load file reflects activity over a period of time; a Db2 Unload utility creates a load file that reflects a given point in time.) A load file is usually accompanied by a load control file that contains parameters for a Db2 Load utility. For more information about generating a load file, see LOGSCAN-load-file-definition. | |||||||||||||||||||||||||||||||||||||||||||
DDL | Directs BMC AMI Log Master to create a data definition language (DDL) output file based on the information obtained in the log scan. A DDL output file contains ANSI-standard DDL statements that duplicate or reverse structural database changes recorded in the Db2 log. You can generate only MIGRATE or UNDO DDL; BMC AMI Log Master does not generate REDO DDL. For more information about generating a DDL output file, see LOGSCAN-DDL-file-definition. | |||||||||||||||||||||||||||||||||||||||||||
COMMAND | Directs BMC AMI Log Master to create a command output file based on the information obtained in the log scan. A command output file contains BIND, REBIND, or FREE commands that duplicate or reverse structural database changes recorded in the Db2 log. You can generate only MIGRATE or UNDO commands; BMC AMI Log Master does not generate REDO commands. For more information, see LOGSCAN-command-file-definition. | |||||||||||||||||||||||||||||||||||||||||||
REPOS UPDATE | Directs BMC AMI Log Master to update the old objects Repository table (ALPOLDO) or the SYSCOPY Repository table (ALPSYSCP), or both. Each set of rows in the old objects table defines a Db2 object at a given point in time. When BMC AMI Log Master is running in overtime mode and it encounters log records related to an object that is not currently defined in the Db2 catalog (for example, after the object has been dropped), it can use the old objects information and the SYSCOPY records in the Repository to process those log records. BMC AMI Log Master can use compression dictionaries stored in the Repository when it runs in current or overtime mode unless the value of the REPOS keyword on the OPTION statement is NO. You can update the old objects information in the Repository from the following sources:
Values for REPOS UPDATE are as described in the following table. If you specify REPOS UPDATE without specifying one of these values, BMC AMI Log Master obtains old objects information from the Db2 log and does not include compression dictionaries or SYSCOPY information.
REPOS UPDATE include options
The following tables show the action that BMC AMI Log Master takes depending on the value of REPOS UPDATE.
Product action determined by REPOS UPDATE value
Product action determined by REPOS UPDATE INCLUDE SYSCOPY value
Note the following points regarding the REPOS UPDATE keyword:
For more information about the old objects table, the Repository, and the associated batch syntax, see Processing-objects-over-time . | |||||||||||||||||||||||||||||||||||||||||||
REPOS DELETE | Directs BMC AMI Log Master to delete rows from supported tables within the Repository. | |||||||||||||||||||||||||||||||||||||||||||
MARKSCAN | Associates a symbolic name (called a log mark name) with the end point of your Range definition (the TO value). Use log marks to refer to a point in the log by using a name instead of an RBA/LRSN or a date and time value. BMC AMI Log Master keeps information about log marks in the Repository (in a table named ALPMARK). By using the MARKSCAN keyword, you can associate a log mark name with a point in the Db2 log other than the current RBA/LRSN value when your job starts executing. Values for MARKSCAN are as follows:
| |||||||||||||||||||||||||||||||||||||||||||
Sort file size parameters | Specifies the estimated size of the data that BMC AMI Log Master must sort during a given log scan. You can also specify the size of the data to be sorted during an entire job on the SORTOPTS statement. These parameters specify either the estimated size of the data to be sorted or a technique that BMC AMI Log Master uses to calculate the estimate. For more information, see Sort file size parameters. | |||||||||||||||||||||||||||||||||||||||||||
DB2CATALOG | Determines whether BMC AMI Log Master includes Db2 catalog information from log records in the generated output.
The DB2CAT installation option affects the action of the DB2CATALOG keyword. The person installing BMC AMI Log Master can set DB2CAT to NEVER, which prevents BMC AMI Log Master from including any Db2 catalog information in the generated output. If your job operates on objects stored in the Db2 catalog, BMC AMI Log Master must perform completion processing on Db2 catalog log records. Because of the large number of log records related to the catalog, this processing can cause your job to run longer and require more resources than a job that does not read the Db2 catalog. If you frequently operate on objects stored in the catalog, you can improve performance by creating more frequent image copies of the catalog or by defining tables in the Db2 catalog with Data Capture Changes (DCC). | |||||||||||||||||||||||||||||||||||||||||||
DB2DIRECTORY | Determines whether BMC AMI Log Masterincludes Db2 directory information from log records in the generated output. Db2 directory information is limited to Quiet Point and Summary All Activity report outputs.
The DB2DIR installation option affects the action of the DB2DIRECTORY keyword. The person installing BMC AMI Log Master can set DB2DIR to NEVER, which prevents BMC AMI Log Master from including any Db2 directory information in the generated output. | |||||||||||||||||||||||||||||||||||||||||||
Scan range definition | Specifies the part of the Db2 log that BMC AMI Log Master scans for information. The scan range definition can also specify a start point where BMC AMI Log Master begins generating REDO information (often called a recovery point). The scan range definition is not required when you specify the REPOS DELETE keyword. For more information about specifying the range of the log scan, see LOGSCAN-scan-range-definition. | |||||||||||||||||||||||||||||||||||||||||||
FILTER | Specifies an existing filter that BMC AMI Log Masteruses to select log records from within the log scan range. Normally, you use the online interface to create filters. BMC AMI Log Master stores them in the Repository. If you use the task-oriented dialogs of the online interface, the filter name defaults to be the same as the work ID name. userID.filterName The filterName can be up to 18 characters long. The first character cannot be numeric, and any additional characters must be alphanumeric characters or national characters ($, #, or @). Use the FILTER keyword to refer to a stored filter that already exists. To define new selection criteria within the current job, use the WHERE clause of the LOGSCAN statement. You can qualify filterName with a user ID. If you do not specify a user ID, the default ID is the TSO prefix or TSO user ID that submitted the job. For more information about creating filters, see the section about defining the log scan step in the Defining-a-log-scan-step. | |||||||||||||||||||||||||||||||||||||||||||
WHERE Search condition definition | Defines the search conditions that BMC AMI Log Master uses to select log records from within the log scan range. The conditions specified in a WHERE clause relate to database structures or characteristics, as opposed to a scan range that relates to part of the log. Use the WHERE clause to define new selection criteria within the current job. To use a stored filter that already exists, use the FILTER keyword of the LOGSCAN statement. For more information about specifying a search condition, see LOGSCAN-search-condition-definition. | |||||||||||||||||||||||||||||||||||||||||||
ONGOING HANDLE handleID | Defines a unique handle ID that BMC AMI Log Master uses to identify this log scan as an ongoing process (a log scan that is run repeatedly, with each start point dependent on the end of the previous log scan). For more information, see Ongoing log scans. BMC AMI Log Master associates the different runs of an ongoing log scan by using the handle ID (along with the combination of the work ID and the user ID specified in a job’s WORKID statement). Use the online interface to create a work ID that contains an ongoing log scan. When you do, the online interface ensures that the Repository contains all necessary information and generates a unique combination of handle ID, work ID and user ID. To rerun a job that contains an ongoing log scan, use either the USE or RERUN keywords. Both keywords can use the run sequence number of a previous run of an ongoing job. BMC AMI Log Master displays the run sequence number for a job in message BMC097494.
Be aware of the following points regarding USE RUNSEQ or RERUN RUNSEQ:
|
Ongoing log scans
BMC AMI Log Master
provides the ability to define an ongoing log scan (one that is run repeatedly, with each start point dependent on the end of the previous log scan).
With this feature, you can scan the logs multiple times, changing the range of the log scan for each run, but not changing the SYSIN syntax of your job step. In many environments, ongoing log scans extract data for migration to other databases or platforms.
For an ongoing log scan, BMC AMI Log Master keeps track of each run. BMC AMI Log Master also keeps track of any transactions (units of recovery) that start within the current log scan, but are still open at the end point. At the start of each run, BMC AMI Log Master automatically changes the start point so that it begins at the lowest RBA/LRSN address in the set of recorded open transactions from the previous run of the log scan. BMC AMI Log Master issues message BMC097778 to display any transactions (URIDs) that were open at the end of the previous run.
For ongoing log scans, BMC AMI Log Master ensures that
- Any transactions that are open at the end of the current log scan will be included in a subsequent run of the log scan
- Any transactions that were completed within a previous log scan are not processed twice, even though BMC AMI Log Master might scan part of the same log range again
When you work with ongoing log scans, remember the following points:
- Use the online interface to create a work ID that contains an ongoing log scan. The online interface ensures that an ongoing job’s combination of handle ID, work ID name, and user ID is unique. If you define your own handle ID outside of the online interface, ensure that you define a unique combination of these three items. (BMC AMI Log Master associates the different runs of an ongoing log scan by using the handle ID, along with the combination of the work ID name and the user ID specified in a job’s WORKID statement).
- When possible, schedule ongoing log scans to run before running any utilities that can change the location of rows within a table space. (For example, a Db2 Reorg utility can change the location of a row, so that the row associated with a record ID (RID) value is different than the row associated with that RID value in previous log records). Events that change the location of rows limit the BMC AMI Log Master options for row completion processing. When the log scan does not include such an event, BMC AMI Log Master is more likely to select an option for row completion processing that results in better product performance.
- When possible, schedule ongoing log scans to run before executing any data definition language (DDL) statements that change the structure of a table (for example, an ALTER COLUMN SET DATA TYPE statement) and any subsequent database reorganizations. This action enables BMC AMI Log Master to avoid scanning log records for multiple versions of a Db2 table. When a log scan includes multiple versions of a table, BMC AMI Log Master performs additional processing to keep track of the versions and convert log records from previous versions to the current version of the table. Avoiding this additional processing can improve product performance.
- You can reset the start point of an ongoing log scan (for more information, see ONGOING HANDLE handleID ).
- BMC AMI Log Master does not support ongoing log scans with an input source of logical log files.
- BMC AMI Log Master performs row completion processing differently for a work ID that contains an ongoing log scan. When an ongoing log scan requires access to the current table space, but updates to the table space have not yet been written to DASD storage, BMC AMI Log Master can defer completing some log records during the current log scan so that they can be completed in a subsequent log scan.
- BMC AMI Log Master responds to return codes greater than 8 (error) differently for a work ID that contains an ongoing log scan. For more information, see Log-Master-termination-processing.
- Consider using ongoing log scans to periodically update the BMC AMI Log Master Repository with compression dictionaries (to avoid mounting image copies), or with structure definitions for old objects (to enable processing in overtime mode).
This section contains the following topics: