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

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.

Suspending and resuming logging

You can temporarily suspend, then resume logging for a specified file set by using the SUSPENDED and ACTIVE options.

Syntax

FILE file_set, {SUSPENDED | ACTIVE} ;
SUSPENDED

Temporarily suspends logging for the particular file set.

ACTIVE

Resumes logging for the file set.