Control Values

You specify the control values in a list and separate them with semicolons.

The Plug-in supports three types of control values:

  • Text values: ABC, "ABC"
  • Bitmask values: "1001"&
  • Hexadecimal values: "1FB4"X

All three types can be specified in the same list:

ABC; "1001"&; "1FB4"X

Text Values

You can use a simple text expression or enclose it in single or double-quotes.

When a value is enclosed in quotes, the quotes are not considered a part of the value. If you want to embed a quote into a quoted value be sure to repeat the quote twice unless the quote differs from those at the beginning and at the end of the value.

Use unquoted values only when

  • a value does not include a semicolon
  • does not start or end with a space, leading and trailing spaces are not considered a part of an unquoted value.

A few examples are shown here. Note that in the Values column, the boldfaced values, not the commas between them, are the actual values.

Examples of Control Values in a List
Value List Values
"abc"; 'a' abc, a
"abcd'abcd'xyz" abcd'abcd'xyz
'abcd''abcd''xyz' abcd'abcd'xyz
a;b;c a, b, c
'abc Invalid value because of no closing single quotes
'abc'' Invalid value because of no closing single quotes
Note:
  • Matching of control fields applies the Trim Whitespaces from String Values setting of the Parse Copybook Data activity. If you select that setting, the activity removes the leading and trailing whitespaces from the data and from a control-field value before comparison.
  • Text values cannot be used if a control field is configured to have XSD type base64Binary
  • For Text values, the matching process is type-aware; for example, if your control field is numeric, variations of string representation of a number are acceptable in a control value.

Bitmask Values

The bitmask control values are quoted sequences of 0 and 1 with an ampersand at the end, for example "1001"&.

You use these values to check if bits specified as 1 are set in the byte value of a control field. Control-value bits specified as 0 are not checked.

Note that these checks operate on the raw byte value of the control field. It's copybook data type or other settings have no effect on this process.

The following rules apply:

  • Single or double quotes can be used. For example "1001"& and "1001'& are valid and denote the same bitmask.
  • You can use the repetition factor (n) to make your value compact. (n) repeats the following bit n times, for example, "1(6)01"& is equivalent to "10000001"&
  • Spaces are allowed anywhere within quotes. They are ignored.
  • Trailing zeros are allowed, but are ignored. Leading zeros are meaningful. For example, '10001'& is equal to '1000100000'&, but not equal to '00010001'&
  • A bitmask can be shorter than the raw data of a control field. In that case, the mask is checked starting at the leftmost bit of the field. The field data following the mask length is not taken into account.
  • If a bitmask is longer than a control field, it never produces a match. For example,

    01 ITEM PIC X

    is never matched by a control value

    '1000100011110111'&

Hexadecimal Values

Hexadecimal values are quoted sequences of pairs of hexadecimal digits followed by X. For example "1FB4"X.

You use these values to check if the raw binary value of a control field contains specific bytes. Note that the copybook type of the field or other settings do not affect the matching process.

The following rules apply:

  • Each byte is represented by two hexadecimal digits 0-F. Only an even number of hex digits is allowed.
  • Single or double quotes can be used. For example, '1FB4'X and "1FB4"X are valid and denote the same byte value.
  • You can use the repetition factor (n) to make your value compact. (n) repeats the following pair of hex digits n times, for example, "01(3)FF02"X is equivalent to "01FFFFFF02"X.
  • You can use spaces anywhere within "quotes" . They are ignored. You can use them to make values more readable, for example, "01 FF FF FF 02"X
  • A hexadecimal control value can be shorter than the byte data of a control field. In that case, the bytes are compared starting at the leftmost byte of the field. The data following the length of the control value is not taken into account.
  • If a control value is longer than the control field, it never produces a match. For example,

    01 ITEM PIC X.

    is never matched by a control value

    "01 FF FF FF 02"X

Matching Sequence

Some data values might match more than one control value. For example, a control field with a value xFF matches values '1'& and 'FF'X. In such cases, it is important to be aware of how the overall checking sequence operates.

  • All control values in the list are checked starting with the first value. Once a match is detected, the matching process stops.
  • The control value lists are checked starting from the first field in the redefine group. When a value is matched successfully the matching process stops.
Warning: Exercise care when changing the order of redefined items in a copybook.

Consider this example:

An item A with control value 'FF'X precedes item B with a control value '10000001'&. A control field value xFF results in the item A.

When B is placed before A, a control value xFF always results in B, because value '10000001'& matches a broader range of data and is checked first.