System Logger API Library Module

The system logger API library module has the file name sys_log.c. This module provides a multi-user/system message logging service. System log messages are sent to the system log server which logs the messages for many computers.

The Unix/Linux version of this API uses the TCP Berkeley socket interprocess communication method. The Windows version of this API uses the Winsock interprocess communication method. The QNX 4.x version of this API uses it's own message passing IPC method.

Normally, this API would be a client of the client IPC API. Since both client and server IPC API's use the same function names, a program bound to the server API could not also bind to the client API in the same program. For this reason, this API does not use the client IPC API. It does, however use the low level TCP functions contained in the module ipcomm.c (TCP only).

Any mention of QNX in this documentation refers to the QNX 4.x OS.

This module contains the following global data:

- host name (TCP only)
- port number (TCP only)
- client socket data depending on platform (TCP only)
- process ID of the system log server (QNX only)
- sys_log flag/switch (sys_log_islog)
- console output flag (sys_log_console_output)

All logging function calls will immediately return if the log switch is off. All system logger codes and defines are located in the include file sys_log.h.

The system log server uses a primary and alternate log file. If the primary log file is locked or has been held open, log messages will be written to the alternate log file. The system log server usually keeps the log files closed in between writes.

This system logger API uses the socloc interface (TCP only). Automatic failover of a system log server has been built into this API providing that there is another system log server available (TCP only). This API requires a minimum of one running socloc server (TCP only). A valid socloc startup file must also be present in the current directory.

This API is not coded to use the logging manager API, it uses the personal logger API for all messages.

Here is a list of functions in the system logger API library module:

- sys_log_init
- sys_log_end
- sys_log
- sys_log_nf
- sys_log_status
- sys_log_stop
- sys_log_lock
- sys_log_unlock
- sys_log_open
- sys_log_close
- sys_log_delete
- sys_log_log_off
- sys_log_log_on
- sys_log_log_status
- sys_log_service_name
- sys_log_version
- is_sys_log_active
- sys_log_console
- sys_log_get_console
- sys_log_get_active
- sys_log_trans_num
- sys_log_connect_num
- sys_log_sr_code
- sys_log_sr_char
- sys_log_failover
- sys_log_lsr_code
- sys_log_lsr_char
- sys_log_client_connect

# Module Dependencies

The following modules are required along with this module:

- ipcomm.c (TCP only)
- slogcode.c (to interpret sys_log return codes)
- sloc.c (TCP only)
- slconfig.c (TCP only)
- sliocode.c (TCP only)
- sconnect.c (TCP only)

Just make sure you compile and link this module along with the other required modules.

# Module Header Files

This module requires the header files:

- stdhead.h
- flsocket.h
- ipcomm.h (TCP only)
- sys_log.h
- socloc.h (TCP only)
- sloc.h (TCP only)
- sliocode.h (TCP only)

The header sys_log.h is automatically included from the header file enhlib.h which is automatically included from header file stdhead.h except in the case of the DOS platform which does not have a system log server or sys_log API.

# Module Functions

## sys_log_init

    Prototype  : int sys_log_init(char *apname)
    Parameters :
          Name : apname
    Description: application name

    Returns    : sys_log code

This function starts the sys_log API. Since this API uses the socloc interface, the socloc API function sloc_initialize must have already been successfully called before calling this function. After the socloc interface has been validated by calling the function sloc_is_init, the first responding system log server is found by calling the socloc function sloc_find. If the find is successful, the host name and port number of the responding system log server are loaded into the module global variables. The QNX version uses the built in nameloc service and does not require socloc. The application name parameter must contain the current application name.

## sys_log_end

    Prototype  : void sys_log_end(void)

This function will stop the sys_log API by turning off the sys_log_islog switch. The module global variables containing the system log server host name and TCP port number are also cleared.

## sys_log

    Prototype  : int sys_log(char *fmt,...)
    Parameters :
          Name : fmt
    Description: printf style format string

    Returns    : sys_log code

This function will send a request to the sys_log server to log a message. The function sys_log_init must have already been called to activate the sys_log API. It is ok to have spaces in the message. Do not use the single quote in your message as this will confuse the parser. This function automatically surrounds the message in single quotes.

## sys_log_nf

    Prototype  : int sys_log_nf(char *mes)
    Parameters :
          Name : mes
    Description: message text

    Returns    : sys_log code

