Maintaining Transaction Filter Definitions

A transaction filter definition specifies filter conditions for replication, based on the values of fields in the database records. No transaction filter definitions are required. Transaction filter definitions are defined using the FILTER initialization parameter, but should be maintained using the Adabas Event Replicator Subsystem.

• Listing Transaction Filter Definitions

• Adding Transaction Filter Definitions

• Modifying Transaction Filter Definitions

• Copying Transaction Filter Definitions

• Deleting Transaction Filter Definitions

• Rules for Writing Filter Conditions

Listing Transaction Filter Definitions

To use the Adabas Event Replicator Subsystem to list the transaction filter definitions stored in the Replicator system file:

1. Select option F from the Adabas Event Replicator Subsystem Main Menu.

   The List of Transaction Filters screen appears showing all of the transaction filter definitions in the Adabas Event Replicator Subsystem.

   18:28:56 ***** A D A B A S EVENT REPLICATOR SUBSYSTEM ***** 2013-02-28 List of Transaction Filters M-RP1140 Sel Name Sel Name Sel Name Sel Name ------------ ------------ ------------ ------------ _ ABCDEF01 _ 52ZA05 _ 52ZA19 _ 52207313 _ ABCDEF02 _ 52ZA06 _ 52005019 _ 52207414 _ AFD _ 52ZA07 _ 52206101 _ 52207515 _ DNXABF _ 52ZA08 _ 52206202 _ 52207616 _ NXNAF _ 52ZA09 _ 52206303 _ 52207717 _ SMXTF _ 52ZA10 _ 52206404 _ 52207818 _ UYU _ 52ZA11 _ 52206505 _ 52207919 _ WIS1 _ 52ZA12 _ 52206606 _ 52208101 _ WIS2 _ 52ZA13 _ 52206707 _ 52208202 _ XYZ _ 52ZA14 _ 52206808 _ 52208303 _ 52ZA01 _ 52ZA15 _ 52206909 _ 52208404 _ 52ZA02 _ 52ZA16 _ 52207010 _ 52208505 _ 52ZA03 _ 52ZA17 _ 52207111 _ 52208606 _ 52ZA04 _ 52ZA18 _ 52207212 _ 52208707 Command ==> Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12--- Help Repos Exit Add - + Menu

The function keys on this screen perform the following functions:

Adding Transaction Filter Definitions

To use the Adabas Event Replicator Subsystem to add a transaction filter definition to the Replicator system file, complete the following steps:

• Step 1. Access the Transaction Filter Definition Area of the Adabas Event Replicator Subsystem

• Step 2. Specify a Transaction Filter Definition Name and Type

• Step 3. Add Filter Conditions to the Transaction Filter Definition

• Step 4. Save the Transaction Filter Definition

Step 1. Access the Transaction Filter Definition Area of the Adabas Event Replicator Subsystem

To use the Adabas Event Replicator Subsystem to add a transaction filter definition to the Replicator system file:

1. Select option F from the Administration menu.

   The List of Transaction Filters screen appears showing all of the transaction filter definitions in the Adabas Event Replicator Subsystem.

   18:28:56 ***** A D A B A S EVENT REPLICATOR SUBSYSTEM ***** 2013-02-28 List of Transaction Filters M-RP1140 Sel Name Sel Name Sel Name Sel Name ------------ ------------ ------------ ------------ _ ABCDEF01 _ 52ZA05 _ 52ZA19 _ 52207313 _ ABCDEF02 _ 52ZA06 _ 52005019 _ 52207414 _ AFD _ 52ZA07 _ 52206101 _ 52207515 _ DNXABF _ 52ZA08 _ 52206202 _ 52207616 _ NXNAF _ 52ZA09 _ 52206303 _ 52207717 _ SMXTF _ 52ZA10 _ 52206404 _ 52207818 _ UYU _ 52ZA11 _ 52206505 _ 52207919 _ WIS1 _ 52ZA12 _ 52206606 _ 52208101 _ WIS2 _ 52ZA13 _ 52206707 _ 52208202 _ XYZ _ 52ZA14 _ 52206808 _ 52208303 _ 52ZA01 _ 52ZA15 _ 52206909 _ 52208404 _ 52ZA02 _ 52ZA16 _ 52207010 _ 52208505 _ 52ZA03 _ 52ZA17 _ 52207111 _ 52208606 _ 52ZA04 _ 52ZA18 _ 52207212 _ 52208707 Command ==> Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12--- Help Repos Exit Add - + Menu

2. Press PF4 on the List of Transaction Filters.

   The Transaction Filter screen appears.

   18:30:29 ***** A D A B A S EVENT REPLICATOR SUBSYSTEM ***** 2013-02-28 Transaction Filter M-RP1150 Transaction Filter Name ..... ________ 1 of 1 Exclude or Include Records .. I ------ Source -------------------- ----- Target ----- Sel Group Field PE MU Image Begin Length Cond Field Value --- ----- ------------------------------------ ---- -------------------- Command ==> Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12--- Help Exit Add Save - + Menu

