A network event requires administrative assistance
The functions in the Alert category provide a method for notifying network service programs and applications of events as they occur.
The Alert category functions, data types, structures, and constants are defined in the netcons.h, neterr.h, and alert.h header files. A source program can access these definitions by defining the constants INCL_NETERRORS and INCL_NETALERT, and including the lan.h master header file.
|
Function |
Description |
|
Notifies network service programs and applications registered in the alert table that a specified event occurred. |
|
|
Registers network service programs and applications to be notified of a specified type of network event. |
|
|
Removes registered network service programs and applications from an alert table. |
An event is a particular instance of a process or state of hardware defined by an application or by the Advanced Server software. Advanced Server sends out an alert, in the form of a message or the resetting of a semaphore, when certain events occur. Other programs, network services, or internal network components use the NetAlertRaise function to raise an alert, notifying various applications or users when a particular type of event occurs.
The alert.h include file defines the following classes of events for which alerts are sent out:
A network event requires administrative assistance
An entry is added to an error log file
A user or application receives a broadcast message
A print job completes
A user accesses or uses certain applications or resources. Other classes of alerts can be defined for network applications as needed. For example, if an application on a server routinely writes large amounts of data to a disk drive, running the risk of filling the disk, you might want the event "no free disk space" to trigger an alert that notifies the application to pause or kill the process that is filling the disk.
An application or network service, also known as a client, registers to be notified of an event (or class of events) by calling the NetAlertStart function.
The client can be registered for several types of events, by calling the NetAlertStart function multiple times. Each registration adds an entry to an alert table.
An application or network service program receives alert messages through the use of a mailslot (registered as \mailslot\name). If a program requires detailed information about an event, it should be registered as a mailslot.
An application or network service program can be registered for one type of event or for several types by calling the NetAlertStart function multiple times. To discontinue alerts for a registered application or network service program, use NetAlertStop to remove its entry in the alert table for the particular class of event.
The following sample code provides a function that defines an alert handler to receive notification of printing events and to then pass the information to a user:
print_job_alert_handler () {
DosMakeMailslot (); /* create a mailslot to
receive alert information */
NetAlertStart (); /* start sending print information to mailslot */
while (still_running ()){
DosReadMailslot (); /* if the mailslot contains
information,read mailslot */
notify_user (); /* give information to user */
}
NetAlertStop (); /* stop sending information
about printing to the mailslot */
DosDeleteMailslot (); /* clean up the mailslot */
return; /* exit handler */
}
An application registered as a mailslot client receives information about each class of event for which it is registered. This information consists of a fixed-length header followed by variable-length information specific to the type of event, as defined in the alert.h file.
The fixed-length header contains the following data:
/* Standard event data structure */
struct std_alert {
long alrt_timestamp;
char alrt_eventname[EVLEN+1];
char alrt_pad1;
char alrt_servicename[LM20 SNLEN+1];
};
Within this structure, the parameters are defined as follows:
alrt_timestamp tells the time and date of the event.
alrt_eventname is an ASCIIZ string specifying the alert class (type of event).
alrt_pad1 word-aligns data structure components.
alrt_servicename is an ASCIIZ string specifying which application is raising the alert.
The alert.h include file contains data structures for the following predefined alert classes:
Print Request Completed
Network Message Received
Entry Made to Error Log File
Notify Administrator of Network Event
Notify User of an Event
The data structures define only the fixed-length part of the information, not the ASCIIZ strings that follow some of the structures. The following section contains descriptions of each of the predefined alert classes.
The print_other_info data structure has the following format:
struct print_other_info {
short alrtpr_jobid;
short alrtpr_status;
long alrtpr_submitted;
long alrtpr_size;
};
/* followed by consecutive ASCIIZ strings
char computername[];
char username[];
char queuename[];
char destname[];
char status_string[];
*/
Within this structure, the parameters are defined as follows:
alrtpr_jobid is the print job’s identification number.
alrtpr_status tells the status of the print job.
alrtpr_submitted is a time stamp telling when the job was submitted.
alrtpr_size tells the size (in bytes) of the print job.
computername is an ASCIIZ string specifying which client or server submitted the print job.
username is an ASCIIZ string specifying which user requested the job.
queuename is an ASCIIZ string specifying which queue handled the job.
destname is an ASCIIZ string specifying which printer handled the job.
status_string is information that the print processor returns. This string corresponds to status_string in the print job data structure for the print job. For more information, see Print Job Category.
No data structure is defined; however, the text from the received message is in the following format:
char msg_text [ ];
Within this structure, msg_text is an ASCIIZ string message text.
The errlog_other_info data structure has the following format:
struct errlog_other_info {
short alrter_errcode;
long alrter_offset;
};
Within this structure, the parameters are defined as follows:
alrter_errcode is the return code that was logged.
alrter_offset is the offset for the new entry in the error log file.
The admin_other_info data structure has the following format:
struct admin_other_info {
short alrtad_errcode;
short alrtad_numstrings;
/* followed by 0-9 consecutive ASCIIZ strings
char mergestrings [ ];
*/
};
Within this structure, the parameters are defined as follows:
alrtad_errcode is the return code for a new entry in the message log.
alrtad_numstrings tells how many (0-9) consecutive ASCIIZ strings mergestrings contains.
mergestrings is a series of consecutive ASCIIZ strings that comprise the error message indicated by alrtad_errcode.
The user_other_info data structure has the following format:
struct user_other_info {
short alrtus_errcode;
short alrtus_numstrings;
/* followed by the consecutive ASCIIZ strings
char mergestrings [];
char username[];
char computername[];
*/
};
Within this structure, the parameters are defined as follows:
alrtus_errcode is the return code for the new message in the message log file.
alrtus_numstrings tells how many (0-9) consecutive ASCIIZ strings mergestrings contains.
mergestrings is a series of consecutive ASCIIZ strings that comprise the error message indicated by alrtus_errcode .
username is the user name of the user or application that is being affected by the alert.
computername is the name of the computer that the user or application is accessing.
The alert.h include file contains macros to simplify access to the variable-length fields in the alert structure, as follows:
|
Macro |
Task |
|
ALERT_OTHER_INFO |
When given a pointer to the start of the std_alert data structure, the ALERT_OTHER_INFO macro resolves to a pointer to the variable-length part of the alert message (the information specific to the alert class). |
|
ALERT_VAR_DATA |
Works with the data structures defined in the alert.h file. Given a pointer to the beginning address of the data structure, ALERT_VAR_DATA returns a pointer to the first variable-length ASCIIZ string. |
