HP OpenVMS System Services Reference Manual

If the buffer supplied by the application is not big enough to contain all the subkey path names found, the system returns the SS$_BUFFEROVF error message in the iosb argument, and the system returns the required length to complete the operation successfully in the REG$_REQLENGTH item (if specified).

Specify the item codes as follows:

Item Code	Required	Parameter Type
REG$_KEYPATH	No	Input (Pointer to Unicode string. Unicode character is 4 bytes long.)
REG$_KEYID	Yes	Input
REG$_PATHBUFFER	Yes	Output
REG$_REQLENGTH	No	Output
REG$_RETURNSTATUS	No	Output
REG$_VALUENAME	Yes	Input

REG$FC_SET_VALUE

Using this function 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.

When a value is set to a link, the system validates the link unless you specify the REG$M_IGNORE_LINKS function code modifier.

Specify the item codes as follows:

Item Code	Required	Parameter Type
REG$_DATAFLAGS	No	Input
REG$_DATATYPE	No	Input
REG$_KEYID	Yes	Input
REG$_KEYPATH	No	Input (Pointer to Unicode string. Unicode character is 4 bytes long.)
REG$_LINKPATH	No	Input (Pointer to Unicode string. Unicode character is 4 bytes long.)
REG$_LINKTYPE	No	Input
REG$_RETURNSTATUS	No	Output
REG$_SEPARATOR	No	n/a
REG$_VALUEDATA	No	Input
REG$_VALUENAME	No	Input

Item Codes Table SYS-51 provides a summary of item codes that are valid as an item descriptor in the itmlst argument. The table lists the item codes, input/output usage, and data types.

Complete descriptions of each item code are provided in the sections that follow this table.

Table SYS-51 Item Code Summary

Item Code	Input/Output	Data Type
REG$_CACHEACTION	Input, output	Longword
REG$_CLASSNAME	Input, output	(Pointer to Unicode string. Unicode character is 4 bytes long.)
REG$_CLASSNAMEMAX	Output	Longword
REG$_DATAFLAGS	Input, output	Quadword
REG$_DATATYPE	Input, output	Longword
REG$_DISPOSITION	Output	Longword
REG$_FLAGOPCODE	Input	Longword
REG$_FLAGSUBKEY	Input	Longword
REG$_KEYID	Input, output	Longword
REG$_KEYPATH	Input	(Pointer to Unicode string. Unicode character is 4 bytes long.)
REG$_KEYRESULT	Output	Longword
REG$_LASTWRITE	Output	Quadword
REG$_LINKCOUNT	Output	Longword
REG$_LINKPATH	Input, output	(Pointer to Unicode string. Unicode character is 4 bytes long.)
REG$_LINKTYPE	Input, output	Longword
REG$_NEWNAME	Input	Unicode string
REG$_NOTIFYFILTER	Input	Longword
REG$_PATHBUFFER	Output	Buffer
REG$_REQLENGTH	Output	Longword
REG$_RETURNSTATUS	Output	Longword
REG$_SECACCESS	Input	Longword
REG$_SECURITYPOLICY	Input, output	Longword
REG$_SEPARATOR	n/a	None
REG$_SUBKEYINDEX	Input	Longword
REG$_SUBKEYNAME	Input, output	(Pointer to Unicode string. Unicode character is 4 bytes long.)
REG$_SUBKEYNAMEMAX	Output	Longword
REG$_SUBKEYSNUMBER	Output	Longword
REG$_VALUEDATA	Input, output	Buffer
REG$_VALUEDATAMAX	Output	Longword
REG$_VALUEDATASIZE	Output	Longword
REG$_VALUEINDEX	Input	Longword
REG$_VALUENAME	Input, output	Unicode string
REG$_VALUENAMEMAX	Output	Longword
REG$_VALUENUMBER	Output	Longword
REG$_VOLATILE	Input, output	Longword

REG$_CACHEACTION

The REG$_CACHEACTION item code is an input item code. It is a longword flag that specifies whether the information on a specified object should be written to disk immediately. It takes one of the following values:

Cache Value	Description
REG$K_WRITEBEHIND	Write information about the specified object written to disk at a later time (default).
REG$K_WRITETHRU	Write information about the specified object to disk immediately.

Note If you do not specify this item code, the value or key inherits its value from the parent object. By default, the entry points (REG$_HKEY_CLASSES_ROOT, REG$_HKEY_LOCAL_MACHINE, and REG$_HKEY_USERS) are set with a value equal to that of REG$K_WRITEBEHIND.

REG$_CLASSNAME

The REG$_CLASSNAME item code is, depending on the function code, either an input or output item code.

The class name is an information field for a key. The type of an object is an example of a class name. It can be composed of any string of Unicode characters. A Unicode character is 4 bytes long.

