HP OpenVMS System Services Reference Manual


Previous Contents Index

Note

The system report changes to subkeys of the specified key only if the REG$_FLAGSUBKEY item code is set to 1.

REG$_PATHBUFFER

The REG$_PATHBUFFER item code is an output item code. It is a buffer that receives a set of either key paths or value paths, separated by a null Unicode character (4 bytes long). (The third longword of the item descriptor contains the number of bytes written to the buffer.)

REG$_REQLENGTH

The REG$_REQLENGTH item code is an output item code. It is a longword that receives the required buffer size (in bytes) to complete the operation successfully.

REG$_RETURNSTATUS

The REG$_RETURNSTATUS item code is an output item code. It is a longword that receives the final completion status for a specified operation. For more information, see the Condition Values Returned section of this chapter.

REG$_SECACCESS

The REG$_SECACCESS item code is an input item code. It is a longword mask that specifies the desired security access for the new key. It takes any combination of the following values:
Security access mask Description
REG$M_ALLACCESS A combination of the following access values:
REG$K_CREATELINK
REG$K_CREATESUBKEY
REG$K_ENUMSUBKEYS
REG$K_NOTIFY
REG$K_QUERYVALUE
REG$K_SETVALUE
REG$M_CREATELINK Allows creation of a symbolic link.
REG$M_CREATESUBKEY Allows creation of subkeys.
REG$M_ENUMSUBKEYS Allows enumeration of subkeys.
REG$M_EXECUTE Allows read access.
REG$M_NOTIFY Allows change notification.
REG$M_QUERYVALUE Allows queries of subkey data.
REG$M_READ A combination of the following access values:
REG$K_ENUMSUBKEYS
REG$K_QUERYVALUE
REG$K_NOTIFY
REG$M_SETVALUE Allows setting of values and data.
REG$M_WRITE A combination of the following access values:
REG$K_CREATESUBKEY
REG$K_SETVALUE

REG$_SECURITYPOLICY

The REG$_SECURITYPOLICY item code is an input item code. It is a longword that specifies the security policy to enforce for the key.

It takes the following value:
Policy Setting Description
REG$K_POLICY_NT_40 Access is required to the first key and the requested key (default).

REG$_SEPARATOR

The REG$_SEPARATOR item code is an empty item code that provides a separator between sets of item codes.

Using this item code, you can group multiple requests into a single call to the $REGISTRY service. If you use this multiple-request feature, use the REG$_SEPARATOR item code to indicate the end of the set of item codes for the current request and that there is another request to process.

REG$_SUBKEYINDEX

The REG$_SUBKEYINDEX item code is an input item code. It is a longword that specifies the index of the subkey to retrieve.

REG$_SUBKEYNAME

The REG$_SUBKEYNAME item code is an input item code. It is a string of Unicode characters that specifies the name of a subkey. A Unicode character is 4 bytes long.

REG$_SUBKEYNAMEMAX

The REG$_SUBKEYNAMEMAX item code is an output item code. It is a longword that receives the length (in characters) of a specified key's longest subkey name.

REG$_SUBKEYSNUMBER

The REG$_SUBKEYSNUMBER item code is an output item code. It is a longword that receives the number of subkeys contained in a specified key.

REG$_VALUEDATA

The REG$_VALUEDATA item code is, depending on the function code, either an input or output item code. It is a buffer that contains either the value data component to write to the OpenVMS Registry (input), or it receives a data value component from the OpenVMS Registry (output).

REG$_VALUEDATAMAX

The REG$_VALUEDATAMAX item code is an output item code. It is a longword that receives the length (in bytes) of the specified key's longest data component value.

REG$_VALUEDATASIZE

The REG$_VALUEDATASIZE item code is an output item code. It is used to specify the address and size of a buffer that receives the length, in bytes, of the value data. The buffer size should be 4 bytes.

REG$_VALUEINDEX

The REG$_VALUEINDEX item code is an input item code. It is a longword that specifies the index of the value to retrieve within a specified key. Note that the value index starts at zero and can be any value up to one less than the count returned by REG$_VALUENUMBER.

REG$_VALUENAME

The REG$_VALUENAME item code is, depending on the function code, either an input or an output item code. It is a string of Unicode characters that specifies the name of a value.

REG$_VALUENAMEMAX

The REG$_VALUENAMEMAX item code is an output item code. It is a longword that receives the length (in characters) of a specified key's longest value name.

REG$_VALUENUMBER

The REG$_VALUENUMBER item code is an output item code. It is a longword that receives the number of values contained in a specified key.

REG$_VOLATILE

