INCLUDE: Only use specific log records

Use the INCLUDE command to selectively include specific log records, after images, in the forward recovery processing, logstreamcopy processing or journal print processing.

Format

INCLUDE { | FILEID(id1,id2,...) | TERMID(id1,id2,... ) | TRANSID( id1,id2,...) }

Keywords

FILEID(id1,id2,...)

Specifies that CICS® VR must use only log records, after images, with these file IDs when performing the forward recovery. If more than one keyword is specified, for example, INCLUDE FILEID(DD1),TERMID(TST1), the log record must match both IDs specified for it to be included.

id1,id2,...: Specifies the file ID defined to CICS®. id1, id2, for example, can be 1-8 characters. Up to 99 IDs can be specified for one FILEID. If more than one ID is specified on the FILEID keyword, a log record only needs to match one of the specified file IDs to be included.

TERMID(id1,id2,...)

Specifies that CICS® VR must use only log records, after images, with these terminal IDs when performing the forward recovery. If more than one keyword is specified, for example, INCLUDE FILEID(DD1),TERMID(TST1), the log record must match both IDs specified for it to be included.

id1,id2,...: Specifies the terminal ID defined to CICS®. id1, id2, for example, can be 1-4 characters. Up to 99 IDs can be specified for one TERMID. If more than one ID is specified on the TERMID keyword, a log record only needs to match one of the specified terminal IDs to be included.

TRANSID(id1,id2,...)

Specifies that CICS® VR must use only log records, after images, with these transaction IDs when performing the forward recovery. If more than one keyword is specified, for example, INCLUDE TRANSID(DD1),TERMID(TST1), the log record must match both IDs specified for it to be included.

id1,id2,...: Specifies the transaction ID defined to CICS®. id1, id2, for example, can be 1-4 characters. Up to 99 IDs can be specified for one TRANSID. If more than one ID is specified on the TRANSID keyword, a log record only needs to match one of the specified transaction IDs to be included.

Usage Notes

Consider the following when using the INCLUDE command:

Multiple INCLUDE commands and EXCLUDE commands can be specified in the same job step. When this occurs, CICS® VR processes a log record against all EXCLUDE commands before it processes the log record against all INCLUDE commands. For each log record, if the EXCLUDE criteria is met, the record is excluded. If the EXCLUDE criteria is not met, then CICS® VR matches the log record against the next EXCLUDE command. When the log record has been examined against all the EXCLUDE commands, CICS® VR examines the log record against the first INCLUDE command, if the log record was not excluded by any of the EXCLUDE commands. If the INCLUDE criteria is met, or if no INCLUDE commands were specified, then the record is applied to the VSAM sphere being recovered. If it is not met, then CICS® VR matches the record against the next INCLUDE command. If the log record does not match any of the INCLUDE commands, this log record is not applied to the VSAM sphere being recovered. CICS® VR repeats this process for the next log record by first matching it against the EXCLUDE commands, then the INCLUDE commands.
If one or more INCLUDE commands are entered and no EXCLUDE commands are entered, all log records that match the entered include criteria is applied. For example, if you specify:
```
INCLUDE FILEID(DD1),TERMID(T1)
```
CICS® VR uses log records that only have a file ID of DD1 and terminal ID of T1. If you want CICS® VR to only use log records that have a file ID of DD1 or terminal ID of T1, you must specify two INCLUDE commands as follows:
```
INCLUDE FILEID(DD1) 
INCLUDE TERMID(T1)
```
There is no limitation on the number of INCLUDE (and EXCLUDE) commands.
You can specify up to 99 IDs on each keyword.
If you specify INCLUDE or EXCLUDE commands that eliminate all of the records, no records are applied.
Avoid specifying INCLUDE and EXCLUDE criteria that conflict (for example, INCLUDE FILEID(DD1) and EXCLUDE FILEID(DD1)). If conflicting criteria is specified, no records are applied to the VSAM sphere being recovered. No error messages are produced.

CICS® VR cannot perform a selective forward recovery using change accumulation data sets. Verify that the APPLYCA keyword is not specified on the RECOVER command when the INCLUDE or EXCLUDE command is specified in the same job step.

Examples

INCLUDE FILEID(DD3) TRANSACTIONID(APQ4)      |1|
INCLUDE TERMINALID(TST2)                     |2|

Assume these two INCLUDE commands are specified in one job step. The two INCLUDE commands tell CICS® VR to:

|1| Include all records that have both a file id of DD3
      and transaction id of APQ4, or
|2| Include all records that have a terminal id of TST2.

INCLUDE FILEID(DD1,DD2)                               |3|
INCLUDE FILEID(DD3) TERMINALID(TST1)                  |4|
INCLUDE FILEID(DD4) TRANSACTIONID(APQ1,APQ2,APQ3)     |5|
EXCLUDE FILEID(DD3) TRANSACTIONID(APQ4)               |1|
EXCLUDE TERMINALID(TST2)                              |2|

Assume these five commands are specified in one job step. Since multiple EXCLUDE or INCLUDE commands are specified in one step, CICS® VR processes a log record against all EXCLUDE commands before the log record is processed against all INCLUDE commands.

|1| Exclude all records that have both a file id of DD3 and
      transaction id of APQ4, or
|2| Exclude all records that have a terminal id of TST2.

If the log record was not excluded by any of the EXCLUDE commands, it is processed using the include criteria. For the remaining records, the log records that were not excluded by the EXCLUDE command.

|3| Include all records that have a file id of DD1 or DD2, or
|4| Include all records that have a file id of DD3 and 
      terminal id of TST1, or
|5| Include all records that have a fileid of DD4 and transaction
      id of APQ1, APQ2, or APQ3.

Synonyms

The EXCLUDE synonyms table provides the INCLUDE commands or keywords along with acceptable synonyms that can be used in place of the commands or keywords:

Table 1. EXCLUDE synonyms
Command or keyword	Synonyms
FILEID	DD, DDNAME
TERMID	TERMINALID
TRANSID	TRANSACTIONID