OpenVMS Alpha Galaxy Guide

Document revision date: 19 July 1999

OpenVMS Alpha Galaxy Guide

Contents

Index

$DELETE_GALAXY_LOCK_TABLE (Alpha Only)

Deletes an OpenVMS Galaxy locktable.

Format

SYS$DELETE_GALAXY_LOCK_TABLE lcktbl_handle

C Prototype

int sys$delete_galaxy_lock_table (unsigned int *lcktbl_handle);

Arguments

lcktbl_handle

OpenVMS usage lock table handle

type longword (unsigned)

access read

mechanism input by value

The 32-bit lock table handle that identifies the table to be deleted. This value is returned by SYS$CREATE_GALAXY_LOCK_TABLE.

Description

This service deletes an OpenVMS Galaxy lock table. If there are no longer any mappers of the locktable section, the table is deleted.
Required Access or Privileges

CMKRNL, SHMEM
Required Quota

None
Related Services

$ACQUIRE_GALAXY_LOCK, $CREATE_GALAXY_LOCK_TABLE, $DELETE_GALAXY_LOCK, $DELETE_GALAXY_LOCK, $GET_GALAXY_LOCK_INFO, $GET_GALAXY_LOCK_SIZE, $RELEASE_GALAXY_LOCK

Return Values

SS$_NORMAL Normal completion.

SS$_BADPARAM Bad parameter value.

SS$_IVLOCKID Invalid lock ID.

SS$_IVLOCKTBL Invalid lock table.

SS$_NOCMKRNL Operation requires CMKRNL privilege.

SS$_NOSHMEM Operation requires SHMEM privilege.

$GET_GALAXY_LOCK_INFO (Alpha Only)

Returns "interesting" fields from the specified lock.

Format

SYS$GET_GALAXY_LOCK_INFO handle ,name ,timeout ,size ,ipl ,rank ,flags

C Prototype

int sys$get_galaxy_lock_info (unsigned __int64 lock_handle, char *name, unsigned int *timeout, unsigned int *size, unsigned int *ipl, unsigned int *rank, unsigned short int *flags);

Arguments

handle

OpenVMS usage handle for the galaxy lock

type quadword (unsigned)

access read

mechanism input by value

The 64-bit lock handle that identifies the lock on which to return information. This value is returned by SYS$CREATE_GALAXY_LOCK.
name

OpenVMS usage address

type zero-terminated string

access write

mechanism output by reference

Pointer to a buffer. This buffer must be large enough to receive the name of the lock. Lock names are zero-terminated strings with a maximum size of 16 bytes.
timeout

OpenVMS usage address

type longword (unsigned)

access write

mechanism output by reference

Pointer to a longword. The value returned is the timeout value of the lock.
size

OpenVMS usage address

type longword (unsigned)

access write

mechanism output by reference

Pointer to a longword. The value returned is the size of the lock in bytes.
ipl

OpenVMS usage address

type longword (unsigned)

access write

mechanism output by reference

Pointer to a longword. The value returned is the IPL of the lock.
rank

OpenVMS usage address

type longword (unsigned)

access write

mechanism output by reference

Pointer to a longword. The value returned is the rank of the lock.
flags

OpenVMS usage address

type word (unsigned)

access write

mechanism output by reference

Pointer to a word. The value returned is the word mask of lock flags.

Description

This service returns all "interesting" fields from the specified lock.
See the $CREATE_GALAXY_LOCK service for detailed information regarding these values.
Required Access or Privileges

Read access to lock.
Required Quota

None
Related Services

$ACQUIRE_GALAXY_LOCK, $CREATE_GALAXY_LOCK, $CREATE_GALAXY_LOCK_TABLE, $DELETE_GALAXY_LOCK, $DELETE_GALAXY_LOCK_TABLE, $GET_GALAXY_LOCK_SIZE, $RELEASE_GALAXY_LOCK

Return Values

SS$_NORMAL Normal completion.

SS$_IVLOCKID Invalid lock ID.