The REG$_VOLATILE item code identifies the volatility of an item. As an output, it returns the volatility of the object. On OpenVMS, volatile keys and values are lost when all nodes running an OpenVMS Registry server are rebooted. (In a standalone system, volatile keys and values are lost when the system reboots.)
Volatile Type Description
REG$K_CLUSTER The item is removed when the cluster reboots.
REG$K_NONE The item is not volatile (default).
Function Modifiers You can optionally specify the high-order bits of a function code value with function modifiers. These individual bits can alter the operation of the function.

For example, you can specify the function modifier REG$M_CASE_SENSITIVE with the function REG$FC_CREATE_KEY. When you use the function and function modifier together, the data passed to the OpenVMS Registry is treated as case sensitive. The two values are written in HP C as REG$M_CASE_SENSITIVE | REG$FC_CREATE_KEY .

The OpenVMS Registry function modifiers are defined in the header file REGDEF.H.

REG$M_CASE_SENSITIVE

Use case sensitive matching for keys and values.

REG$M_DISABLE_WILDCARDS

Treat wildcard characters as normal characters for this function.

REG$M_IGNORE_LINKS

Force the operation to not follow any symbolic links associated with a key or a value.

By default, if a key or value is symbolically linked to another key or value, the system follows all links so that the operation specified by the function code is performed on the linked key or value.

When you specify the REG$M_IGNORE_LINKS function modifier, the operation specified by the function code affects only the specified key or value, not the linked key or value.

By default, if a key or value has a symbolic link, it can not be deleted. If you specify the REG$M_IGNORE_LINKS function modifier, the system deletes the key or value.

REG$M_NOW

Write to disk immediately, regardless of the REG$_CACHEACTION item code value.

Description

The $REGISTRY service provides the means to create, delete and modify registry keys, key values, and key attributes.

The $REGISTRY service uses process P1 space to store handles to keys.

The $REGISTRY service must be called at IPL 0, and requires system dynamic memory to deliver AST requests.

Related Services

$REGISTRYW

Condition Values Returned

SS$_NORMAL Normal successful completion.
SS$_ACCVIO One of the arguments cannot be read/written.
SS$_BADPARAM Function code or one of the item list code is invalid.
SS$_EXASTLM Exceeded AST limit.
SS$_INSFARG Insufficient number of argument supplied.
SS$_INSFP1POOL Not enough process P1 space available.
SS$_NOIMPERSONATE The caller does not have the privilege to obtain information about the specified personae.
SS$_TOO_MANY_ARGS Too many arguments.
REG$_ACCESSDENIED Requested access to key is denied.
REG$_IPLTOOHIGH Callers above IPL 0 cannot call this service.

Condition Values Returned in the I/O Status Block

SS$_NORMAL Normal successful completion.
SS$_ACCVIO One of the arguments cannot be read/written.
SS$_BADPARAM Function code or one of the item list code is invalid.
SS$_EXASTLM Exceeded AST limit.
SS$_INSFARG Insufficient number of argument supplied.
SS$_INSFP1POOL Not enough process P1 space available.
SS$_NOIMPERSONATE The caller does not have the privilege to obtain information about the specified personae.
SS$_TOO_MANY_ARGS Too many arguments.
REG$_ACCESSDENIED Requested access to key is denied.
REG$_BUFFEROVF Buffer overflow.
REG$_DBALREADYLOADED Database is already loaded.
REG$_DBNOTYETLOADED Database is not yet loaded.
REG$_EXQUOTA Registry file quota or page file quota exceeded.
REG$_HASLINK Key has a link to another key.
REG$_HAVESUBKEYS Cannot delete a key with subkeys.
REG$_INTERNERR Registry internal error.
REG$_INVCACHEACTION Invalid cache action parameter.
REG$_INVCREDENTIALS NT credentials are not valid.
REG$_INVDATA Invalid data value.
REG$_INVDATATYPE Invalid data type parameter.
REG$_INVFUNCCODE Invalid function code.
REG$_INVKEYFLAGS Invalid key flags.
REG$_INVKEYID Key does not exist or invalid key ID was specified.
REG$_INVKEYNAME Invalid key name.
REG$_INVLINK Invalid link or link type.
REG$_INVLINKPATH Invalid link path.
REG$_INVPARAM Invalid parameter.
REG$_INVPATH Invalid key path.
REG$_INVSECDESCRIPTOR Invalid security descriptor.
REG$_INVSECPOLICY Invalid security policy parameter.
REG$_INVVALNAME Invalid value name.
REG$_INVVOLROOTKEY Cannot create a new file with a volatile root key.
REG$_IPLTOOHIGH Callers above IPL 0 cannot call this service.
REG$_KEYCHANGED Key or subkey has changed.
REG$_KEYLOCKED Key locked by another thread.
REG$_KEYNAMEEXIST Key name already exists.
REG$_NOKEY Specified key does not exist.
REG$_NOMOREITEMS No more items for specified key.
REG$_NOPATHFOUND Path not found.
REG$_NORESPONSE OpenVMS Registry server failed to respond within the alloted time period.
REG$_NOTROOTKEY Invalid root key index.
REG$_NOTSUPPORTED Function code, item code, or item value is not supported.
REG$_NOVALUE Specified value does not exist.
REG$_REQRECEIVED Received request for key change notification.
REG$_RESERVED Cannot delete or modify a reserved key or value.
REG$_SECVIO Violates the security access method specified when this key was last opened.
REG$_STRINGTOOLONG Input string too long.
REG$_STRINGTRUNC Output buffer is not large enough to contain the converted string.
REG$_TOOMANYOPENKEY Number of opened keys exceeds the limit.
REG$_VALUEEXIST Value already exists.
REG$_VOLMISMATCH Cannot create nonvolatile subkey for a volatile key.