Step 2. Specify a Transaction Filter Definition Name and Type

To specify a transaction filter definition name and type:

1. Tab to the Transaction Filter Name field and specify a unique name for the transaction filter definition. The name must use alphanumeric characters and be between one and 8 characters long. This is the equivalent of specifying the FILTER NAME parameter in the Event Replicator Server startup job.

2. Tab to the Exclude or Include Records field and specify an "I" to include (replicate) the records selected by the filter definition or an "E" to exclude (do not replicate) records selected by the filter definition. This is the equivalent of specifying the FRECORDS parameter in the Event Replicator Server startup job. The default is "I".

3. Although no field filter conditions have yet been specified for the transaction filter definition, press PF5 to save it.

Step 3. Add Filter Conditions to the Transaction Filter Definition

For more information about rules of filter conditions, read Rules for Writing Filter Conditions.

To add filter conditions to the transaction filter definition:

1. Press PF4 to define a field filter conditions for the transaction filter definition. Up to 2500 filter conditions can be specified.

   The Filter Condition screen appears with the transaction filter name listed at the top of the screen.

   18:31:16 ***** A D A B A S EVENT REPLICATOR SUBSYSTEM ***** 2013-02-28 Filter Condition M-RP1155 Transaction Filter Name ..... MYFILT ------- Source ------ ------- Target ------ Group Field PE MU Image Condition Field PE MU Image 2nd line: Begin Length Begin Length ----- ----------------------- --------- ----------------------- ___ __ _____ _____ __ __ __ _____ _____ __ or value(s) _____ _____ _____ _____ Target Value 1 .. ____________________________________________________________________________ ____________________________________________________________________________ ____________________________________________________________________________ ____________________________________________________________________________ Target Value 2 .. ____________________________________________________________________________ ____________________________________________________________________________ ____________________________________________________________________________ ____________________________________________________________________________ Command ==> Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12--- Help Exit Save - + Menu

   Note that you can specify a target field, part of a target field, or multiple target values on this screen:

   • The target field is specified under the Target heading in the Field column.

   • The part of a target field is specified under the Target heading using a combination of the Field column and the Begin and Length columns (which are on the second line).

   • Multiple target values can be specified in the Target Value n fields at the bottom part of the screen.