SS$_IVLOCKTBL Invalid lock table.

$GET_GALAXY_LOCK_SIZE (Alpha Only)

Returns the minimum and maximum size of an OpenVMS Galaxy lock.

Format

SYS$GET_GALAXY_LOCK_SIZE min_size ,max_size

C Prototype

int sys$get_galaxy_lock_size (unsigned int *min_size, unsigned int *max_size);

Arguments

min_size

OpenVMS usage address

type longword (unsigned)

access write

mechanism output by reference

Pointer to a longword. The value returned is minimum legal size of a galaxy lock structure.
max_size

OpenVMS usage address

type longword (unsigned)

access write

mechanism output by reference

Pointer to a longword. The value returned is maximum legal size of a galaxy lock structure.

Description

This service returns the minimum and maximum size of an OpenVMS Galaxy lock. If a lock is created with the maximum size, the locking services will record acquire and release information in the lock.
The lock sizes can be used to determine the value of the section_size parameter to the $CREATE_GALAXY_LOCK_TABLE service.
Required Access or Privileges

Read access to lock.
Required Quota

None
Related Services

$ACQUIRE_GALAXY_LOCK, $CREATE_GALAXY_LOCK, $CREATE_GALAXY_LOCK_TABLE, $DELETE_GALAXY_LOCK, $DELETE_GALAXY_LOCK_TABLE, $GET_GALAXY_LOCK_INFO, $RELEASE_GALAXY_LOCK

Return Values

SS$_NORMAL Normal completion.

$RELEASE_GALAXY_LOCK (Alpha Only)

Releases ownership of an OpenVMS Galaxy lock.

Format

SYS$RELEASE_GALAXY_LOCK handle

C Prototype

int sys$release_galaxy_lock (unsigned __int64 lock_handle);

Arguments

handle

OpenVMS usage galaxy lock handle

type quadword (unsigned)

access read

mechanism input by value

The 64-bit lock handle that identifies the lock to be released. This value is returned by SYS$CREATE_GALAXY_LOCK.

Description

This service releases ownership of an OpenVMS Galaxy lock. Because a Galaxy lock can be acquired multiple times by the same owner (nested ownership), the lock is not released until the ownership count goes to zero. If the lock ownership is completely released and there are other threads waiting for the lock, they are released from their wait states.
Required Access or Privileges

Write access to lock.
Required Quota

None
Related Services

$ACQUIRE_GALAXY_LOCK, $CREATE_GALAXY_LOCK, $CREATE_GALAXY_LOCK_TABLE, $DELETE_GALAXY_LOCK, $DELETE_GALAXY_LOCK_TABLE, $GET_GALAXY_LOCK_INFO, $GET_GALAXY_LOCK_SIZE

Return Values

SS$_NORMAL Normal completion.

SS$_IVLOCKID Invalid lock ID.

SS$_IVLOCKOP Invalid lock operation.

SS$_IVLOCKTBL Invalid lock table.

