C$SYSLOG

This library routine can be used to open, write to, and close the system log. Using this routine, you can write to the system log or event notification system (on Windows) in the event of a serious error that administrators need to know about.

Usage

CALL "C$SYSLOG"
    USING OP-CODE, parameters

Parameters

OP-CODE Constant Indicates which C$SYSLOG operation to perform. The operations are described below in the Description section.
parameters vary depending on the op-code chosen Provide information and hold results for the operation specified. These parameters are discussed with their corresponding op-codes in the Description section below.

Description

C$SYSLOG sends messages to syslog on UNIX systems that have the syslog function. On other UNIX systems, and on other non-Windows operating systems, this routine sends messages to the console. On Windows systems, the routine sends messages to the event log, which can be viewed using the Event Viewer applet available on Windows.

The runtime also sends messages to the system log when it detects broken files. This function allows COBOL programmers to notify system administrators automatically when a broken file is detected, instead of relying on individual users to report such errors. The runtime sends such notifications only if the COBOL program has opened the system log using the C$SYSLOG routine as described below.

Note: Because the various implementations of system logging don't report errors, the C$SYSLOG routine does not report errors either, because it never receives any.

See your UNIX system documentation for information about the syslog facility. See your Windows documentation for information on the Event Viewer applet.

The following constants used by the C$SYSLOG library routine are defined in acucobol.def:

CSYSLOG-OPEN (op-code 0)

opens the system log. This operation takes the following two parameters and has no return value:

DOMAIN Alphanumeric item The UNC name of a Windows machine to which to send events. This parameter is used only for Windows machines. It is ignored on other operating systems.

If this parameter is set to any of the following items, the local machine executing the runtime receives the event messages:

  • the NULL keyword
  • an empty string literal (this setting generates a compiler warning)
  • a string literal that contains spaces
  • a data item with a value of spaces or low-values
APPNAME Alphanumeric item The name of the application under which to log the notifications. See the Event Viewer or syslog documentation for information about what this parameter actually does and how to filter notifications on this name.

CSYSLOG-WRITE (op-code 1)

allows you to write to the system log. This operation takes the following two parameters:

PRIORITY Numeric item This parameter may have one of the following values:
  • CSYSLOG-PRIORITY-SUCCESS (value 0)
  • CSYSLOG-PRIORITY-INFORMATION (value 1)
  • CSYSLOG-PRIORITY-WARNING (value 2)
  • CSYSLOG-PRIORITY-ERROR (value 3)

See the Event Viewer or syslog documentation that comes with your operating system for information about these values and how to filter based on them.

MESSAGE Alphanumeric item The message sent to the system log. This parameter has no maximum length; it is sent to the system log as is. The system administrator sees this message in the system log.

CSYSLOG-CLOSE (op-code 2)

closes the system log. This operation takes no parameters and returns no value. After the system log is closed and before it is opened again, all writes to the system log (including those done internally by the runtime for reporting broken files) fail with no warning or error message.