2. Update the fields on this screen as described in the following table.

   Note:
   The transaction filter definition name cannot be changed.

   Parameter Name	Specify	Default
   Group	A group number you can use to group field filters together within a transaction filter definition. All of the field filters with the same group number are blocked and logically ANDed together when the filters are examined during subscription processing. In other words, a field in the database must meet all of the criteria of the group before it is selected. Likewise, different groups of field filters are logically ORed together. In other words, a field need only meet the criteria specified by one of the groups to be selected. Valid values are numbers ranging from "1" through "999". The equivalent processing in the Event Replicator Server startup job is available through the use of the OR keyword within a series of FFIELD parameters. For more information about rules of filter conditions, read Rules for Writing Filter Conditions.	---
   Source Field	The two-byte Adabas field code for the field to be compared. This field must be in the format buffer specified for the file in the SFILE definition of the subscription. This is the equivalent of specifying the FFIELD parameters in the Event Replicator Server startup job. If you want to specify part of a source field for the comparison, specify: a starting byte number in the Source Begin field on the second line. optionally, the length of the part to be compared in the Source Length field on the second line. Note: The format of the complete field is used for partial field comparisons. If the formats of a source field or partial source field and a target field or partial target field do not match, the comparisons may always result in an unequal condition. For example, comparing an alphanumeric field to a packed field will always result in an unequal condition. For more information about rules of filter conditions, read Rules for Writing Filter Conditions.	---
   Source PE	The index number (occurrence) of the periodic group (PE) to which the condition relates if the source field in this field filter is a PE field. Valid values range from 0 through 191. This is the equivalent of specifying the FSPE subparameter parameter in the Event Replicator Server startup job.	0, indicating the source field is not a PE field.
   Source MU	The index number of the multiple-value field (MU) to which the condition relates if the source field in this field filter is an MU field. Valid values range from 0 through 191. This is the equivalent of specifying the FSMU subparameter in the Event Replicator Server startup job.	0, indicating the source field is not an MU field.
   Source Image	Whether the source field is in the after image (AI), before image (BI), or the default image of the record. Valid values are "AI" and "BI". This is the equivalent for specifying the FSIMAGE subparameter in the Event Replicator Server startup job.	AI for adds and updates; BI for deletes
   Source Begin	The starting byte number of the partial Adabas source field to be compared. This field is only used if you want to specify a partial field for comparison and only if the field is of alphanumeric or binary format. This is the equivalent of specifying the FSBEGIN subparameter in the Event Replicator Server startup job. Note: The format of the complete field is used for partial field comparisons. Valid comparisons of different field types are listed in Field Type Considerations. For fixed length fields, valid values range from "1" (the start of the field) through the maximum length of the field (the last byte of the field). For variable length fields, valid values range from "1" (the start of the field) to the maximum length allowed for that field type. Counting occurs from left to right beginning with 1 for fields defined with alphanumeric format, and from right to left beginning with 1 for fields defined with binary format.	1
   Source Length	The numeric length of the partial Adabas source field that should be compared. This field is only used if you want to specify a partial field for comparison and only if the field is of alphanumeric or binary format. This is the equivalent of specifying the FSLENGTH subparameter in the Event Replicator Server startup job. Note: The format of the complete field is used for partial field comparisons. Valid comparisons of different field types are listed in Field Type Considerations. For fixed length fields, errors will occur if the sum of the values of the Source Begin and Source Length parameters exceeds the fixed length of the field. For variable length fields, the sum of the values of the Source Begin and Source Length parameters must not exceed the maximum length of the field plus 1. For example, if a variable length field has format "A" with a maximum length of 253 bytes, settings of Source Begin=1 and Source Length=253 are valid, but settings of Source Begin=2 and Source Length=254 are not.	If Source Begin is not specified, the default value is the entire field. If Source Begin is specified, the default value is the maximum length of the field minus the value of the Source Begin parameter plus 1.
   Condition	A condition operator code for the filter. Valid values are "EQ" (equal to), "NE" (not equal to), "LT" (less than), "LE" (less than or equal to), "GT" (greater than), or "GE" (greater than or equal to). This is the equivalent of specifying the FCOND subparameter in the Event Replicator Server startup job. When EQ or NE are specified, multiple target values and target values using wildcards can be tested. For all other condition codes, only single target values without wildcards can be tested. For more information about rules of filter conditions, read Rules for Writing Filter Conditions.	EQ
   Target Field	The two-byte Adabas field code for the field with which the source field will be compared. Use single quotation marks around the field code. This field must be in the same record as the source field. This is the equivalent of specifying the FTARGET parameter in the Event Replicator Server startup job. If you want to specify part of a target field for the comparison, specify: a starting byte number in the Target Begin field on the second line. optionally, the length of the part to be compared in the Target Length field on the second line. Note: The format of the complete field is used for partial field comparisons. Valid comparisons of different field types are listed in Field Type Considerations. This field is mutually exclusive with the Target Value n fields. If you specify the target field code, you cannot specify values in the Target Value n fields. For more information about rules of filter conditions, read Rules for Writing Filter Conditions.	---
   Target PE	The index number of the periodic group (PE) to which the condition relates if the target field in this field filter is a PE field. Valid values range from 0 through 191. This is the equivalent of specifying the FTPE subparameter in the Event Replicator Server startup job. This field is mutually exclusive with the Target Value n fields. If you specify the target field code, you cannot specify values in the Target Value n fields.	0, indicating the target field is not a PE field.
   Target MU	The index number (occurrence) of the multiple-value field (MU) to which the condition relates if the target field in this field filter is an MU field. Valid values range from 0 through 191. This is the equivalent of specifying the FTMU subparameter in the Event Replicator Server startup job. This field is mutually exclusive with the Target Value n fields. If you specify the target field code, you cannot specify values in the Target Value n fields.	0, indicating the target field is not an MU field.
   Target Image	Whether the target field is in the after image (AI), before image (BI), or the default image of the record. Valid values are "AI" and "BI". This is the equivalent of specifying the FTIMAGE subparameter in the Event Replicator Server startup job. This field is mutually exclusive with the Target Value n fields. If you specify the target field code, you cannot specify values in the Target Value n fields.	AI for adds and updates; BI for deletes
   Target Begin	The starting byte number of the partial Adabas target field at which the comparison should begin. This field should only be specified if you want to specify a partial field for comparison, if the field is of alphanumeric or binary format, and only if an Adabas target field (Target Field) is specified. This is the equivalent of specifying the FTBEGIN subparameter in the Event Replicator Server startup job. Note: The format of the complete field is used for partial field comparisons. Valid comparisons of different field types are listed in Field Type Considerations. For fixed length fields, valid values range from "1" (the start of the field) through the maximum length of the field (the last byte of the field). For variable length fields, valid values range from "1" (the start of the field) to the maximum length allowed for that field type. Counting occurs from left to right beginning with 1 for fields defined with alphanumeric format, and from right to left beginning with 1 for fields defined with binary format.	1
   Target Length	The numeric length of the partial Adabas target field that should be used for the comparison. This field should only be specified if you want to specify a partial field for comparison, if the field is of alphanumeric or binary format, and only if an Adabas target field (Target Field) is specified. This is the equivalent of specifying the FTLENGTH subparameter in the Event Replicator Server startup job. Note: The format of the complete field is used for partial field comparisons. Valid comparisons of different field types are listed in Field Type Considerations. For fixed length fields, errors will occur if the sum of the values of the Target Begin and Target Length parameters exceeds the fixed length of the field. For variable length fields, the sum of the values of the Target Begin and Target Length parameters must not exceed the maximum length of the field plus 1. For example, if a variable length field has format "A" with a maximum length of 253 bytes, settings of Target Begin=1 and Target Length=253 are valid, but settings of Target Begin=2 and Target Length=254 are not.	If Target Begin is not specified, the default value is the entire field. If Target Begin is specified, the default value is the maximum length of the field minus the value of the Target Begin parameter plus 1.
   Target Value n	A value against which the source field will be compared. Only one value can be specified in each Target Value field. Up to 128 Target Value fields are available in which you can specify values; use the PF7 and PF8 keys to scroll through them. Strings that include blanks should be enclosed in single quotes. Apostrophes in strings must be doubled (for example: ‘six o”clock’). A maximum of 254 characters can be specified for each value. Each value may consist of either free-format characters or a mix of elements specified using the A() or X() notation. If free-format data consists entirely of numeric data (including an optional leading "+" or "-" character) it is treated as a numeric value. If a value (or part of a value) is specified using A() notation, it will be treated as alphabetic data. Hexadecimal values may be specified using X() notation. A value must be specified entirely as free-format data, or composed of one or more A() or X() subelements. If a value begins with an A() or X() subelement all remaining subelements of the value must be so specified. For more information about rules of filter conditions, read Rules for Writing Filter Conditions. This field is mutually exclusive with the Target Field, Target Image, Target MU, and Target PE fields. You cannot specify values for the Target Field, Target Image, Target MU, or Target PE fields if you have specified a value for this field. This is the equivalent of specifying the FLIST subparameter in the Event Replicator Server startup job.	---