This function behaves just like sys_log except that the function does not allow a variable number of arguments.

## sys_log_status

    Prototype  : int sys_log_status(void)
    Returns    : SYS_LOG_OK upon success, another sys_log code otherwise

This function will send the SYS_LOG_STATUS request to the system log server.

## sys_log_stop

    Prototype  : int sys_log_stop(char *paswd)
    Parameters :
          Name : passwd
    Description: password string

    Returns    : SYS_LOG_TERM if successful, sys_log code otherwise

This function will halt the system log server. The server password is expected in the password string.

## sys_log_lock

    Prototype  : int sys_log_lock(void)
    Returns    : SYS_LOG_OK if successful, sys_log code otherwise

This function will lock the system log server primary log file. Once the primary log file is locked, no other changes will be accepted by the system log server. The log server will record all log messages to the alternate log file while the primary log file is locked. It is the callers responsibility to unlock the primary log file once you are done.

## sys_log_unlock

    Prototype  : int sys_log_unlock(void)
    Returns    : SYS_LOG_OK if successful, sys_log code otherwise

This function will unlock the system log server primary log file. The primary log file must have already been locked.

## sys_log_open

    Prototype  : int sys_log_open(void)
    Returns    : SYS_LOG_OK if successful, sys_log code otherwise

This function will open the system log server primary log file. This log file will remain open until it is closed by the caller using the function sys_log_close. While the system log server primary log file is left open, all subsequent messages sent to the log server will be written to the system log server alternate log file.

## sys_log_close

    Prototype  : int sys_log_close(void)
    Returns    : SYS_LOG_OK if successful, sys_log code otherwise

This function will close the system log server primary log file. The primary log file must have been already opened by calling the function sys_log_open.

## sys_log_delete

    Prototype  : int sys_log_delete(char *paswd)
    Parameters :
          Name : passwd
    Description: password string

    Returns    : SYS_LOG_OK if successful, sys_log code otherwise

This function will delete the system log server primary log file. The server password is required in the password string.

## sys_log_log_off

    Prototype  : int sys_log_log_off(void)
    Returns    : SYS_LOG_NOT_IMPLEMENTED

This function normally would turn logging off. The function is present only for common code compliance and does not make sense in this API. For this reason, this function always returns SYS_LOG_NOT_IMPLEMENTED.

## sys_log_log_on

    Prototype  : int sys_log_log_on(char *lfname)
    Parameters :
          Name : lfname
    Description: log file name

    Returns    : SYS_LOG_NOT_IMPLEMENTED

This function normally would turn logging on. The function is present only for common code compliance and does not make sense in this API. For this reason, this function always returns SYS_LOG_NOT_IMPLEMENTED.

## sys_log_log_status

    Prototype  : int sys_log_log_status(int *lflag, char *lfname)
    Parameters :
         Name : lflag
    Description: returned log flag

          Name : lfname
    Description: returned primary and alternate log file names

    Returns    : SYS_LOG_OK if successful, sys_log code otherwise

This function will obtain and return the current log flag, primary log file name and alternate log file name from the currently connected system log server. The log file names (primary and alternate) are placed into lfname in comma delimited format. Lfname must already be allocated to sufficient size by the caller.

## sys_log_service_name

    Prototype  : int sys_log_service_name(char *sname)
    Parameters :
          Name : sname
    Description: returned service name

    Returns    : SYS_LOG_OK if successful, sys_log code otherwise

This function will obtain and return the service name of the currently connected system log server. This service name is always sys_log (/sys_log for QNX). The parameter sname must already be allocated to sufficient size for the returned service name.

## sys_log_version

    Prototype  : int sys_log_version(char *ver)
    Parameters :
         Name : ver
    Description: returned version string

    Returns    : SYS_LOG_OK if successful, sys_log code otherwise

This function will obtain and return the version string of the currently connected system log server. The parameter ver must already be allocated to sufficient size for the returned version string.

## is_sys_log_active

    Prototype  : int is_sys_log_active(void)
    Returns    : log switch sys_log_islog

This function determines whether the system logger API is active by returning the value of the sys_log_islog flag.

## sys_log_console

    Prototype  : void sys_log_console(int flag)
    Parameters :
          Name : flag
    Description: logging flag

This function will set whether logging output will be sent to the console/screen. Output will be turned off if the logging flag is zero. Any other value will cause the output to be turned on. Note that console output is off by default.

