Valid for
Logger
Description
Use FILE
to specify file sets and record types to the current log. You can also use the EXCLUDEFILE
parameter to subsequently exclude files that have been included by FILE
.
You can include files in the current log by:
Specifying file sets
Specifying filtering values
Optionally, you can specify a variety of attributes to enhance file processing.
Syntax
FILE file_set [, attribute...][, filter];
file_set
The name of the file, or file set to be processed.
attribute
For details about the attributes you can specify as FILE
options see "Using parameters as FILE options".
filter
Can be one or more of the following:
PROCESS
process_file_set
PROGRAM
program_file_set
USER
user_id
If more than one filter is specified, all of the specified criteria must be met. See "Including with filters" for details about using filters.
Specifying file sets
FILE
can explicitly name a file set, as in $DATA3.DAT.TRANS
, or specify wildcard arguments as in $DATA4.*.*
.
When multiple FILE
statements are included in a parameter file, only the first match is logged. The following is an example:
FILE $DATA4.GGSDAT.FIN* FILE $DATA4.GGSDAT.*
In this case, the file set $DATA4.GGSDAT.FIN*
is logged only once, to the corresponding log, even if a subsequent FILE
(such as $DATA4.GGSDAT.*
) implicitly includes it in a wildcard argument.
The primary partition of the file must be satisfied by a FILE
entry for extraction to take place. Also, excluding secondary partitions has no effect.
If you wish to retrieve a file set from a remote node, Logger must be configured and running on that node locally.
Using parameters as FILE options
You can use other parameters as options with FILE
; this lets you apply a parameter to a single file or file set, rather than all the files in your Logger group. Parameters that can be set as an option in FILE
include:
COMPRESSUPDATES | NOCOMPRESSUPDATES
(default)
GETAUDITED | IGNOREAUDITED
(default)
GETBEFOREUPDATES | IGNOREBEFOREUPDATES
(default)
GETBULKIO | IGNOREBULKIO
(default)
GETUNSTRUCTURED | IGNOREUNSTRUCTURED
(default)
RENAMEDELAY
delay_seconds
SUSPENDED | ACTIVE
(default)
Including with filters
A file can also be included based on filters. If you specify more than one filter, all of the filter criteria must be met to include the file for logging. For example, the following only includes the specified file set when both the process and user ID filter criteria are met.
FILE $DATA3.APPL.TL*, PROCESS $APP*, USER SUPER.*
If a file is included by FILE
without filters, then excluded according to one or more filters, the file is excluded when the filter criteria are met.
Syntax
FILE file_set [, PROCESS process_file_set] [, PROGRAM program_file_set] [, USER user_id] ;
PROCESS
process_file_set
Includes files sets that are opened by the specified process.
PROGRAM
program_file_set
Includes file sets that are opened by the specified program.
USER
user_id
Includes file sets when the creator ID of the opening process or program is associated with the specified user ID.
Specifying attributes
You can optionally specify attributes for:
Compressing updates
Capturing or omitting record types
Supporting file renaming
Suspending and resuming logging
To specify multiple attributes, include each attribute in a separate FILE
statement, similar to:
COMPRESSUPDATES FILE $DATA1.DAT.PAYMENT, NOCOMPRESSUPDATES FILE $DATA1.DAT.ACCOUNT, GETBULKIO FILE $DATA1.DAT.TRANS, RENAMEDELAY 10
This example does the following:
Compresses updates for subsequent FILE
statements.
Turns compression off for the PAYMENT
file.
Logs bulk I/O for the ACCOUNT
file.
Supports file renaming by delaying the actual rename of the TRANS
file until the name is changed in the log.
See the following subsections for details about using the FILE
parameter attributes.
Compressing updates
You can compress and decompress update records using the COMPRESSUPDATES
and NOCOMPRESSUPDATES
options.
By default, update records are not compressed. The default can result in lower throughput, especially across Wide Area Networks, due to the additional traffic load. For example, consider an application that updates a 1000-byte customer record with a key 20 bytes long. If typically only the balance field within the customer record is changed, and that field is 10 bytes long, only 38 bytes rather than 1000 need to be transmitted across the network to execute a replicated update (20 bytes for the key, 10 bytes for the balance field, and 8 bytes to indicate the position within the record of the changed bytes and the key).
If you wish to use a field in KEYCOLS
which is not part of the source file's primary key, you cannot use COMPRESSUPDATES
.
Syntax
FILE file_set, {COMPRESSUPDATES | NOCOMPRESSUPDATES}
NOCOMPRESSUPDATES
No compression (the default).
COMPRESSUPDATES
COMPRESSUPDATES
directs Logger to compress update record images by comparing before and after-images. Compressed images include the key of the changed record and only the changed bytes within the record. Note that if you wish to use a field in KEYCOLS
which is not part of the source file's primary key, you cannot use COMPRESSUPDATES
.
Capturing or omitting record types
You can specify that Logger include or omit the following record types:
TMF audited records
Before updates
Bulk I/O updates
Unstructured file changes
Omit inserts, updates, or deletes.
Syntax
FILE file_set
[, GETAUDITED | IGNOREAUDITED]
[, GETBEFOREUPDATES | IGNOREBEFOREUPDATES]
[, GETBULKIO | IGNOREBULKIO]
[, GETUNSTRUCTURED | IGNOREUNSTRUCTURED]
[, OMITINSERTS | OMITUPDATES | OMITDELETES] ;
GETAUDITED | IGNOREAUDITED
Retrieves or omits data from files that are TMF audited.
Note:
Carefully consider possible outcomes before using GETAUDITED.
Logger cannot capture TMF abort operations. When GETAUDITED
is used, Logger will capture operations that it will not be able to back out if TMF aborts them.
GETBEFOREUPDATES | IGNOREBEFOREUPDATES
Retrieves or omits the before-images of records.
GETBEFOREUPDATES
retrieves images of records before they are changed in addition to capturing the after record image. For example, if an account balance was $100 before a transaction, and after it was $1000, both records will be written to the log trail. This information can be useful for data warehousing, archival, and other applications. When records are deleted, before-images are always logged. The default is to not extract before-images.
GETBULKIO | IGNOREBULKIO
Retrieves or omits bulk I/O updates. IGNOREBULKIO
(omit bulk I/O updates) is the default. Bulk I/O occurs when Guardian SETMODE 141
is invoked by a program, such as during FUP LOAD
or FUP DUP
.
GETUNSTRUCTURED | IGNOREUNSTRUCTURED
Retrieves or omits unstructured file changes. IGNOREUNSTRUCTURED
(omit unstructured file changes) is the default.
OMITINSERTS | OMITUPDATES | OMITDELETES
Excludes the specified record operation from being captured. You can combine these options.
Supporting file renaming
If your application renames database files while they are still open and being updated, the RENAMEDELAY
option ensures that the new file name changes in the log trail. For RENAMEDELAY
, specify a delay interval to give the system time to detect and record the new name.
Syntax
FILE file_set, RENAMEDELAY delay_seconds
delay_seconds
Represents the delay interval, as in RENAMEDELAY
10
. The interval should range from 5-15 seconds, depending on overall system resource usage and hardware capacity. In general, more powerful systems require less delay. Use this feature with caution, since the process invoking the rename will be delayed before being allowed to continue.