Step 4. Save the Transaction Filter Definition

To save the transaction filter definition:

• Press PF5 to save the transaction filter definition in the Replicator system file.

Modifying Transaction Filter Definitions

To use the Adabas Event Replicator Subsystem to modify a transaction filter definition in the Replicator system file:

1. List the transaction filter definitions in the Adabas Event Replicator Subsystem, as described in Listing Transaction Filter Definitions.

   The transaction filter definitions are listed on the List of Transaction Filters screen.

2. Locate the definition you want to modify on the screen and enter an M in the Sel column for that definition.

   You can locate the definition you want in the list by pressing the PF7 (F7) or PF8 (F8) keys to scroll through the list. You can also press PF2 (F2) to specify the name of the definition to which the list should be repositioned.

   An appropriate transaction filter definition screen appears for the transaction filter you selected.

3. Modify the Exclude or Include Records field, as necessary. If you want to modify a filter condition specification, enter an "M" next to it in the list to display and update the Filter Condition screen for that condition. If you want to delete a filter condition from the transaction filter definition, enter a "D" next to the condition in the list.

   Note:
   You cannot alter the name of the transaction filter definition. If you want to rename a transaction filter definition, first copy it using the name you want and then delete the original.

   For information on modifying this screen, read the description of adding transaction filter definitions in Adding Transaction Filter Definitions.

4. When all modifications have been made, press PF5 to save the changes.

Copying Transaction Filter Definitions

To use the Adabas Event Replicator Subsystem to copy a transaction filter definition in the Replicator system file:

1. List the transaction filter definitions in the Adabas Event Replicator Subsystem, as described in Listing Transaction Filter Definitions.

   The transaction filter definitions are listed on the List of Transaction Filters screen.

2. Locate the definition you want to copy on the screen and enter a C in the Sel column for that definition.

   You can locate the definition you want in the list by pressing the PF7 (F7) or PF8 (F8) keys to scroll through the list. You can also press PF2 (F2) to specify the name of the definition to which the list should be repositioned.

   A dialog appears requesting a name for the copy of the transaction filter definition.

   Enter new name: ________ or press PF3 to cancel

3. Specify a new, unique name for the copy of the transaction filter definition and press Enter.

   The transaction filter definition is copied and the copy appears on the List of Transaction Filters screen.

Deleting Transaction Filter Definitions

To use the Adabas Event Replicator Subsystem to delete a transaction filter definition in the Replicator system file:

1. List the transaction filter definitions in the Adabas Event Replicator Subsystem, as described in Listing Transaction Filter Definitions.

   The transaction filter definitions are listed on the List of Transaction Filters screen.

2. Locate the definition you want to delete on the screen and enter a D in the Sel column for that definition.

   You can locate the definition you want in the list by pressing the PF7 (F7) or PF8 (F8) keys to scroll through the list. You can also press PF2 (F2) to specify the name of the definition to which the list should be repositioned.

   Note:
   If you want to delete a filter condition from the transaction filter definition, read Modifying Transaction Filter Definitions.

   The transaction filter definition is deleted.

