 |
HP OpenVMS System Services Reference Manual
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.
|