REG$_CLASSNAMEMAX

The REG$_CLASSNAMEMAX item code is an output item code. It receives the length, in bytes, of the longest string specifying a subkey class name.

REG$_DATAFLAGS

Depending on the function code, the REG$_DATAFLAGS item code is either an input or output item code. It is a 64-bit application-dependent value data flag.

REG$_DATATYPE

Depending on the function code, the REG$_DATATYPE item code is either an input or output item code.

It is a longword that either specifies the type of information to be stored as a value data or receives the type of information of a specified value data component.

It takes one of the following values:

Type code	Description
REG$K_BINARY	Binary data
REG$K_DWORD	A 32-bit number
REG$K_EXPAND_SZ	A string of Unicode characters
REG$K_MULTI_SZ	A concatenated array of REG$K_SZ strings
REG$K_NONE	No defined value type (default)
REG$K_QWORD	A 64-bit number
REG$K_SZ	A null-terminated Unicode string

Note The difference between REG$K_EXPAND_SZ and REG$K_SZ: A string is a set of characters usually in human-readable form. Many value entries in the OpenVMS Registry are written using a string (REG_SZ) or an expandable string (REG_EXPAND_SZ) format. An expandable string is usually human-readable text, but it can also include a variable that will be replaced when the string is called by an application. For example, on a Windows NT system, in the value entry %SystemRoot%\System32\Bootok.exe , %SystemRoot% is the expandable portion of the variable. This part is replaced with the actual location of the directory that contains the Windows NT system files.

REG$_DISPOSITION

The REG$_DISPOSITION item code is an output item code. It is a longword and takes one of the following values:

Disposition value	Description
REG$K_CREATENEWKEY	The key did not exist and was created.
REG$K_OPENEXISTINGKEY	The key existed and was opened.

REG$_FLAGOPCODE

The REG$_FLAGOPCODE item code is an input item code. It is a longword flag that indicates how the REG$_DATAFLAGS input item code should be matched against the data flags field in the OpenVMS Registry database. It takes one of the following values:

Operator code options	Description
REG$K_ANY	The data field in the OpenVMS Registry database must contain at least one of the flags in the REG$_DATAFLAGS input item code.
REG$K_EXACTMATCH	The REG$_DATAFLAGS input item code must match exactly the data flags field in the OpenVMS Registry database.
REG$K_EXCLUDE	The data flags field in the OpenVMS Registry database must not contain the flags in the REG$_DATAFLAGS input item code.
REG$K_INCLUDE	The data flags field in the OpenVMS Registry database must contain, at a minimum, the flags in the REG$_DATAFLAGS input item code.
REG$K_NOTANY	The data field in the OpenVMS Registry database must not contain any of the flags in the REG$_DATAFLAGS input item code.

REG$_FLAGSUBKEY

The REG$_FLAGSUBKEY item code is an input item code. It is a longword Boolean field that indicates the following:

• If set to 1, report changes in a specified key and any of its subkeys.
• If set to 0, report changes to a specified key only.

REG$_KEYID

The REG$_KEYID item code is an input item code. It is a longword that contains the key identifier.

REG$_KEYRESULT

The REG$_KEYRESULT item code is an output item code. It is a longword that receives a key identifier. The key identifier can be passed to other Registry calls using the REG$_KEYID item code.

REG$_KEYPATH

The REG$_KEYPATH item code is an input item code. It is a string of Unicode characters that specifies a key path. A Unicode character is 4 bytes long.

REG$_LASTWRITE

The REG$_LASTWRITE item code is an output item code. It is a quadword representation of absolute time that receives the time a specified key was last written to (including changes to its values).

REG$_LINKCOUNT

The REG$_LINKCOUNT item code is an output item code. It is longword count of the number of symbolic links that refer to the item.

REG$_LINKPATH

The REG$_LINKPATH 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 key path to which a specified key is linked. A Unicode character is 4 bytes long.

REG$_LINKTYPE

The REG$_LINKTYPE item code is, depending on the function code, either an input or an output item code. It is longword type that indicates the link type.

Link Type	Description
REG$K_NONE	No link (default)
REG$K_SYMBOLICLINK	Symbolic (logical) link

REG$_NEWNAME

The REG$_NEWNAME item code is a string of Unicode characters that specifies the new name of the key.

REG$_NOTIFYFILTER

The REG$_NOTIFYFILTER item code is an input item code. It is a longword mask that specifies which changes to the specified key and its subkeys and values to report. It takes any combination of the following values:

Value	Description
REG$M_CHANGEATTRIBUTES	An attribute change of the specified key or its subkeys.
REG$M_CHANGELASTSET	Changes to the last write time of the specified key or its subkeys.
REG$M_CHANGENAME	A key name change, including creation and deletion, of the specified key or its subkeys.

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

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.