Rules for Writing Filter Conditions

There are various things you should consider when creating filter conditions. This section describes them.

• So My Record Matches the Filter Conditions -- Now What?

• Failed or Ignored Filter Conditions

• Target (FLIST Parameter) Value Syntax

• When You Can Specify Multiple Targets

• How Multiple Filter Conditions Are Interpreted

• Specifying a Range of Values

• Field Type Considerations

• Varying Field Length Considerations

• Using Wildcards

So My Record Matches the Filter Conditions -- Now What?

Filter conditions are based on the values of fields (or partial fields) in an SFILE record definition. If a field or partial field meets all of the filter conditions specified, the record is selected. Once selected, the record will be either included or excluded from replication processing, based on what the transaction filter definition specifies. So selection of a record does not necessarily mean that it will be replicated -- merely that it passed the filter conditions specified by the transaction filter definition. If the transaction filter definition indicates that selected records should be excluded from replication, the record will not be replicated.

Transaction filter definitions indicate whether selected records are replicated or not via the FRECORDS initialization parameter in the DDKARTE statements of the Event Replicator Server startup job or via the Exclude or Include Records field on the Transaction Filter screen of the Adabas Event Replicator Subsystem.

Failed or Ignored Filter Conditions

A filter condition will be ignored if it cannot be evaluated. This can occur if the image to be tested (set by the FSIMAGE or FTIMAGE parameters) is not present for replication. The effect of this on filter processing varies, based on whether the filter occurs as part of include or exclude processing and, if it is included in a group of conditions, how the other conditions in the group are matched, failed, or ignored. This is best explained in a series of examples.

1. Suppose an add command (N1) adds a record containing field AB to which the following filter is applied:

   FRECORDS=INCLUDE 
     FFIELD='AB',FSIMAGE=BI
       FCOND=EQ
       FLIST='1916'
   

   In this case, the filter cannot be evaluated because only the after image is present for an add and the filter is for the before image (FSIMAGE=BI). So this filter is ignored and no test is done on the field to see if the before image is equal to "1916". Consequently the add transaction is not included in replication.

2. Likewise, a similar exclude filter is also ignored:

   FRECORDS=EXCLUDE 
     FFIELD='AB',FSIMAGE=BI
       FCOND=EQ
       FLIST='1916'
   

   In this case, the filter cannot be evaluated because only the after image is present for an add and the filter is for the before image (FSIMAGE=BI). So this filter is ignored and no test is done on the field to see if the before image is equal to "1916". However, because this is an exclude filter, the add transaction is not excluded from replication; in other words, it is included in replication, regardless of whether or not the before image of the AB field was equal to "1916".

3. Now consider the following transaction filter using multiple filter conditions and include processing:

   FILTER NAME=MYINCLF
     FRECORDS=INCLUDE 
       FFIELD='BA',FSIMAGE=BI,FCOND=EQ,FLIST='AAAA'
       FFIELD='BB',FSIMAGE=AI,FCOND=EQ,FLIST='VVVV'
       FFIELD='BC',FSIMAGE=AI,FCOND=EQ,FLIST='XXXX'
   

   If an add command (N1) is issued for a record containing the BA, BB, and BC fields, no before image is present for these fields -- only the after image. Therefore, the filter condition for BA is ignored because the filter is for the before image; the BA filter condition is treated as if it is not even specified. The add transaction, then, is only included in replication if both filters for fields BB and BC are true.

4. Finally, consider the following transaction filter using multiple filter conditions, exclude processing, and OR processing:

   FILTER NAME=MYEXCLF
     FRECORDS=EXCLUDE 
       FFIELD='BA',FSIMAGE=BI,FCOND=EQ,FLIST='AAAA'
       FFIELD='BB',FSIMAGE=AI,FCOND=EQ,FLIST='VVVV'
     OR
       FFIELD='CA',FSIMAGE=AI,FCOND=EQ,FLIST='EEEE'
       FFIELD='CB',FSIMAGE=AI,FCOND=EQ,FLIST='CCCC'
     OR
       FFIELD='DA',FSIMAGE=BI,FCOND=EQ,FLIST='OOOO'
       FFIELD='DB',FSIMAGE=BI,FCOND=EQ,FLIST='CCCC'
   

   If an add command (N1) is issued for a record containing these fields, no before image is present for these fields -- only the after image. Therefore, the filter conditions for BA, DA, and DB are ignored because the filters are for the before image; these filter conditions are treated as if they are not even specified.

   The add transaction, then, is only excluded in replication if the filter for BB is satisfied OR if both the filters for field CA and field CB are satisfied. Otherwise, the add transaction is included in replication.

Target (FLIST Parameter) Value Syntax

