HP OpenVMS Systems Documentation

Allocates an OpenVMS Galaxy lock block from a lock table created with the $CREATE_GALAXY_LOCK_TABLE service.

Note that this system service is supported only in an OpenVMS Alpha Galaxy environment.

For more information about programming with OpenVMS Galaxy system services, refer to the OpenVMS Alpha Partitioning and Galaxy Guide.

Format

SYS$CREATE_GALAXY_LOCK lcktbl_handle ,name ,size ,timeout ,ipl ,rank ,handle

C Prototype

int sys$create_galaxy_lock (unsigned int lcktbl_handle, void *name, unsigned int size, unsigned int timeout, unsigned int ipl, unsigned int rank, unsigned __int64 *lock_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 lock table in which to create the lock. This value is returned by SYS$CREATE_GALAXY_LOCK_TABLE.

name

OpenVMS usage:	address
type:	ASCID string
access:	read
mechanism:	input by reference

The name parameter is a pointer to an ASCID string (passed by descriptor). The name can be a maximum of 15 characters. Lock names are not checked for uniqueness; therefore, multiple locks can be created with the same name.

timeout

OpenVMS usage:	wait timeout
type:	longword (unsigned)
access:	read
mechanism:	input by value

The 32-bit wait or spin timeout specified in 10 microsecond units. If not specified, the timeout defaults to 10 microseconds.

size

OpenVMS usage:	byte count
type:	longword (unsigned)
access:	read
mechanism:	input by value

The size of the galaxy lock in bytes. Galaxy locks have two legal sizes. These values are returned by SYS$GET_GALAXY_LOCK_SIZE. The value passed to SYS$CREATE_GALAXY_LOCK must be equal to the value passed to the call to SYS$CREATE_GALAXY_LOCK_TABLE.

ipl

OpenVMS usage:	IPL of lock
type:	longword (unsigned)
access:	read
mechanism:	input by value

For galaxy locks acquired in kernel mode, the IPL to raise to while the lock is held. This parameter is ignored for all other access mode.

rank

OpenVMS usage:	rank of lock
type:	longword (unsigned)
access:	read
mechanism:	input by value

Rank applied to a galaxy lock. Ranking is used to detect potential deadlocks. This parameter is currently ignored.

handle

OpenVMS usage:	address
type:	quadword (unsigned)
access:	write
mechanism:	output by reference

The handle parameter is a pointer to a quadword. The value returned is a 64-bit handle that uniquely identifies the lock galaxy-wide.

Description

This service allocates an OpenVMS Galaxy lock block from a lock table created with the $CREATE_GALAXY_LOCK_TABLE service.

Required Access or Privileges

For System Lock: CMKRNL, SHMEM
For User Lock: SHMEM
Write access to Lock Table

Required Quota

None

Related Services

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

Condition Values Returned

SS$_NORMAL	Normal completion.
SS$_ACCVIO	Access violation on parameter.
SS$_BADLCKTBL	OpenVMS Galaxy lock table is corrupt.
SS$_BADPARAM	Bad parameter value.
SS$_IVLOCKID	Invalid lock id.
SS$_IVLOCKTBL	Invalid lock table.
SS$_INSFMEM	Insufficient memory in lock table.
SS$_NOCMKRNL	Operation requires CMKRNL privilege.
SS$_NOSHMEM	Operation requires SHMEM privilege.

Allocates an OpenVMS Galaxy lock table.

Note that this system service is supported only in an OpenVMS Alpha Galaxy environment.

For more information about programming with OpenVMS Galaxy system services, refer to the OpenVMS Alpha Partitioning and Galaxy Guide.

Format

SYS$CREATE_GALAXY_LOCK_TABLE name ,accmode ,section_size ,section_type ,prot ,lock_size ,lcktbl_handle

C Prototype

int sys$create_galaxy_lock_table (void *name, unsigned int accmode, unsigned __int64 section_size, unsigned int section_type, unsigned int prot, unsigned int lock_size, unsigned int *lcktbl_handle);

Arguments

name

OpenVMS usage:	address
type:	ASCID string
access:	read
mechanism:	input by reference

The name parameter is a pointer to an ASCID string (passed by descriptor). The name is given to the global section that is created to contain the galaxy locks.

accmode

OpenVMS usage:	access mode
type:	longword (unsigned)
access:	read
mechanism:	input by value

Access mode that is to be the owner of the pages created during the mapping. The accmode argument is a longword containing the access mode.

section_size

OpenVMS usage:	byte count
type:	quadword (unsigned)
access:	read
mechanism:	input by value

Length of the global section to be created, in bytes. The size must be specified as a multiple of the CPU-specific page size. A size of zero is illegal.

section_type

OpenVMS usage:	bit mask
type:	longword (unsigned)
access:	read
mechanism:	input by value

Used to control where in virtual memory the global section is created. If GLCKTBL$C_PROCESS is specified, the section is created in P2 (process) space. If GLCKTBL$C_SYSTEM is specified, the section is created in S0/S1 (system) space. These constants are defined in the GLOCKDEF macro.

prot

OpenVMS usage:	protection
type:	longword (unsigned)
access:	read
mechanism:	input by value

Protection to be applied to the global section.

The mask contains four 4-bit fields. Bits are read from right to left in each field. The following diagram depicts the mask:

Cleared bits indicate that read, write, execute, and delete access, in that order, are granted to the particular category of user.

Only read and write access are meaningful for lock section protection. Delete access bits are ignored.

lock_size

lcktbl_handle

Description

This service allocates an OpenVMS Galaxy lock table. This structure is used to maintain information about a shared memory section, which this service also creates. The first caller of the service with a unique lock table name creates the section. Additional callers map it. This shared memory section contains a set of Galaxy locks. All locks residing in the section are of the same size. Once the lock table is created, the $CREATE_GALAXY_LOCK service can be used to create and allocate a lock from the table.

The flags GLCKTBL$C_PROCESS and GLCKTBL$C_SYSTEM specify whether the shared memory region is mapped into system space or process space. Creation of process space sections requires the SHMEM privilege. Creation of system space sections requires the SHMEM and CMKRNL privileges.

Required Access or Privileges

CMKRNL, SHMEM

Required Quota

None

Related Services

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

Condition Values Returned

SS$_NORMAL	Normal completion.
SS$_ACCVIO	Access violation on parameter.
SS$_BADPARAM	Bad parameter value.
SS$_CREATED	File or section did not exist; has been created.
SS$_IVLOCKID	Invalid lock id.
SS$_NOPRIV	No privilege for attempted operation.
SS$_NOCMKRNL	Operation requires CMKRNL privilege.
SS$_NOSHMEM	Operation requires SHMEM privilege.

On Alpha systems, creates a buffer object out of a range of pages.

This service accepts 64-bit addresses.

Format

SYS$CREATE_BUFOBJ_64 start_va_64 ,length_64 ,acmode ,flags ,return_va_64 ,return_length_64 ,buffer_handle_64

C Prototype

int sys$create_bufobj_64 (void *start_va_64, unsigned __int64 length_64, unsigned int acmode, unsigned int flags, void *(*(return_va_64)), unsigned __int64 *return_length_64, struct _generic_64 *buffer_handle_64);

Arguments

start_va_64

OpenVMS usage:	address
type:	quadword address
access:	read only
mechanism:	by value

Starting virtual address of the pages to be included in the buffer object. The specified virtual address will be rounded down to a CPU-specific page boundary.

The virtual address space must already exist.

length_64

OpenVMS usage:	byte count
type:	quadword (unsigned)
access:	read only
mechanism:	by value

Length of the virtual address space to be included in the buffer object. The specified length will be rounded up to a CPU-specific page boundary such that it includes all CPU-specific pages in the requested range.

acmode

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

Access mode on behalf of which the request is being made. The acmode argument is a longword containing the access mode.

The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H in SYS$STARLET_C.TLB define the following symbols and their values for the four access modes:

Value	Symbolic Name	Access Mode
0	PSL$C_KERNEL	Kernel
1	PSL$C_EXEC	Executive
2	PSL$C_SUPER	Supervisor
3	PSL$C_USER	User

The most privileged access mode used is the access mode of the caller. For the $CREATE_BUFOBJ_64 service to complete successfully, the resultant access mode must be equal to or more privileged than the access mode already associated with the pages in the specified input range.

flags

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

Flag mask specifying the request options. The flags argument is a longword bit vector in which each bit corresponds to a flag. The $CBODEF macro in STARLET.MLB and CBODEF.H file in SYS$STARLET_C.TLB define a symbolic name for each flag.

The following table describes each flag that is valid for the $CREATE_BUFOBJ_64 service:

Flag	Value	Description
CBO$M_RETSVA	1	If set, returns the system virtual address in the return_va_64 argument instead of the process virtual address range. (Valid for inner mode callers only.)
CBO$M_SVA_32	4	If set, creates the buffer object window in 32-bit S0/S1 space. (By default, this service creates the window in 64-bit S2 space.)

return_va_64

OpenVMS usage:	address
type:	quadword address
access:	write only
mechanism:	by 32- or 64-bit reference

The lowest process virtual address of the pages in the buffer object. The return_va_64 argument is the 32- or 64-bit virtual address of a naturally aligned quadword into which the service returns the virtual address.

return_length_64

OpenVMS usage:	byte count
type:	quadword (unsigned)
access:	write only
mechanism:	by 32- or 64-bit reference

The length of the virtual address range in the buffer object. The return_length_64 argument is the 32- or 64-bit virtual address of a naturally aligned quadword into which the service returns the length of the virtual address range in bytes.

buffer_handle_64

OpenVMS usage:	handle
type:	quadword (unsigned)
access:	write only
mechanism:	by 32- or 64-bit reference

The 32- or 64-bit virtual address of a naturally aligned quadword into which a buffer handle is returned to be used when referencing the created buffer object.

Description

The Create Buffer Object service creates a buffer object for use by the I/O subsystem. The pages that constitute the buffer object are permanently locked into physical memory (but not the process's working set) and double mapped into system space. The net effect is the following:

• I/O can be initiated to or from the buffer without the need to probe or lock the buffer pages.
• The process is still fully swappable.

If the condition value SS$_ACCVIO is returned by this service, a value cannot be returned in the memory locations pointed to by the return_va_64, return_length_64, and buffer_handle_64 arguments.

If a condition value other than SS$_ACCVIO is returned, the returned address and returned length indicate the pages that were successfully made part of the buffer object before the error occurred. If no pages were made part of the buffer object, the return_va_64 argument will contain the value -1, and a value is not returned in the memory location pointed to by the return_length_64 argument.

Required Privileges

No privileges are required if calling $CREATE_BUFOBJ_64 from an inner mode. If calling from user mode, the process must hold the rights identifier VMS$BUFFER_OBJECT_USER at the time of the call. This identifier is normally granted by the system administrator via the Authorize utility.

Required Quota

No process quota is charged but the pages are charged against a systemwide limit, system parameter MAXBOBMEM.

Related Services

$CRETVA_64, $DELETE_BUFOBJ, $EXPREG_64

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The return_va_64, return_length_64, or buffer_handle_64 argument cannot be written by the caller.
SS$_BADPARAM	Invalid flags options specified.
SS$_EXBUFOBJLM	Buffer object cannot be created because it would bring the total number of buffer object pages above the systemwide limit MAXBOBMEM.
SS$_INSFMEM	Insufficient dynamic memory.
SS$_INSFSPTS	Insufficient system page table entries.
SS$_NOBUFOBJID	The process attempted to create a buffer object from user mode but was not holding required rights identifier VMS$BUFFER_OBJECT_USER.
SS$_NOPRIV	Valid flag options were specified but from user mode.
SS$_PAGNOTWRITE	A page within the address range is not writable.
SS$_PAGOWNVIO	The pages could not be put into the buffer object because the access mode associated with the call to $CREATE_BUFOBJ_64 was less privileged than the access mode associated with the pages.

On Alpha systems, creates a permanent, memory-resident, global demand-zero section to which processes can map. Shared page table sections can also be created.

This service accepts 64-bit addresses.

Format

SYS$CREATE_GDZRO gs_name_64 ,ident_64 ,prot ,length_64 ,acmode ,flags [,reserved_length_64] [,rad_mask]

C Prototype

int sys$create_gdzro (void *gs_name_64, struct _secid *ident_64, unsigned int prot, unsigned __int64 length_64, unsigned int acmode, unsigned int flags,...);

Arguments

gs_name_64

OpenVMS usage:	section_name
type:	character-coded text string
access:	read only
mechanism:	by 32- or 64-bit descriptor--fixed-length string descriptor

Name of the global section. The gs_name_64 argument is the 32- or 64-bit virtual address of a naturally aligned 32- or 64-bit string descriptor pointing to this name string.

ident_64

OpenVMS usage:	section_id
type:	quadword (unsigned)
access:	read only
mechanism:	by 32- or 64-bit reference

Identification value specifying the version number of the global section. The ident_64 argument is a quadword containing three fields. The ident_64 argument is the 32- or 64-bit virtual address of a naturally aligned quadword that contains the identification value.

The first longword specifies the matching criteria in its low-order 2 bits. Their meanings are as follows:

Value	Symbolic Name	Match Criteria
0	SEC$K_MATALL	Match all versions of the section.
1	SEC$K_MATEQU	Match only if major and minor identifications match.
2	SEC$K_MATLEQ	Match if the major identifications are equal and the minor identification of the mapper is less than or equal to the minor identification of the global section.

If you specify the ident_64 argument as 0, the version number and match control fields default to 0.

The version number is in the second longword. The version number contains two fields: a minor identification in the low-order 24 bits and a major identification in the high-order 8 bits. You can assign values for these fields by installation convention to differentiate versions of global sections. If no version number is specified when a section is created, processes that specify a version number when mapping cannot access the global section.

prot

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

Protection to be applied to the global demand-zero section. The mask contains four 4-bit fields. Bits are read from right to left in each field. The following diagram depicts the mask:

Cleared bits indicate that read, write, execute, and delete access, in that order, are granted to the particular category of user. Only read, write, and execute access are meaningful for section protection. Delete access bits are ignored. Read access also grants execute access for those situations where execute access applies. If 0 is specified, read access and write access are granted to all users.

length_64

acmode