## sys_log_get_console

    Prototype  : int sys_log_get_console(void)
    Returns    : console output flag

This function will obtain and return the console output flag.

## sys_log_get_active

    Prototype  : void sys_log_get_active(char *hname, int *port)
    Parameters :
          Name : hname
    Description: returned host name

          Name : port
    Description: returned TCP port number

This function will obtain and return the host name and TCP port number of the currently connected system log server. The parameter hname must already be allocated to sufficient size for the returned host name. This function applies to the TCP IPC method only.

## sys_log_trans_num

    Prototype   : int sys_log_trans_num(long *transout)
    Parameters  :
          Name  : transout
    Description : returned transaction count

    Returns    : SYS_LOG_OK if successful, sys_log code otherwise

This function will get the system log server transaction count. Upon success the transaction count will be loaded into the returned transaction count.

## sys_log_connect_num

    Prototype   : int sys_log_connect_num(int *connectout)
    Parameters  :
          Name  : connectout
    Description : returned connection count

    Returns    : SYS_LOG_OK if successful, sys_log code otherwise

This function will get the system log server connection count. Upon success the connection count will be loaded into the returned connection count.

# Module Private Functions

## sys_log_sr_code

    Prototype  : static int sys_log_sr_code(int typ, char *parm)
    Parameters :
          Name : typ
    Description: system log send code

          Name : parm
    Description: command parameters

    Returns    : SYS_LOG_OK if successful, sys_log code otherwise

This private function will attempt to send a request to a system log server that returns only a reply code. This function makes sure the system log interface is active and sends the command using the function sys_log_lsr_code. The send command is in a loop detecting a socket error which indicates a failure in the currently connected system log server. If a socket error is detected, the function sys_log_failover is called to select another system log server. (TCP only)

## sys_log_sr_char

    Prototype  : static int sys_log_sr_char(int typ, char *parm, char *cout)
    Parameters :
          Name : typ
    Description: system log send code

          Name : parm
    Description: command parameters

          Name : cout
    Description: returned string value

    Returns    : SYS_LOG_OK if successful, sys_log code otherwise

This private function will attempt to send a request to a system log server that returns a string in addition to the reply code. This function makes sure the system log interface is active and sends the command using the function sys_log_lsr_char. The send command is in a loop detecting a socket error which indicates a failure in the currently connected system log server. If a socket error is detected, the function sys_log_failover is called to select another system log server (TCP only).

## sys_log_lsr_code

    Prototype  : static int sys_log_lsr_code(int typ, char *parm)
    Parameters :
          Name : typ
    Description: system log send code

          Name : parm
    Description: command parameters

    Returns    : SYS_LOG_OK if successful, sys_log code otherwise

This private function will attempt to send a request to a system log server that returns only a reply code. The function calls sys_log_client_connect to establish a connection with the current system log server (TCP only).

## sys_log_lsr_char

    Prototype  : static int sys_log_lsr_char(int typ, char *parm, char *cout)
    Parameters :
          Name : typ
    Description: system log send code

          Name : parm
    Description: command parameters

          Name : cout
    Description: returned string value

    Returns    : SYS_LOG_OK if successful, sys_log code otherwise

This private function will attempt to send a request to a system log server that returns a string in addition to the reply code. The function calls sys_log_client_connect to establish a connection with the current system log server (TCP only).

## sys_log_failover

    Prototype  : static int sys_log_failover(int dflag)
    Parameters :
          Name : dflag
    Description: delete system log server flag

    Returns    : SYS_LOG_OK if successful, sys_log code otherwise

This private function will delete the current system log server entry registered with socloc using the function sloc_delete. This deletion will only be attempted when dflag is high. Another responding system log server will try to be found by calling the function sloc_find. If the find is successful, the host name and TCP port number of the new responding system log server will be loaded into the module global variables. This function applies to the TCP IPC method only.

## sys_log_client_connect

    Prototype  : static int sys_log_client_connect(void)
    Returns    : TRUE upon success, FALSE otherwise

This private function will attempt to connect to the current system log server. This function applies to the TCP IPC method only.

Goto Top | GPL Software Overview | GPL Library
Future Lab Home | Contact Webmaster | Feedback

Copyright © 1999-2006 Future Lab, Last Updated Jun 30, 2006