EXIT_CODE_MAP - UCMD Manager configuration option

Owned by Stonebranch (Deactivated)
Jul 15, 2024
4 min read

Description

The EXIT_CODE_MAP option allows one or more exit codes from the user process executed by Universal Command Server to be translated (mapped) to a corresponding exit code for Universal Command Manager.

This overrides the default behavior of the UCMD Manager, which would normally exit with the same value as the user process.

EXIT_CODE_MAP is provided to simplify dependent processing in environments where exit code rules are enforced and/or where remote exit code values are invalid on the Manager platform.


IBM i

IBM i implementation of mapped exit codes is to issue an exception (escape) message that corresponds to the mapped exit code number; that is, the exit code is mapped to the severity of the IBM i exception message. However, if the mapped exit code is greater than 99, it is mapped to 99 (the highest allowed severity).

Before posting the exception message, UCMD posts an informational message, UNV2582, that explains mapped exit codes. Also, the original messages posted upon exit from UCMD are now issued as diagnostic messages. The new exception messages began with UCMFF to avoid collision with normal Universal Agent messages.

Usage

Method

Syntax

IBM i

UNIX

Windows

z/OS

Command Line, Short Form

n/a





Command Line, Long Form

-exit_code_map map


(tick)

(tick)

(tick)

Environment Variable

UCMDEXITCODEMAP=map

(tick)

(tick)

(tick)


Configuration File Keyword

exit_code_map map

(tick)

(tick)

(tick)

(tick)

STRUCM Parameter

EXITCDMAP(option)

(tick)




Values

map is a comma-separated list of rules in the following format:

[status]range:exitcode[,[status]range:exitcode,...,[status]range:exitcode]

In this format:

  • status is the termination status of the user process.
  • range is the range of user process exit codes to which the rule applies.
  • exitcode is the value with which the UCMD Manager will exit.

Valid values for status are:

  • a (abnormal)
  • n (normal)

If a value for status is not specified, the rule will apply to all termination types.


The exit codes mapped by a rule can consist of a single value or a range of values.

  • A hyphen ( - ) can be used to define a finite, inclusive range of exit codes. For example, a range of 1-5 will map all exit codes from 1 through 5, inclusive.
  • A greater than ( > ) or less than ( < ) symbol can be used to define an open-ended range of exit codes, where the value specified for range sets the lower limit and upper limit, respectively, of the range. For example, a range of >1 maps all user process exit codes greater than 1, while a range of <1 maps all exit codes with a value less than 1.
  • An asterisk ( * ) can be specified for range, which defines a mapping that applies to all user process exit codes for the given termination status (if specified).
  • Negative values can be specified for the exit code(s) specified by range. (Negative values are not supported for exitcode.)
  • For readability, spaces are allowed in the value specified for map, but will be ignored by UCMD Manager.

When entered from the command line, map should be enclosed in double ( " ) or single
( ' ) quotes if any of the mapping rules define an open-ended range. This will prevent the greater than ( > ) and less than ( < ) symbols from being interpreted by the command shell as an I/O redirection operator.

Exit code mapping entries are processed from left to right. The first entry that matches the termination status and exit code of a user process is the one applied.

Examples

Example 1

-exit_code_map "a*:16"

In this example, the map is interpreted as:

If the user process ends abnormally, the UCMD Manager exits with a value of 16.

If the user process ends normally, the UCMD Manager exits with the same value returned by the user process.

Example 2

-exit_code_map "1-5:4, a6-10:1,n6-10:2, >15:8, <20:12"

In this example, the map is interpreted as:

  • If the user process exits with a value of 1 through 5, inclusive, the UCMD Manager exits with a value of 4.
  • If the user process ends abnormally with a value of 6 through 10, inclusive, the UCMD Manager exits with a value of 1.
  • If the user process ends normally with a value of 6 through 10, inclusive, the UCMD Manager exits with a value of 2.
  • If the user process ends with a value greater than 15, the UCMD Manager exits with a value of 8.
  • If the user process ends with a value less than 20, the UCMD Manager exits with a value of 12.
  • If the user process exits with any other value, the UCMD Manager also exits with that value.

Example 3

-exit_code_map "a*:16,n*:0,>0:4"

In this example, the map is interpreted as:

  • If the user process ends abnormally, the UCMD Manager exits with a value of 16.
  • If the user process ends normally, the UCMD Manager exits with a value of 0.

By definition, the termination status of a process is either abnormal or normal. All exit codes returned by the user process will match one of these first two entries. The third entry in the map, which translates any user process exit code greater than 0 (zero) to a UCMD Manager exit code of 4, is ignored.