2.77 FILE
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
FILEfile_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
FILEfile_set
[, PROCESSprocess_file_set
] [, PROGRAMprogram_file_set
] [, USERuser_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 inKEYCOLS
which is not part of the source file's primary key, you cannot useCOMPRESSUPDATES
.
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. WhenGETAUDITED
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 GuardianSETMODE 141
is invoked by a program, such as duringFUP LOAD
orFUP 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
FILEfile_set
, RENAMEDELAYdelay_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.