ZCOMLOG (3X)

NAME

zcomlog - Add a message to the ZCOM log file

SYNOPSIS

#include  <zcom/zcomsys.h>
#include  <zcom/zcomcall.h> /* if compiled with ANSI C (recommended) */
 
void zcomlog (error, msgno, narg [, desc, arg])
 
uint32  error;
int32   msgno;
uint8   narg;
uint32  desc;
uint32  arg;

DESCRIPTION

Routine zcomlog creates a log record and passes it to the ZCOM message log system, where the logged messages will be retrieved and processed by the ZMLOG program. Before calling this routine, zcomlname(3X) should be called to set up the logging program name for all subsequent log records.

The log record created consists of the program name as specified in the preceding zcomlname call, the message number msgno and the associated arguments arg. This routine has a variable number of arguments: the call argument pair "desc, arg" repeats for the number of times specified by narg.

The libraries libzcom_c.a and libpthread.a must be linked into the calling program by giving the options "-lzcom_c -lpthread" to cc(1) or ld(1).

Threads Considerations

This routine may be called from a multi-threaded application using the POSIX (1003.1c) kernel threads API package. This routine has the following characteristics when called by a multi-threaded application:

cancellation point	Thread cancellation can occur when a thread calls this routine.
async-cancel unsafe	The calling thread's cancelability type must be PTHREAD_CANCEL_DEFERRED if cancellation is enabled.
async-signal unsafe	It cannot be called from a signal handler.
fork unsafe	It cannot be called by a child process after fork(2) but before exec(2).

See the NOTES section for more information on using this routine in a multi-threaded application.

PARAMETERS

error	Error code to be logged (unsigned int). The error code is displayed as a 5-digit unsigned value (ranges from 00000 to 99999) in the error message log file.
msgno	ID number of the message to be logged (signed int).
narg	Number of arguments to be logged with the message (positive int).
desc	Argument descriptor used to describe the "type" of the argument which follows. The values of this parameter may be one of the following:
	ZCOM_AT_CHAR ZCOM_AT_UCHAR ZCOM_AT_SINT ZCOM_AT_USINT ZCOM_AT_INT ZCOM_AT_STR ZCOM_AT_ERRNO ZCOM_AT_ZERROR ZCOM_AT_ZSTAT ZCOM_AT_XSTAT	- char - unsigned char - short int - unsigned short int - int - char * - int (UNIX error code, usually errno) UNIX error string will be logged - int (ZCOM error code) ZCOM error string will be logged - int (ZCOM status code) ZCOM status string will be logged - int (ZCOM X.25 status code) ZCOM X.25 status string will be logged
arg	Argument value to insert into the message to be logged. Note that the argument's type must match the type specified in the desc parameter. Each argument will be substituted into the message text string using printf.

RETURN VALUE

Routine zcomlog has no return value.

NOTES

The ZMLOG program retrieves the unique message test using the logging program name and message number. By default, the message tests of all log messages are retrieved from the message file default.msg in /opt/acc/msg. If the environment variable "LANG" is defined, the message text is retrieved from the message file $LANG.msg instead. In case it does not exist, the default.msg file is used. This allows support for multiple message file in different languages.
Before calling this routine, zcomlname(3X) should be called to set up the logging program name for all subsequent log records.
In a multi-threaded application, zcomlname is to be called only once by any one of the threads. It sets up the logging program name for the subsequent calls to zcomlog for all threads. If it is called again, the new program name is effective for the subsequent log messages.

EXAMPLE

#include     <zcom/zcomsys.h>
#include     <zcom/zcomcall.h> 
 
uint32    error;
int32     msgno;
uint32    desc;
uint32    arg;
char      p1;
int       p2;
 
error    = 1730;
msgno    = 150; /* Msg text = "This is an error. P1 = %c P2 = %d". */
p1       = 'a';
p2       = 37;
zcomlog (error, msgno, 2, ZCOM_AT_CHAR, p1, ZCOM_AT_INT, p2);

FILES

/opt/acc/include/zcom/zcomsys.h	ZCOM subsystem general include file, containing data types, data structures, constants, error codes, masks, etc. Note that this must be the first include file before any other ZCOM include files.
/opt/acc/include/zcom/zcomcall.h	ZCOM routine function prototypes (requires ANSI C compilation).
/opt/acc/msg/default.msg	Master message text file.