$maplist (parse-spec, list-macro, default-value) function

This function returns the value of the list-macro list that matches the value returned by the parse-spec argument. The list-macro (second argument) is the name of a list (either with or without @@ characters) found in the Correlation > Config > Lists tab. The function is useful for correlating or displaying error messages with a descriptive value. The default-value (third argument) is optional. If it exists, the default-value is returned if no match occurs in the list-macro argument for the value parsed by the parse-spec argument.

The content of list-macro is a standard list of keywords and descriptive text, where the first word of the list entry is a value that is compared to the value returned by the parse spec. If the list-macro is not found, or an entry in the list macro is not matched, just the parsed value is returned.

If a parse-spec returns a value with spaces, the spaces are substituted by underscore (_) characters. This behavior is important because the first column of the list-macro list must also contain underscores instead of spaces to match the result of the parse-spec. For more information, see the token-parse-spec-function.

In addition to supporting the Parse-Thread-Gadget, this parse function supports correlating messages against external data, such as the description of an error code that is not found in the message, but that is defined in a list macro.

The following examples show target strings, parse expressions, and return values:

Target String	Parse Expression	Return Value
100: xyz	$maplist ($1, @@mylist@@)	100: Invalid access Explanation: It is assumed that @@mylist@@ is a list macro and has the 100: Invalid access entry.
User Name: backup	$maplist(user name: *, @@ugroups@@)	backup – system level operator Explanation: It is assumed that @@ugroups@@ is a list macro and has the backup – system level operator entry.