Target (FLIST parameter) values are the values to be compared to the source field (FFIELD parameter) using the condition type specified (FCOND parameter). When multiple values are being compared for a field, they must be specified in a comma-separated list.

Each value can be expressed in one of two ways:

• You can specify values as free-format text. This text can be any set of alphanumeric set of characters. If blanks are required in the value, you should enclose the value in single quotes.

  When the data in the text is all numeric with an optional leading "+" or "-" sign, it is flagged as a numeric value and will be handled differently depending on the source field type in the Event Replicator Server definitions.

• You can specify values as a combination of A() and X() constructs that enable you to enter data for the same variable in alphabetic format, hexadecimal format, or both, as required. If the element value starts with the string "A(" or "X(" it is treated as an A() or X() value. If the value does not start with one of these strings, the value is treated as free-format text.

This section describes rules specific to these different methods of specifying target values.

• Free-Format Value Rules
• A() and X(0) Format Value Rules
• Examples

Free-Format Value Rules

The following rules apply to free-format values.

• Free-format values can be any sequence of alphanumeric data apart from the comma character itself.

• If a blank is required for the free-format value, specify the value in single quotes.

• If an apostrophe is required as part of a free-format value, double the apostrophe (for example,‘six o”clock’).

• If the value consists of all numeric characters with an optional leading "+" or "-" sign, the value will be treated as numeric.

• If the value begins with a single asterisk (*), it is interpreted as a wildcard suffix (for example, '*xyz').

• If the value ends with a single asterisk, it is interpreted as a wildcard prefix (for example, 'abc*').

• If two asterisks are found together (**) in any location in the free-format value, they are interpreted as a single asterisk in the resulting data.

• If a single asterisk is found in the middle of the data, it is rejected as invalid.

A() and X(0) Format Value Rules

The following rules apply to A() and X() value specifications.

• The A() construct is specified using the following syntax:

  A(data)

  In this syntax, the data specified can be any alphanumeric characters, except the parentheses characters.

• The X() construct is specified using the following syntax:

  X(data)

  In this syntax, the data specified must be an even number of characters in the range X’F0’ to X’F9’ (i.e. 0 to 9) and x’C1’ to X’C6’ (i.e. A to F). Each pair of characters will represent the hexadecimal value for one byte in the resultant value.

• If a value starts with an A() or X() construct, the entire value must be specified using these constructs. You cannot mix them with free-format values.

• A() and X() constructs can be specified multiple times in the same value specification. They must always have matching opening and closing parentheses, or the entire value specification is treated as invalid.

• When the A() construct is used, the asterisk (*) wildcard character is treated in the same manner as for free-format values.

• When the X() construct is used, the X'5C' character (which represents an asterisk) is treated like any other hexadecimal character and is not interpreted as a wildcard.

Examples

In the following example, an FLIST value of "ABCDE" is specified:

FLIST='ABCDE'

In the following example, a numeric FLIST value of "12345" is specified:

FLIST='12345'

In the following example, a numeric FLIST value of "-678" is specified:

FLIST='-678'

In the following example, an FLIST value of "AB123" is specified:

FLIST='AB123'

In the following example, an FLIST value of "XyZ" is specified:

FLIST='A(XyZ)'

In the following example, an FLIST value of "SSS" (the alphabetic equivalent of X'E2E2E2') is specified:

FLIST='X(E2E2E2)'

In the following example, an FLIST value of "abc<<<def" is specified:

FLIST='A(abc)X(4C4C4C)A(def)'

In the following example, an FLIST value of "AX(E2E2E2)" is specified:

FLIST='AX(E2E2E2)'

In the following example, an FLIST value of "1A(BCD)" is specified:

FLIST='1A(BCD)'

In the following example, an FLIST value of "1A(BCD)" is specified:

FLIST='1A(BCD)'

In the following example, an FLIST value of "*abc*" ("abc" is the alphabetic equivalent of X'C1C2C3') is specified. Note that this FLIST value is open-ended because wildcards are specified:

FLIST='A(*)X(C1C2C3)A(*)'

In the following example, an FLIST value of "*def**" is specified. Note that the first asterisk specifies a wildcard, but the last two asterisks specify asterisk characters (the alphabetic equivalent of X'5C5C'):

FLIST='A(*def)X(5C5C)'

The following examples are invalid because they specify a wildcard asterisk in the middle of the values:

FLIST='*ABC*DEF*'
FLIST='X(F5F6)*X(F7F8)'
FLIST='X(F2)A(*)X(F4)'

The following examples are invalid because they specify invalid hexadecimal data:

FLIST='X(ABACFGZZAE)'
FLIST='X(ABC)'

The following example is invalid because it mixes free-format and hexadecimal data:

FLIST='X(AB)AB'

The following example is invalid because it misuses commas:

FLIST='X(ABAC),,A(123)'

The following example is invalid because it misuses parentheses in the A() construct:

