Updated: 11 December 1998 |
OpenVMS Alpha Galaxy Guide
Previous | Contents |
Clear System Event
Clear Event does not allow you to specify a handle and an event. You must pass a zero as one of these parameters. You can either clear by handle or request that all events for the user be cleared.
Removes one or more notification requests previously established by a call to SYS$SET_SYSTEM_EVENT.
Format:
SYS$CLEAR_SYSTEM_EVENT [handle], [acmode], event
C Prototype:
int sys$clear_system_event (struct _generic_64 * handle, unsigned int acmode, unsigned int event);
Arguments:
handle
OpenVMS usage: | identifier |
type: | quadword (unsigned) |
access: | read only |
mechanism: | by reference |
Identification of the AST request to be cleared. The handle argument uniquely identifies the request and is returned when the $SET_SYSTEM_EVENT service is called. The handle argument may be omitted by specifying a zero address.
acmode
OpenVMS usage: | access_mode |
type: | longword (unsigned ) |
access: | read only |
mechanism: | by value |
Access mode of the system event to be cleared. The acmode argument is a longword containing the access mode. The value of the access mode is maximized with the access mode of the caller.
event
OpenVMS usage: | event_code |
type: | longword (unsigned) |
access: | read only |
mechanism: | by value |
The event argument is a value indicating the type of system event to be cleared. SYSEVT$C_ALL_EVENTS may be specified to clear all event types.
Description
The Clear System Event service removes one or more event types or notification objects previously established by a call to the $SET_SYSTEM_EVENT service.
A valid request specifies either the handle for a specific notification request, or is a wildcard clear of all notification objects whose is access mode is greater than or equal to acmode .
If the handle argument is specified, caller's access mode must be less than or equal to the access mode of the object to be cleared.
If SYSEVT$C_ALL_EVENTS is specified, or the set of events enabled for the object(s) becomes empty, the notification object is deleted.
Required Access or Privileges
None
Required Quota
None
Related Services
$SET_SYSTEM_EVENT
Condition Values Returned
SS$_NORMAL | The service completed successfully. |
SS$_ACCVIO | The service cannot access the location specified by the handle. |
SS$_BADPARAM | One of more arguments has an invalid value, such as an invalid handle. |
SS$_NOSUCHOBJ | No request was found that matches the description supplied |
A shared memory global section maps some amount of
memory that can be accessed on all instances in a sharing community.
These objects are also called Galaxywide shared
sections. Each such object has a name, a version, and
protection characteristics.
16.1 Using Shared Memory
Application programs access shared memory by mapping Galaxywide shared sections. The programming model is the same as for standard OpenVMS global sections; that is you create, map, unmap, and delete them on each instance where you want to use them. Some shared memory global section characteristics are:
From a programmer's point of view, shared memory global sections are similar to memory resident sections. You use the same system services to create Galaxywide shared sections that you would use to create memory resident sections. Setting the flag SEC$M_SHMGS lets the service operate on a shared memory global section.
In contrast to memory resident sections, the Reserved Memory Registry
is not used to allocate space for Galaxywide sections. Shared memory is
not used for normal OpenVMS paging operations and therefore does not
need to be reserved.
16.2 System Services
The following sections describe new and changed system services that
support shared memory global sections.
16.2.1 Enhanced Services
The following system services have been enhanced to recognize the new shared memory global section flag SEC$M_SHMGS:
The following system services have enhanced to work with shared memory, but no interfaces were changed:
The new section flag SEC$M_READ_ONLY_SHPT is recognized by the SYS$CREATE_GDZRO and SYS$CRMPSC_GDZRO_64 services. When this bit is set, it directs the system to create shared page tables for the section that allow read access only. This feature is particularly useful in an environment where a memory resident or Galaxy shared section is used by many readers but only a single writer.
When you map a Galaxy shared section or a memory resident section that has an associated shared page table section, you have the following options for accessing data:
Shared page tables | Read only | Read and Write |
---|---|---|
None created |
Do not set the SEC$M_WRT flag in the map request.
Private page tables will always be used, even if you are specifying a shared page table region into which to map the section. |
Set the SEC$M_WRT flag in the map request.
Private page tables will always be used, even if you are specifying a shared page table region into which to map the section. |
Write access |
Do not set the SEC$M_WRT flag in the map request.
Ensure that private page tables will be used. Do not specify a shared page table region into which to map the section. If you do, the error status SS$_IVSECFLG is returned. |
Set the SEC$M_WRT flag in the map request.
The shared page table section will be used for mapping if you specify a shared page table region into which to map the section. |
Read access | Do not set the SEC$M_WRT flag in the map request. The shared page table section will be used for mapping if you specify a shared page table region into which to map the section. | Set the SEC$M_WRT flag in the map request. Ensure that private page tables will be used. Do not specify a shared page table region into which to map the section. If you do the error status SS$_IVSECFLG is returned. |
Shared page tables for Galaxy shared sections are also implemented as Galaxy shared sections. This implies that they allow either read access only on all OpenVMS instances connected to this section or read and write access on all instances. The setting of the SEC$M_READ_ONLY_SHPT flag as requested by the first instance to create the section is used on all instances. Using the SYS$CRMPSC_GDZRO_64 service always implies that the SEC$M_WRT flag is set and that you want to map the section for writing. If you want to use this service to create a section with shared page tables for read only access, you must use private page tables and you cannot specify a shared page table region into which to map the section. |
The SHMEM privilege is required to create an object in Galaxy shared memory. The right to map to an existing section is controlled through normal access control mechanisms. SHMEM is not needed to map an existing section. Note that the VMS$MEM_RESIDENT_USER identifier, which is needed to create an ordinary memory resident section, is not required for Galaxywide sections.
Creating and mapping Galaxywide memory sections is accomplished through the same services used to create memory resident sections. The following services now recognize the SEC$M_SHMGS flag:
SYS$CREATE_GDZRO and SYS$CRMPSC_GDZRO_64 can also return new status codes. To be supplied---more details about these:
SS$_INV_SHMEM | Shared memory is not valid. |
SS$_INSFRPGS | Insufficient free shared pages or private pages. |
SS$_NOBREAK | A Galaxy lock is held by another node and was not broken. |
SS$_LOCK_TIMEOUT | A Galaxy lock timed out. |
$ INSTALL LIST/GLOBAL and $ SHOW MEMORY also know about glaxywide sections. To be supplied---some additional documentation about these.
Galaxywide sections are using their own name space. Just as you could always use the same name to identify system global sections and group global sections for various owner UICs, you can now also have Galaxywide system global sections and Galaxywide group global sections all with the same name.
Galaxywide sections also have their own security classes:
These security classes are used with the $GET_SECURITY, $SET_SECURITY system services, and the SET/SHOW SECURITY DCL commands:
These new security classes are only valid in a Galaxy environment. They are not recognized on a non-galaxy node.
You can only retrieve and affect security attributes of Galaxywide global sections if they exist on your sharing instance.
Audit messages for Galaxywide sections look like this:
%%%%%%%%% OPCOM 20-MAR-1998 10:44:43.71 %%%%%%%% (from node GLX1 at 20-MAR-1998 10:44:43.85) Message from user AUDIT$SERVER on GLX1 Security alarm (SECURITY) on GLX1, system id: 19955 Auditable event: Object creation Event information: global section map request Event time: 20-MAR-1998 10:44:43.84 PID: 2040011A Process name: ANDY Username: ANDY Process owner: [ANDY] Terminal name: RTA1: Image name: MILKY$DKA100:[ANDY]SHM_MAP.EXE;1 Object class name: GLXGRP_GLOBAL_SECTION Object name: [47]WAY____D99DDB03_0$MY_SECTION Secondary object name: <Galaxywide global section> Access requested: READ,WRITE Deaccess key: 8450C610 Status: %SYSTEM-S-CREATED, file or section did not exist; has been created |
Note the "Object name" record: the object name displayed here uniquely identifies the section in the OpenVMS Galaxy. The fields are as follows:
[47] | (only for group global sections) identifies the UIC group of the section creator. |
WAY____D99DDB03_0$ | An identifier for the sharing community. |
MY_SECTION | The name of the section as specified by the user. |
The user can only specify the section name and class for requests to set or show the security profile. The UIC is always obtained from the current process and the community identifier is obtained from the community in which the process executes.
The output for a Galaxywide system global section differs only in the fields "Object class name" and "Objects name". The object name for this type of section does not include a group identification field:
Object class name: | GLXSYS_GLOBAL_SECTION |
Object name: | WAY____D99DDB03_0$SYSTEM_SECTION |
Security attributes for a Galaxywide memory section must appear identical to a process no matter on what instance it is executing. This can be achieved by having all instances participating in this sharing community also participate in a "homogeneous" OpenVMS Cluster where all nodes share the security related files:
In particular, automatic propagation of protection changes to a Galaxywide section requires that the same physical file (VMS$OBJECTS.DAT) is used by all sharing instances. If your installation does not share these files throughout the Galaxy, the creator of a Galaxywide shared section must ensure that the section has the same security attributes on each instances. This may require manual intervention. |
17.1 SYS$CPU_TRANSITION
On Alpha systems, changes the current processing state of a CPU in the
configure set of the current system or an unassigned CPU in an OpenVMS
Galaxy configuration. This service completes asynchronously. For
synchronous completion, use the $CPU_TRANSITIONW service.
This service accepts 64-bit addresses. Parameter and bit definitions are resolved in $CSTDEF in the appropriate STARLET library.
SYS$CPU_TRANSITION tran_code, cpu_id, nodename, node_id, flags, efn, iosb, astadr_64, astprm_64
tran_code
OpenVMS usage: | longword |
type: | longword (unsigned) |
access: | read only |
mechanism: | by value |
Identifier specifying the type of state change to be initiated on the target CPU. The tran_code argument is a longword containing one of the following values:
Symbolic Name | Description |
---|---|
CST$K_CPU_STOP | The target CPU is to be removed from the active set and halted into console mode. It remains in the configure set of the current partition. |
CST$K_CPU_MIGRATE | The target CPU is removed from the configure set of the local partition and the console is requested to add it to the configure set of the partition specified in node_id. If the CPU is currently in the active set, it is automatically brought to console mode through the CST$K_CPU_STOP function first. |
CST$K_CPU_START | The target CPU is requested to exit console mode and join the active set of the current partition. The CPU must already be part of the configure set. |
CST$K_CPU_FAILOVER | The CPU is assigned a default target partition where it will automatically migrate on system failure. This assignment persists until it is superseded. To remove an assignment or partition name, the current partition ID should be specified. |
cpu_id
OpenVMS usage: | longword |
type: | longword (unsigned) |
access: | read only |
mechanism: | by value |
Identifier of the CPU whose state is to be modified. The cpu_id argument is a longword number in the supported range of individual CPUs from 0 to SYI$_MAX_CPUS - 1. In a Galaxy, this CPU must be in the configure set of the local partition or not assigned to any other partitions. The symbolic values, CST$K_ANY_LOCAL_CPU can be used in certain types of transitions to allow the next available processor of the appropriate type be used instead of a specific one.
node_id
OpenVMS usage: | longword |
type: | longword (unsigned) |
access: | read only |
mechanism: | by value |
Identifier of the target Galaxy partition in CST$K_CPU_ASSIGN, CST$K_CPU_FAILOVER, or CST$K_CPU_MIGRATE transition. The node_id argument is a longword containing a number in the supported range of IDs provided by the console for the current hardware platform. If the nodename parameter is specified, node_id is ignored.
flags
OpenVMS usage: | longword_mask |
type: | longword (unsigned) |
access: | read only |
mechanism: | by value |
Options selected for the CPU state transition. The flags argument is a longword bit vector wherein a bit corresponds to an option. Only the bits specified below are used; the remainder of the longword bits are reserved and must be 0.
Each option (bit) has a symbolic name. The flags argument is constructed by performing a logical OR operation using the symbolic names of the following options:
Symbolic Name | Description |
---|---|
CST$V_CPU_DEFAULT_CAPABILITIES | At the completion of the transition, the CPU's user capabilities are set back to the default system value. If this option is not specified, modified user capabilities are maintained across STOP and START transitions as long as the CPU remains in the local partition configure set. |
CST$V_CPU_ALLOW_ORPHANS | The transition is to be allowed even though it will leave at least one thread in the system unable to execute on any CPU in the active set. |
efn
OpenVMS usage: | ef_number |
type: | longword (unsigned) |
access: | read only |
mechanism: | by value |
The event flag to be set when the state transition attempt has completed. The efn argument is a longword specifying the number of the event flag; however, this service only uses the low-order byte.
When you invoke $CPU_TRANSITION, the specified event flag is cleared; when the operation is complete, the event flag is set.
iosb
OpenVMS usage: | io_status_area |
type: | IOSB structure |
access: | write only |
mechanism: | by 32-bit or 64-bit reference |
The I/O status area to receive the final completion status of the transition operation. The iosb argument is the 32-bit or 64-bit virtual address of the I/O status area. The I/O status area structure is 32 bytes in length; its definition can be found in $IOSBDEF in STARLET.MLB for macro and in the file IOSBDEF.H in SYS$STARLET_C.TLB for C.
When you call $CPU_TRANSITION, the I/O status area is cleared. After the transition operation is complete, the block is modified as follows:
Symbolic Name | Description |
---|---|
iosb$w_status | The first word contains the condition value return, indicating the final completion status of the operation. |
The first bit in the second word of the IOSB is set only if an error occurred during the operation; the remaining bits are zeroes. |
astadr_64
OpenVMS usage: | ast_procedure |
type: | procedure value |
access: | call without stack unwinding |
mechanism: | by 32-bit or 64-bit reference |
The AST routine to be executed when the requested transition attempt has completed. The astadr_64 argument is the 32-bit or 64-bit virtual address of this routine. If you specify the astadr_64 argument, the AST routine executes at the access mode from which the state transition was requested.
astprm_64
OpenVMS usage: | user_arg |
type: | quadword |
access: | read only |
mechanism: | by value |
The quadword AST parameter to be passed to the AST routine.
The state transition in tran_id is requested for the target cpu_id.
A CPU currently in the active set can transition:
A CPU in the configure set can transition:
CPU state transition is a two-phase operation in the OpenVMS scheduling model. This service initiates the request in the process context of the caller and returns the setup status in the service condition value. Phase 2 proceeds asynchronously; the efn and iosbarguments can be used to indicate the completion of the transition through the standard wait system services. Additional notification of the completion can be made through the OpenVMS AST mechanisms using a routine specified in astadr_64 and a user-supplied parameter in astprm_64.
The caller must have the CMKRNL privilege to call SYS$CPU_TRANSITION to modify CPU states.
Related Services
$CPU_TRANSITIONW
SS$_NORMAL | The service completed successfully |
SS$_BADPARAM | One of more arguments has an invalid value or the specified CPU is not in the configuration |
SS$_ACCVIO | The service cannot access the locations specified by one or more arguments |
SS$_NOCMKRNL | Caller does not have CMKRNL privilege needed to complete operation |
SS$_INSFARG | Fewer than the required number of arguments were specified or no operation was specified |
SS$_TOO_MANY_ARGS | More arguments were specified than are allowed by the service |
SS$_INVCOMPID | The target gNode ID is not valid in this configuration |
SS$_CPUNOTACT | The specified CPU is not part of the current partitions's active set |
SS$_NOSUCHCPU | The specified CPU does not exist in the current hardware configuration, or is not in the configure set of the local partition |
SS$_CPUSTARTD | The specified CPU is already in the local active set, or is in the process of joining it |
SS$_CPUSTOPPING | The specified CPU is already STOPPED or in the processing of leaving the active set |
Previous | Next | Contents |
Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal |
6512PRO_009.HTML
|