Using nco_postmsg to send alerts to ObjectServers

You can send an alert to an ObjectServer by using the nco_postmsg utility. You can use this utility as a replacement for the IBM Tivoli Enterprise Console postemsg utility and the postzmsg utility.

The nco_postmsg utility accepts name-value pairs for the alert data and constructs an SQL INSERT statement. The statement is used to insert a new row of data into a specified database table in the ObjectServer.

You can run nco_postmsg from the command line, or you can develop scripts or automations that use the nco_postmsg command to send alerts to the ObjectServer. The frequency of execution can vary. If you run the utility from the command-line interface, the utility might run a few times a day. If the utility is run from a script, it might be run a few times a second. Multiple instances of the nco_postmsg utility can also run simultaneously. Some usage examples of the nco_postmsg utility are as follows:

  • You can use nco_postmsg to send single alerts to the ObjectServer for diagnostic or testing purposes; for example, during system configuration, or when troubleshooting alert delivery problems.
  • You can use nco_postmsg to send alerts that indicate the start and end of a maintenance period.
  • You can use nco_postmsg when feedback from an external automation is needed in the ObjectServer. For example, if an alert is received that causes an external automation to run. The external automation fires a script that performs an action, and the success or failure of this action needs to be recorded in the ObjectServer. You can include an nco_postmsg command in the script to insert a new alert with the status of the action, and additionally set up automations in the ObjectServer to process the new alert.

The nco_postmsg utility is installed with the Probe Support feature of Tivoli Netcool/OMNIbus, and can therefore be deployed separately from the other Tivoli Netcool/OMNIbus features, on one or more hosts. A properties file called nco_postmsg.props is available for the utility.

The nco_postmsg utility can establish a secure connection to the ObjectServer by using SSL in both FIPS 140-2 mode and non-FIPS 140-2 mode.

To send an alert to an ObjectServer, enter the following command:

$NCHOME/omnibus/bin/nco_postmsg [ -option [ value ] ... ] "column_name=column_value" ...

Where:
  • -option is the nco_postmsg command-line option and value is the value to which you are setting the option. Not every option requires you to specify a value.
  • column_name is a valid column name in the database table into which you want to insert the alert, and column_value is the matching data value that you want to insert. Each name-value pair for column_name=column_value must be enclosed in double quotation marks, as shown in the syntax for the command. Additionally, column_value must be enclosed in single quotation marks if it is a string value.
    Note: If you are sending an alert to the alerts.status table, a name-value pair for the Identifier field is mandatory. For more information about setting a value for the Identifier column, see the IBM Tivoli Netcool/OMNIbus Best Practices document at https://www.ibm.com/developerworks/community/wikis/home?lang=en#!/wiki/Tivoli+Netcool+OMNIbus/page/Best+Practices.
    When you specify column_value, use a data type that is appropriate for the ObjectServer field. Use Netcool/OMNIbus Administrator to verify the data types that are assigned to fields in database tables, or you can use the ObjectServer SQL DESCRIBE command.

Running nco_postmsg in UTF-8 encoding

You can run the nco_postmsg utility in UTF-8 encoding by using the -utf8enabled command-line option. You cannot, however, specify the name-value pairs directly from the command line, and must instead add the name-value pairs to a text file. In the text file, specify each name-value pair on a separate line, and enclose the value in single quotation marks if it is a string value. The text file must be in UTF-8 encoding, and can contain data for a single alert only. The nco_postmsg.props properties file must also be in UTF-8 encoding.

The syntax for running nco_postmsg in UTF-8 encoding is:

$NCHOME/omnibus/bin/nco_postmsg [ -option [ value ] ... ] -utf8enabled TRUE < file_name.txt

Where:
  • -option is any of the nco_postmsg command-line options (other than -utf8enabled), and value is the value to which you are setting the option.
  • file_name.txt is the file that contains the name-value pairs.

Error processing

When the nco_postmsg utility runs, it reads its properties file and validates any command-line options that are specified. Then, it constructs the INSERT statement by using the name-value pairs that were specified. Alerts are sent to the ObjectServer, provided that the specified name-value pairs and command-line options are valid. Errors are categorized as follows. All errors are written to a log file.
Errors that cause the current alert to be written to a cache file.
If a communication error occurs because the ObjectServer is down or is taking too long to respond, the nco_postmsg utility saves the alert in a cache file named nco_postmsg.cache, and then exits. Any subsequent alerts that are generated while there is a communication failure are also written to the cache file. When the cache file reaches its maximum size, the file is renamed with an _old suffix and a new nco_postmsg.cache file is created. If a file named nco_postmsg.cache_old exists, it is deleted during the renaming process, and its contents are lost.
Tip: The response time limit of the ObjectServer is set by the Ipc.Timeout property of nco_postmsg, and the maximum size of the cache file is set by the MaxCacheFileSize property.

The next time the nco_postmsg utility is run, and can successfully connect to the ObjectServer, alerts are sent to the ObjectServer in the following order:

  1. Alerts in the nco_postmsg.cache_old file (if one exists). The alerts are sent in order of age, with the oldest being sent first. When empty, the file is deleted.
  2. Alerts in the nco_postmsg.cache file. When empty, the file is truncated to 0 bytes.
  3. The current alert, which was generated when the nco_postmsg utility was run.
Errors that cause the current alert to be discarded.
Alerts are discarded under the following conditions:
  • Command-line errors: An invalid properties file path was specified or invalid syntax was specified for the name-value pairs.
  • Authentication errors: The authentication to the ObjectServer failed because of invalid login credentials, an invalid ObjectServer name, or SSL errors.
  • Database errors: The database table write permission was not set, the database table name was invalid, or there was a syntax error in the constructed INSERT statement.
  • File errors: An error occurred writing the entry to the cache file, or there were syntax errors in the properties file.

Additional notes

  • Users of nco_postmsg are subject to the ObjectServer authorization system, and so require insert permission on the database table into which the data is being written.
  • If not set within the properties file, a password is required when the nco_postmsg utility runs from the command line.
  • If the nco_postmsg utility is inserting data into the alerts.status table, it sets the value of the FirstOccurrence and LastOccurrence columns to the current UNIX time or POSIX time, unless these column values are explicitly specified on the command line or in a script.
  • If a value is specified for the Class column when the nco_postmsg is run, a name-value pair is added to the INSERT statement. If no value is specified for Class, the ObjectServer assigns the default class of 0 (zero) to the alert.
  • Multiple instances of the nco_postmsg utility can be configured to cache alerts to the same file by using the CacheFile property.
  • If a communication error occurs while alerts are being sent from a cache file to the alerts.status table, the alerts are retained in the cache file. The nco_postmsg utility attempts to resend the alerts the next time the utility runs. Consequently, alerts might be sent more than once, in which case, the Tally field is inaccurately incremented.