Skip to main content

Flags and Filters

Many commands can limit their action to some records or fields, so there are some common filters that we can use on them that are consistent across the application to define exactly that. Here we will present how to use them.

Flags are used in the command line and they are indicated by two dashes followed by a word, or some times just one dasy followed by a single letter (this is considered an "alias" to simplify its usage). Some flags can accept values as parameters and act as a filter, other times the presence of the flag itsef changes the behavior.

There are global flags that apply to all the commands, and some other flags that vary depending on the command, so they are not present in all of them.

Global flags​

These flags are present and can be used in all commands.

Flags:
      --help     Show context-sensitive help (also try --help-long and --help-man).
  -v, --verbose  Add more information displayed on some commands.
      --mono     Supress color on output.
      --ignore   Try to ignore some errors and continue processing the file
  -W, --width    Ignore small terminal width check and force execution
  -z, --silent   Suppress all output (banner, headers, summary) except the results. Specially useful for DESCRIBE command piped to a search utility like fzf
  • --help: This flag has the same effect as the HELP command, and can be added in any place of the line to get help.
  • --verbose (-v): In some commands, it increases the amount of information being displayed. Usually the amount of output is limited to avoid an excess of information, but using this flag we can get more information.
  • --mono: By default, output is colorized to improve readability. This can be a problem when redirecting the output to a file because the control characters used for displaying colors in the terminal are shown as garbage characters when viewing the file. In these cases it is advisable to use this flag to force the supression of colors in the output.
  • --ignore: This flag is becoming obsolete, but it is there for the rare cases that when reading a file and some format errors are found, the process is cancelled. By using this flag the tool tries to continue reading the file as much as possible and load the file anyway. In the latest version of the tool these situations are tried to be fixed automatically, but there still may be cases where this flag can be of use.
  • --silent (-z): Normally the output on screen contains extra information like the banner (with information about version and build), and a trailer with the total execution time. In other cases the output is formatted to be more human readable. But there are situations where we need to process that output using some external tool and all this extra information makes that harder. This simple flag just suppresses the output color, skips showing the banner and trailer, and for big files it hides the progress bar. Besides this, depending on the command, it can modify the output format for these external tools to be able to process the output easier.

Command flags​

Every command can handle their own flags and their usage is explained in the corresopnding section. However, some of them are shared by many commands, so instead of explaining their usage in every command we summarize their usage here:

-T​

Filter by file type.

This flag requires an associated value that consists in a letter, that can be either “I” or “M”

It is used when we supply a list of files to process, like when using wildcards, but we only want to apply the command to certain file types like IPM or MPE

Usually the commands just ignore the invalid file types, but if the list contains valid files and we just want to process one file type, we can tell the command to just process the file type indicated by this file. Currently we can just indicate IPM or MPE types. The rest will just be ignored.

-C​

This flag is a filter that allows to only consider records that correspond to one Function Code. It receives a text that identifies the desired Function Code by description (it does not have to be the exact description).

For example, if we want to consider only records containing information about Chargebacks, we can add “-C chargeback” (To see the full list of available Function Codes, we can execute “cardak describe func”)

-R​

This flag can filter by record number. We can specify the records to be considered by using their physical record number (position) inside the file. It receives a single value or a list of values separated by commas. These values can be just a number to indicate one particular record, or they can be a range of records. Range of records are represented by putting the initial and ending record numbers separated by a dash. Both ending values will be included in the range.

For example, if we want to process the records numbered 10, 12, 30 to 39 and 50, we can write: “-R 10,12,30-39,50”

There is a special case with the GREP command and it is that when we use it over just one file and there are records matching the condition, these results are temporarily saved and can be used by the next command by using the flag --last, so we don't need to write the list of record numbers (that can be an extense list) to operate on the list of records that match the last GREP command. The tools check when using this flag that we are using the same file used in the last GREP command.

-F​

This flag filters by field. In some cases we need to limit the action to certain fields. Just as with the previous flag, this one also receives a list that identifies the fields (in the next section we will see how to identify the fields).

This flag can receive a list of fields or the name of a previously saved filter, which is in fact, just a list of defined field names identifiers associated with a name (the name of the filter).

Field Identifiers​

When dealing with IPM files we find two type of elements, the Data Elements (DE) and the Private Data Subelements (PDS). In turn, these can be subdivided in smaller fields named SubFields.

The naming convention used in the MasterCard manuals and in this tool follows these rules: DE fields are followed by a number between one and tree digits that identify each field, while the PDS are followed by a four-digit value. SubFields are indicated by using the letters "SF" followed by a two-digit number, and all this is appended to the corresponding field. For example, the field named “Card Acceptor Name” will be DE043, and it will be divided into 6 parts, where each one would be: DE043SF01, DE043SF02, etc.

This tool, in order to make the identification of a field easier and more flexible, accepts the following formats:

Data Elements (DE)​

The DE can be represented with the letters "DE" or "D", followed by one to three digits, or just by indicating a single number with up to three digits. When using the letters, they can be either in Upper or Lower case.

For example, to represent field DE43, we can use any of these formats:

DE043, DE43, D43, D043, 043, 43

Private Data Subelements (PDS)​

In the case of PDS, we can represent them using the letters "PDS", "PD" or "P" followed by one or four digits, or just by indicating a sinble number consisting of four digits. Again, when using letters they are case-insensitive.

Please note that when using just digits, if we have one to three digits, it will represent a DE, and when using exactly 4 digits, it represents a PDS.

For example, to represent field PDS0021 we can use any of these formats:

PDS0021, PD21, P21, 0021, etc.

SubFields​

Suffields are indicated by adding the letters "SF" or "S" followed by one or two digits, and they are placed following any representation of the correspoindig field. Again, this is case-insensitive.

For example, for field DE04 tan contains some SubFields, we could use any of these formats:

DE043SF03, D43S3, 043S3, etc.

The same logic applies for subfields of PDS, so, for PDS0158, we can use any of these formats PDS0158SF03, P158s3, 0158s3, etc.

Stored filters​

It is possible to use previously stored filters that were defined using the FILTER command.

When we use the --filter (-F) flag we have two options, either include the list of fields or use the name of a previously saved filter, which is the same as writing the list of fields contained in that filter.

Search in fields​

For commands like GREP where we want to search a value in a specific field, we can specify the field and the value by writing the field identifier and the value separated by a colon (":").

The field identifier is defined according to the rules mentioned previously, and the value to search is a regular expression.

For example, if we want to search for an amount, we could use someting like D4:^0+35010$ to search for an amount of 350.10

We need to consider that the decimals are included in the value and there is no indicator for the decimal position. To know how to evaluate the value, we need to determine how many decimal positions are being included, and that information comes in field PDS0148, where PDS0148SF01 is the currency code and PDS0148SF02 is the number of decimal positions.