This service can also return status values from the following system services: $CLREF, $SYNCH, $PERSONA_EXTENSION_LOOKUP, and $PERSONA_QUERY.


$REGISTRYW (Alpha and Integrity servers)

On Alpha and Integrity server systems, interface to the OpenVMS Registry database server.

The $REGISTRY service supports both asynchronous and synchronous operations. For asynchronous completion, use the Registry ($REGISTRY) system service.

For synchronous completion, use the Registry and Wait ($REGISTRYW) system service. The $REGISTRYW system service is identical to the $REGISTRY system service, except that $REGISTRYW returns to the caller after the system completes the requested operation. For additional information about system service completion, see the Synchronize ($SYNCH) system service.

This system service is 64-bit compatible.


Format

SYS$REGISTRYW [efn] ,func ,0 ,itmlst ,[iosb or iosa_64] [,astadr or astadr_64] [,astprm or astprm_64] [,timeout]


C Prototype

int sys$registryw (unsigned int efn, unsigned int func, void *, void *itmlst, struct _iosb *iosb, ...);


$RELEASE

The Release service unlocks the record specified by the contents of the record file address (RAB$W_RFA) field of the RAB.

For additional information about this service, see the OpenVMS Record Management Services Reference Manual.


$RELEASE_GALAXY_LOCK (Alpha Only)

Releases ownership of an OpenVMS Galaxy lock.

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

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


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


Condition Values Returned

SS$_NORMAL Normal completion.
SS$_IVLOCKID Invalid lock id.
SS$_IVLOCKOP Invalid lock operation.
SS$_IVLOCKTBL Invalid lock table.

$REMOVE

The Remove service deletes a file name from a directory. It is the reverse of the Enter service.

For additional information about this service, see the OpenVMS Record Management Services Reference Manual.


$REM_HOLDER

Deletes the specified holder record from the target identifier's list of holders.

Format

SYS$REM_HOLDER id ,holder


C Prototype

int sys$rem_holder (unsigned int id, struct _generic_64 *holder);


Arguments

id


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

Binary value of target identifier whose holder is deleted when $REM_HOLDER completes execution. The id argument is a longword containing the identifier value.

holder


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

Identifier of holder being deleted when $REM_HOLDER completes execution. The holder argument is the address of a quadword containing the UIC identifier of the holder in the first longword and the value of 0 in the second longword.

Description

The Remove Holder Record from Rights Database service removes the specified holder record from the target identifier's list of holders.

Required Access or Privileges

Write access to the rights database is required.

Required Quota

None

Related Services

$ADD_HOLDER, $ADD_IDENT, $ASCTOID, $CREATE_RDB, $FIND_HELD, $FIND_HOLDER, $FINISH_RDB, $GRANTID, $IDTOASC, $MOD_HOLDER, $MOD_IDENT, $REM_IDENT, $REVOKID


Condition Values Returned

SS$_NORMAL The service completed successfully.
SS$_ACCVIO The holder argument cannot be read by the caller.
SS$_INSFMEM The process dynamic memory is insufficient for opening the rights database.
SS$_IVIDENT The specified identifier or holder identifier is of invalid format.
SS$_NORIGHTSDB The rights database does not exist.
SS$_NOSUCHID The specified identifier does not exist in the rights database, or the specified holder identifier does not exist in the rights database.
RMS$_PRV The user does not have write access to the rights database.

Because the rights database is an indexed file accessed with OpenVMS RMS, this service can also return RMS status codes associated with operations on indexed files. For descriptions of these status codes, see the OpenVMS Record Management Services Reference Manual.


Previous Next Contents Index