FLIST='A(12(34))'

When You Can Specify Multiple Targets

You can only specify multiple targets if the condition operator is EQ (equal) or NE (not equal). The LT (less than), LE (less than or equal), GT (greater than), and GE (greater than or equal) operators logically assume a comparison of the field value to a single target value, so multiple target values are not allowed for these condition operators.

Since wildcards are essentially a concise way of specifying multiple targets, you can also only use wildcards when the condition operator is EQ or NE.

If your filter checks to see if the field value is equal to a list of target values, the field value need only be equivalent to one of the target values for the filter condition to be true. On the other hand, if your filter checks to see if the field value is not equal to a list of target values, the field value must not be equal to any of the target values for the filter condition to be true.

Examples

In the following example, records for which the after image of the AA field is equal to "1", "2", "3", or "4" are selected.

FFIELD=’AA’,FSIMAGE=AI
FCOND=EQ
FLIST=’1,2,3,4’

In the following example, records for which the after image of the AA field is greater than "5" are selected.

FFIELD=’AA’,FSIMAGE=AI
FCOND=GT
FLIST=’5’

In the following example, records for which the first three bytes of the after image of the BB field contain the characters "abc" are selected.

FFIELD=’BB’,FSIMAGE=AI
FCOND=EQ
FLIST=’abc*’

In the following example, records for which the last three bytes of the after image of the BB field contain the characters "xyz" are selected.

FFIELD=’BB’,FSIMAGE=AI
FCOND=EQ
FLIST=’*xyz’

In the following example, records in which no bytes of the after image of the BB field contain the characters "klm" are selected.

FFIELD=’BB’,FSIMAGE=AI
FCOND=NE
FLIST=’*klm*’

The following example is invalid because it specifies multiple FLIST target values when the condition code is not EQ or NE.

FFIELD=’AA’,FSIMAGE=AI
FCOND=LE
FLIST=’1,2,3,4’

The following example is invalid because it specifies a wildcard in the FLIST target value when the condition code is not EQ or NE.

FFIELD=’AA’,FSIMAGE=AI
FCOND=GT
FLIST=’*xyz’

How Multiple Filter Conditions Are Interpreted

You can specify multiple filter conditions within a single transaction filter definition. Unless otherwise grouped, all of the specified filter conditions must be true for a record to be selected. In other words, the filter conditions are logically ANDed. In the following example, cond1, cond2, cond3, and cond4 must all be true for the record to be selected as they are logically ANDed:

FILTER NAME=MYINCLF
FRECORDS=INCLUDE
FFIELD='field',FCOND=cond1,FTARGET or FLIST values1
FFIELD='field',FCOND=cond2,FTARGET or FLIST values2
FFIELD='field',FCOND=cond3,FTARGET or FLIST values3
FFIELD='field',FCOND=cond4,FTARGET or FLIST values4

If, however, you want to insert some logical ORs in this example, you can. To do this you would use the OR keyword in the DDKARTE statements of the Event Replicator Server startup job or use the Group field on the Filter Condition screen in the Adabas Event Replicator Subsystem. As an example of using the OR keyword, consider the following modification to the example given earlier.

FILTER NAME=MYINCLF
FRECORDS=INCLUDE
FFIELD='field',FCOND=cond1,FTARGET or FLIST values1
FFIELD='field',FCOND=cond2,FTARGET or FLIST values2
FFIELD='field',FCOND=cond3,FTARGET or FLIST values3
OR
FFIELD='field',FCOND=cond4,FTARGET or FLIST values4

In this example, condition1, condition2, and condition3 must be true OR condition 4 must true for the record to be selected.

When using the Group field on the Filter Condition screen of the Adabas Event Replicator Subsystem to define your transaction filter definitions, simply use the same group number for those conditions you want ANDed. Conditions with different group numbers are logically ORed.

Specifying a Range of Values

You can specify a range of values in your filter condition by creating two conditions that are logically ANDed (read How Multiple Filter Conditions Are Interpreted). Simply define one filter condition to test for values greater than (GT) or greater than or equal to (GE) the lowermost value. Then define the second filter condition to test for values less than (LT) or less than or equal to (LE) the uppermost value. As both conditions must be true since they are logically ANDed, your range specification is assured.

Field Type Considerations

Ideally, when a field is compared to another field, the field types will be the same. However, it is possible to compare fields of different formats. For example, you can compare a packed decimal format field with a binary format field. For a complete list of compatible Adabas field types, refer to your Adabas documentation.

This section covers the following topics related to how fields of different formats are compared

• Valid Comparison Table
• Comparison Processing by Field Type
• UES Considerations

Valid Comparison Table

An asterisk (*) in a cell in the following table indicates that a comparison of the field types is valid. A blank in a cell in the table indicates that a comparison is not supported.

Comparison Processing by Field Type

