14.1 $SET_SYSTEM_EVENT
Set System Event
Establishes a request for notification when an OpenVMS
system event occurs.
Format:
SYS$SET_SYSTEM_EVENT (event ,astadr ,astprm, acmode,
flags, handle)
C Prototype:
int sys$set_system_event (unsigned int event, void
(*astadr)(_ _unknown_params), int astprm, unsigned int
acmode, unsigned int flags, struct _generic_64 *handle;
Arguments:
event
OpenVMS event_code
usage:
type: longword (unsigned)
access: read only
mechanism: by value
Event code indicating the type of system event for which
an AST is to be delivered. The event argument is a value
indicating which type of event is of interest.
Each event type has a symbolic name. The $SYSEVTDEF
macro defines the following symbolic names.
Symbolic Name Description
SYSEVT$C_ADD_MEMBER One or more OpenVMS
instances have joined
the OpenVMS Galaxy
sharing community.
SYSEVT$C_DEL_MEMBER One or more OpenVMS
instances have left
the OpenVMS Galaxy
sharing community.
SYSEVT$C_ADD_ACTIVE_CPU One or more proces-
sors have become active
within this OpenVMS
instance.
SYSEVT$C_DEL_ ACTIVE_CPU One or more processors
have become inactive
within this OpenVMS
instance
SYSEVT$C_ADD_CONFIG_CPU One or more proces-
sors have become active
within this OpenVMS
instance.
SYSEVT$C_DEL_CONFIG_CPU One or more processors
have become inactive
within this OpenVMS
instance.
astadr
OpenVMS usage: ast_procedure
type: procedure value
access: call without stack unwinding
mechanism: by 32-bit or 64-bit reference
Notification AST routine to receive control after a change in
OpenVMS system configuration occurs.
astprm
OpenVMS usage: user_arg
type: quadword
access: read only
mechanism: by value
The quadword AST parameter to be passed to the AST
routine.
acmode
OpenVMS usage: access_mode
type: longword (unsigned )
access: read only
mechanism: by value
Access mode at which the system event AST is to execute.
The acmode argument is a longword containing the access
mode.
Each access mode has a symbolic name. The $PSLDEF
macro defines the following symbols for the four access
modes.
Symbolic Name Description
PSL$C_KERNEL Kernel
PSL$C_EXEC Executive
PSL$C_SUPER Supervisor
PSL$C_USER User
The value of the access mode is maximized with the access
mode of the caller.
flags
Defined in SYSEVTDEF.
SYSEVT$M_REPEAT_ When this flag is set, event notification
NOTIFY will be repeated.
handle
OpenVMS usage: handle
type: quadword (unsigned)
access: read/write
mechanism: by reference
The virtual address of a naturally aligned quadword for the
event handle.
Description
The Set System Event service establishes a request for noti-
fication when a system event occurs. It may create a new
system event notification object, add an event to a (new or
existing) object, and enable notification on a (new or existing)
object.
If the handle specified is zero, a new system notification
request object is created, and a handle for the new object is
returned.
If theevent specified is non-zero, that event is added to the
set of events which trigger notification on the notification
object.
The service will verify that the input parameters spec-
ify a valid request and enable the object for notification.
Notification is accomplished by AST delivery. After the AST
has been delivered, notification must again be enable on the
object before another notification (AST delivery) can occur if
flag is not set.
Errors will be returned in the following cases:
* If quotas are exceeded, an error will be returned. It is
important to note that this routine will return an er-
ror and will not retry an attempt to get quota if quota is
exhausted on the first attempt.
* See the Condition Values Returned section for types of
errors that can be returned.
* If theastadr argument is omitted, and a new notifi-
cation object is being created, SS$_BADPARAM will be
returned.
* If theevent argument is incorrectly specified, SS$_
BADPARAM will be returned.
* If the access mode parameter is more privileged than the
mode of the caller, the mode of the caller will be used.
* If specified, thehandle argument must be writeable
from the mode of the caller. SS$_ACCVIO is returned if
this is not the case.
Required Privileges
None.
Required Quota
ASTLM.
Related Services
$CLEAR_SYSTEM_EVENT
Condition Values Returned
SS$_NORMAL The service completed successfully.
SS$_ACCVIO The service cannot access the locations
specified by one or more arguments.
SS$_BADPARAM One of more arguments has an invalid
value.
SS$_EXASTLM The process exceeded its quota for
outstanding ASTs.
SS$_INSFMEM The system dynamic memory is insuf-
ficient to complete the service.