16.1 Locking Error Messages

 IVLOCKOP <invalid lock operation> 
 
   An attempt was made to release a lock that is not 
   owned. 
   
   Check that all calls to acquire a lock are matched 
   by calls to release it. 
 
 IVLOCKTBL <invalid lock table> 
 
   The lock table handle passed to the locking service 
   does not represent a valid lock table. 
 
   Verify that the lock table handle being used is the 
   same as that returned by SYS$CREATE_GALAXY_LOCK_TABLE 
   or SYS$INIT_GALAXY_LOCK_TABLE. 
 
 LOCKINUSE <invalid operation; lock is in use> 
 
   An attempt was made to delete a lock which is in use 
   or to initialize a lock which is already initialized 
 
   Verify that the lock handle being used is the same as 
   that returned by SYS$CREATE_GALAXY_LOCK or 
   SYS$INIT_GALAXY_LOCK. 
 
 LOCK_TIMEOUT <failed to acquire lock; request has timed out> 
 
   An attempt to acquire a lock did not complete 
   during the timeout period. 
 
   This problem could be caused by a timeout value 
   that is too small. It can also be caused by 
   a thread holding the lock for too long. 
 
 BADLCKTBL <galaxy lock table is corrupt> 
 
   The list of locks in the specified lock table is 
   corrupt. 
 
   Lock tables are writable from the access 
   mode in which they are created. Verify that the 
   application is not overwriting the lock table. 
 
        NOBREAK  <failed to acquire lock; lock ownership is broken> 
  
   An attempt to acquire a lock failed because the 
   lock ownership had been broken and GLOCK$C_NOBREAK 
   was specified on the call to SYS$ACQUIRE_GALAXY_LOCK. 
 
   Lock ownership being broken can be the result of a 
   process or system failure while a lock is held. 
   Depending on how the lock is used, this could 
   mean that the data this lock protects is corrupt. 
 
 NOWAIT  <failed to acquire lock; NOWAIT was specified> 
 
   An attempt to acquire a lock failed because the 
   lock is currently owned and GLOCK$C_NOWAIT 
   was specified on the call to SYS$ACQUIRE_GALAXY_LOCK 
 
   The application must either retry the operation or 
   wait for the lock to become available. 
 
        BROKEN  <lock acquired after lock ownership was broken.> 
 
                        An attempt to acquire a lock succeeded but the 
   previous owner of the lock no longer existed and 
   its ownership was broken. 
 
   Lock ownership being broken can be the result of a 
   process or system failure while a lock is held. 
   Depending on how the lock is used, this could 
   mean that the data this lock protects is corrupt.

Chapter 17
System Events Programming Interfaces

Applications can register to be notified when certain system events occur; for example, when an instance joins the galaxy or if a CPU joins a configure set. If events are registered, an application can decide how to respond when the registered events occur.

$SET_SYSTEM_EVENT (Alpha Only)

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 usage event_code

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 processors 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 processors 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

type

access

Defined in SYSEVTDEF.

SYSEVT$M_REPEAT_NOTIFY When this flag is set, event notification is 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.

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 processors 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 processors have become active within this OpenVMS instance.
SYSEVT$C_DEL_CONFIG_CPU	One or more processors have become inactive within this OpenVMS instance.

Symbolic Name	Description
PSL$C_KERNEL	Kernel
PSL$C_EXEC	Executive
PSL$C_SUPER	Supervisor
PSL$C_USER	User

Description

The Set System Event service establishes a request for notification 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 the event specified is non-zero, that event is added to the set of events that trigger notification on the notification object.
The service will verify that the input parameters specify 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 enabled on the object before another notification (AST delivery) can occur if flag is not set.
Errors are returned in the following cases:

If quotas are exceeded, an error is returned. It is important to note that this routine returns an error 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 the astadr argument is omitted, and a new notification object is being created, SS$_BADPARAM is returned.
If the event argument is incorrectly specified, SS$_BADPARAM is returned.
If the access mode parameter is more privileged than the mode of the caller, the mode of the caller is used.
If specified, the handle argument must be writeable from the mode of the caller. SS$_ACCVIO is returned if this is not the case.

Required Access or Privileges

None
Required Quota

ASTLM
Related Services

$CLEAR_SYSTEM_EVENT

Return Values

SS$_NORMAL The service completed successfully.

SS$_ACCVIO The service cannot access the locations specified by one or more arguments.

SS$_BADPARAM One or more arguments has an invalid value.

SS$_EXASTLM The process exceeded its quota for outstanding ASTs.

SS$_INSFMEM The system dynamic memory is insufficient to complete the service.

$CLEAR_SYSTEM_EVENT (Alpha Only)

Removes one or more notification requests previously established by a call to $SET_SYSTEM_EVENT.
This service 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.

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 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

Return Values

SS$_NORMAL The service completed successfully.

SS$_ACCVIO The service cannot access the location specified by the handle.

SS$_BADPARAM One or more arguments has an invalid value, such as an invalid handle.

SS$_NOSUCHOBJ No request was found that matches the description supplied.