When either the source or target field is of type floating point (but not both fields), the other field will be converted to floating point, and a floating point comparison will be made. SARC settings governing byte-swapping and floating point type (HFP, IEEEfloat, and VAXfloat) are honored.

In all other cases the following conversions and comparisons will apply:

When a field is compared to a list of target values, the target values are converted (if they are not the same) to the data type of the source field, once the source field type is determined. This can cause problems in the accuracy of filter condition processing if a target value in the list cannot be converted or is otherwise incompatible with the required source field type. So target values and target fields must be specified carefully to avoid such problems.

Target list values entered as alphanumeric are converted to the data type of the source field, honoring the SARC, SACODE and SWCODE parameter settings.

Target list values for alphanumeric fields may be entered as alphanumeric, hexadecimal, or a mixture of both. If it is a mixture of both -- for example, FLIST=A(ABC)X(C4C5C6)A(GHI) -- it is treated as an alphanumeric field even though some of it is specified as hexadecimal.

Target list values for binary fields may be entered in hexadecimal. The hexadecimal values are assumed to be in a form that honors the SARC parameter settings.

Target list values for floating point fields may be entered in hexadecimal. The hexadecimal values are assumed to be in a form that honors the SARC parameter settings such as floating-point format and byte order.

Target list values may not be entered in hexadecimal for zoned decimal, packed decimal and fixed point fields.

UES Considerations

When a field is compared to a target value that is entered in hexadecimal, the target value is normally accepted without any conversion. It is assumed that you have taken into account the settings of the SARC, SACODE and SWCODE parameters when constructing the hexadecimal value. It is important to remember that a given hexadecimal value may have to reflect the setting of more than one of these three parameters.

• The SARC parameter defines special data architecture for fields in the record and value buffers (see the description of record buffers in your Adabas documentation). If the byte order bit of the SARC value is set, the hexadecimal value may have to be entered with low-order bytes first. If the field is a character field, the entered hexadecimal byte values must reflect the setting of the SARC encoding family bit.

  Note:
  If you want to transfer replicated and initial-state data to a relational database using the Event Replicator Target Adapter ( the Destination Class, or DCLASS parameter, is set to "SAGTARG"), set the SARC parameter to "2" -- regardless of the location of your relational database.

• The SACODE parameter assigns special encoding for alphanumeric fields during the user session. Hexadecimal bytes values must reflect the SACODE setting.

• The SWCODE assigns special encoding for wide-character fields during the user session. Hexadecimal values must reflect the SWCODE setting.

This section covers the following topics related to UES processing:

• Internal Handling of UES Settings
• Examples Honoring UES Settings

Internal Handling of UES Settings

When FILTER FLIST value parameters are being processed, the UES settings and the FCOND values are taken into account in an attempt to minimize conversion overhead at runtime.

• If the FCOND setting is either EQ or NE then the FLIST value will be stored as entered. At runtime, this FLIST value can be compared directly with the field value with no conversion required regardless of the UES settings.

• If the FCOND setting is LT, GT, LE, or GE, the FLIST value will be converted, taking into account the UES settings, so that valid comparisons can be made for the specified FCOND value. At runtime, the field value will be similarly converted to facilitate valid comparisons.

It is important to note here that FLIST values that are entered as hexadecimal values for comparison with binary fields must be entered in a form that honors the SARC settings. In other words, they must be specified in the same form as the field is stored in the record buffer. Similarly wide-character field values entered as hexadecimal must be specified in the same form as the field is stored in the record buffer.

FLIST values that are entered as EBCDIC text, or as numbers, will be converted appropriately.

Examples Honoring UES Settings

FLIST='X(41100000)'

FLIST='X(44C3500000000000)'

FLIST='X(40800000)'

FLIST='X(80400000)'

FLIST='X(4843500000000000)'

FLIST='X(4348005000000000)'

FLIST='X(0041004200420040004100420043004400450046)'

FLIST='X(4100420042004000410042004300440045004600)'

FLIST='X(000004)'

FLIST='X(040000)'

Varying Field Length Considerations

When the length of the source field and target field are different, the shorter value is converted to the size of the longer value. For alphanumeric data, the value is padded on the right with blanks. For numeric data, the value is padded on the left with hexadecimal zeros.

Using Wildcards

You can use an asterisk (*) as a wildcard for target values if the condition code being used is EQ (equal) or NE (not equal). You cannot use wildcard characters for any other filter conditions (GT, LT, LE, or GE).

• If you want to test the field for any value beginning with a specific string of characters, simply append an asterisk to the end of the value. For example, to test for a field value starting with the characters "POW", specify "POW*" as the target value.

• If you want to test the field for the occurrence of as specific string within its value, precede and supercede the string with an asterisk. For example, to test for the occurrence of the string "WER", specify "*WER*" as the target value.

• If you need to test for the occurrence of an asterisk itself in a field value, specify two asterisks in a row for the target value ("**").