Contents

Index

privacy and legal statement

6512PRO_011.HTML

OpenVMS usage	lock table handle
type	longword (unsigned)
access	read
mechanism	input by value

SS$_NORMAL	Normal completion.
SS$_BADPARAM	Bad parameter value.
SS$_IVLOCKID	Invalid lock ID.
SS$_IVLOCKTBL	Invalid lock table.
SS$_NOCMKRNL	Operation requires CMKRNL privilege.
SS$_NOSHMEM	Operation requires SHMEM privilege.

OpenVMS usage	handle for the galaxy lock
type	quadword (unsigned)
access	read
mechanism	input by value

OpenVMS usage	address
type	zero-terminated string
access	write
mechanism	output by reference

OpenVMS usage	galaxy lock handle
type	quadword (unsigned)
access	read
mechanism	input by value

OpenVMS usage	event_code
type	longword (unsigned)
access	read only
mechanism	by value

OpenVMS usage	ast_procedure
type	procedure value
access	call without stack unwinding
mechanism	by 32-bit or 64-bit reference

OpenVMS usage	user_arg
type	quadword
access	read only
mechanism	by value

OpenVMS usage	access_mode
type	longword (unsigned)
access	read only
mechanism	by value

OpenVMS usage	handle
type	quadword (unsigned)
access	read/write
mechanism	by reference

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The service cannot access the locations specified by one or more arguments.
SS$_BADPARAM	One or more arguments has an invalid value.
SS$_EXASTLM	The process exceeded its quota for outstanding ASTs.
SS$_INSFMEM	The system dynamic memory is insufficient to complete the service.

OpenVMS usage	identifier
type	quadword (unsigned)
access	read only
mechanism	by reference

OpenVMS Alpha Galaxy Guide

$DELETE_GALAXY_LOCK_TABLE (Alpha Only)

Format

SYS$DELETE_GALAXY_LOCK_TABLE lcktbl_handle

C Prototype

int sys$delete_galaxy_lock_table (unsigned int *lcktbl_handle);

Arguments

lcktbl_handle

Description

Return Values

$GET_GALAXY_LOCK_INFO (Alpha Only)

Format

SYS$GET_GALAXY_LOCK_INFO handle ,name ,timeout ,size ,ipl ,rank ,flags

C Prototype

int sys$get_galaxy_lock_info (unsigned __int64 lock_handle, char *name, unsigned int *timeout, unsigned int *size, unsigned int *ipl, unsigned int *rank, unsigned short int *flags);

Arguments

handle

name

timeout

size

ipl

rank

flags

Description

Return Values

$GET_GALAXY_LOCK_SIZE (Alpha Only)

Format

SYS$GET_GALAXY_LOCK_SIZE min_size ,max_size

C Prototype

int sys$get_galaxy_lock_size (unsigned int *min_size, unsigned int *max_size);

Arguments

min_size

max_size

Description

Return Values

$RELEASE_GALAXY_LOCK (Alpha Only)

Format

SYS$RELEASE_GALAXY_LOCK handle

C Prototype

int sys$release_galaxy_lock (unsigned __int64 lock_handle);

Arguments

handle

Description

Return Values

16.1 Locking Error Messages

Chapter 17System Events Programming Interfaces

$SET_SYSTEM_EVENT (Alpha Only)

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

astadr

astprm

acmode

flags

handle

Description

Return Values

$CLEAR_SYSTEM_EVENT (Alpha Only)

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

acmode

event

Description

Return Values

int sys$get_galaxy_lock_info (unsigned __int64 lock_handle, char name, unsigned int timeout, unsigned int size, unsigned int ipl, unsigned int rank, unsigned short int flags);

int sys$get_galaxy_lock_size (unsigned int min_size, unsigned int max_size);

Chapter 17
System Events Programming Interfaces

int sys$set_system_event (unsigned int event, void (astadr)(__unknown_params), int astprm, unsigned int acmode, unsigned int flags, struct _generic_64 handle);