![[Compaq]](../../images/compaq.gif)
![[Go to the documentation home page]](../../images/buttons/bn_site_home.gif)
![[How to order documentation]](../../images/buttons/bn_order_docs.gif)
![[Help on this site]](../../images/buttons/bn_site_help.gif)
![[How to contact us]](../../images/buttons/bn_comments.gif)
![[OpenVMS documentation]](../../images/ovmsdoc_sec_head.gif)
| Document revision date: 19 July 1999 | |
|
|
|
|
|
|
| Previous | Contents | Index |
This chapter lists and describes the OpenVMS Registry $REGISTRY and $REGISTRYW system services.
The $REGISTRY and $REGISTRYW system services are the interface to the OpenVMS Registry database server. The $REGISTRY service allows you to query, update, and set keys, subkeys, and values in the OpenVMS Registry database.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.
SYS$REGISTRY [efn], func, 0, itmlst, [iosb or iosa_64], [astadr or astadr_64], [astprm or astprm_64]
SYS$REGISTRYW [efn], func, 0, itmlst, [iosb or iosa_64], [astadr or astadr_64], [astprm or astprm_64]
efn
OpenVMS usage: ef_number type: longword (unsigned) access: read only mechanism: by value
Number of the event flag to be used by $REGISTRY. If you do not specify the event flag, the system defaults to EFN$C_ENF. The event flag is initially cleared by $REGISTRY and then set when the operation completes.func
OpenVMS usage: function_code type: longword (unsigned) access: read only mechanism: by value
Function code specifying the action that $REGISTRY is to perform. The func argument is a longword containing this function code. The function code can contain function modifiers. For more information on function modifiers, see the Function Modifiers section in this chapter.A single call to $REGISTRY can specify only one function code. All function codes require additional information to be passed in the call with the itmlst argument.
itmlst
OpenVMS usage: item_list3 or item_list_64b type: longword (unsigned) access: read only mechanism: by reference
Item list supplying information that the system will use to perform the function specified by the func argument. The itmlst argument is the address of the item list. The item list consists of one or more sets of item descriptors. Each descriptor is either an item-list-3 or item-list-64b format.Some function codes allow you specify multiple operations in a single call. In this case, you must place the REG$_SEPARATOR item code between each set of item codes. Each request, separated by a REG$_SEPARATOR item code, can contain the item codes in any order.
You can specify item codes as either input or output parameters. Input parameters modify functions, set context, or describe the information to be returned. Output parameters return the requested information. For item-list-3 lists, you must terminate the list with a longword of 0. For item-list-64b lists, you must terminate the list with a quadword of 0.
Figure 10-1 shows the structure of an item-list-3 descriptor.
Figure 10-1 Item-list-3 Structure
Figure 10-2 shows the structure of an item-list-64b descriptor.
Figure 10-2 Item-list-64b Structure
Table 10-1 defines the item descriptor fields.
| Descriptor Field | Definition |
|---|---|
| Buffer length | A word that specifies the length of the buffer. The buffer either supplies information to be used by $REGISTRY, or receives information from $REGISTRY. The required length of the buffer varies, depending on the item code specified. Each item code description specifies the required length. |
| Item code | A word containing a symbolic code that describes the type of information currently in the buffer or that is returned in the buffer. The buffer address field points to the location of the buffer. |
| Buffer address | A longword that contains the address of the buffer that specifies or receives the information. |
| Return length address | A longword that contains the address of a word that specifies the actual length in bytes of the information returned by $REGISTRY. The information resides in a buffer identified by the buffer address field. The field applies to output item list entries only, and must be 0 (zero) for input entries. If the return length address is 0, it is ignored. |
| OpenVMS usage: | status_block |
| type: | buffer |
| access: | write only |
| mechanism: | by reference |
When $REGISTRY begins execution, it clears the quadword I/O status block if you specify the iosb argument.
Although the iosb argument is optional, Compaq strongly recommends that you specify it for the following reasons:
The condition value returned in R0 and the condition value returned in the I/O status block provide information about different aspects of the call to the $REGISTRY service. The condition value returned in R0 provides information about the success or failure of the service call itself; the condition value returned in the I/O status block provides information about the success or failure of the service operation.
To assess the success or failure of the call to $REGISTRY accurately, you must first check the condition value returned in R0. If R0 contains a successful value, you must check the condition value in the I/O status block.
Table 10-2 defines the item descriptor fields.
| Descriptor Field | Definition |
|---|---|
| Status | A longword specifying the final status of the $REGISTRY service. If you request multiple operations for a function code, the system returns either SS$_NORMAL or SS$_REGERROR to iosb. This field is set to 0 (zero) when the operation begins. |
| Reserved | A reserved longword. |
| OpenVMS usage: | ast_procedure |
| type: | procedure value |
| access: | call without stack unwinding |
| mechanism: | by reference |
If the $REGISTRY service is not called successfully (that is, if it returns an error immediately), the AST routine is not executed.
| OpenVMS usage: | user_arg |
| type: | longword (unsigned) |
| access: | read only |
| mechanism: | by value |
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.
- $REGISTRYW
Function Codes Table 10-3 provides a summary of valid function codes, a brief description of their function, and the OpenVMS Registry rights identifier required to perform the function. You can find a detailed description of each item code in the Item Codes section of this chapter.
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$_EXBYTLM Exceeded byte count quota SS$_ILLEFC Illegal event flag number SS$_INSFARG Insufficient number of argument supplied SS$_INSFMEM Insufficient dynamic memory SS$_NORMAL Normal successful completion SS$_TOO_MANY_ARGS Too many arguments REG$_ACCESSDENIED Requested access to key is denied REG$_BADFILEVER Bad file version number REG$_BUFFEROVF Buffer overflow REG$_CANTCLEANVOLSEG Cannot clean the registry volatile segments REG$_CANTCONVCS Code set conversion error REG$_CANTOPENOUTFILE Cannot open the specified output file REG$_DBACCESS Cannot access registry database object REG$_DBALREADYLOADED Database is already loaded REG$_DBCREATE Cannot create registry database REG$_DBCSMISMATCH Database checksum mismatch: Stored=!XL Calculated=!XL REG$_DBFIND Cannot locate registry database REG$_DBFULL Registry database is full REG$_DBLOAD Cannot load registry database REG$_DBNOTYETLOADED Database is not yet loaded REG$_DBVERMISMATCH Database version mismatch: Current=V!UW.!UW Database=V!UW.!UW REG$_DELROOTKEY Root key was deleted REG$_DOUBLEDEALLOC Structure is already on the free list REG$_DTMUTEXERROR DECthreads mutex lock/unlock error REG$_DTMUTEXINIT DECthreads mutex init error !UL REG$_DTMUTEXLOCK DECthreads mutex lock error !UL REG$_DTMUTEXLOCKED DECthreads mutex is already held by another thread REG$_DTMUTEXUNLOCK DECthreads mutex unlock error !UL REG$_DTRWLOCKINIT DECthreads read/write lock init error !UL REG$_DTRWLOCKLOCK DECthreads read/write lock error !UL REG$_DTRWLOCKUNLOCK DECthreads read/write unlock error !UL REG$_DUPLREQUEST Work-in-progress hash table insert found duplicate request REG$_EXQUOTA Registry file quota or page file quota exceeded REG$_FILECREATE Error creating !AZ!AZ REG$_FILENAMEINVAL Invalid file name REG$_FILEOPEN Error opening !AZ!AZ REG$_FILEREADEOF Attempt to read past end of file; FTE !XL REG$_FNAMMISMATCH Physical/logical file name mismatch; FTE=!AZ LTE=!AZ REG$_FSOCORRUPT File was previously flagged as corrupt; FSO: !XL !XL REG$_FSOFILEINDEX Invalid file index in FSO: !XL !XL REG$_FSOOFFSET Invalid offset in FSO: !XL !XL REG$_FSOSEGNUMBER Invalid segment number in FSO: !XL !XL REG$_FSOSEGREADERR Error reading segment in FSO: !XL !XL REG$_FTEALLOC Error allocating file table entry !XL for !AZ REG$_FTEALREADYEXIST Cannot create file !AZ!AZ; file already exists REG$_FTEALREADYOPEN File is already open REG$_FTEDUPNAME Error allocating file table entry; duplicate file name REG$_FTEINSUFFINFO Specified file table entry is not allocated REG$_FTEINUSE Error allocating file table entry; entry in use REG$_FTENOTEXIST Specified file table entry does not exist REG$_FTENOTOPEN Specified file is not open REG$_FTIMISMATCH Physical file index mismatch; LTE = !XL, FTE = !XL 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$_INVLOG Invalid log file REG$_INVLOGREC Invalid log record REG$_INVPARAM Invalid parameter REG$_INVPATH Invalid key path REG$_INVSECDESCRIPTOR Invalid security descriptor REG$_INVSECPOLICY Invalid security policy parameter REG$_INVSEGNUM Invalid segment number REG$_INVVOLROOTKEY Cannot create a new file with a volatile root key REG$_IOREADERR Disk read error at block !UL for length !UL REG$_IOWRITERR Disk write error at block !UL for length !UL REG$_IPCCONACC IPC connect accept failure: !XL REG$_IPCCONREJ IPC connect reject failure: !XL REG$_IPCDCLAST IPC cannot declare AST for synch completion: !XL REG$_IPCOPEASS IPC open association failure: !XL REG$_IPLTOOHIGH Callers above IPL 0 cannot call this service REG$_KEYCHANGED Key or subkey has changed REG$_KEYEXIST Key already exists REG$_KEYLOCKED Key locked by another thread REG$_KEYNAMEEXIST Key name already exists REG$_LOGFILETABFULL Logical file table is full REG$_LTENOTEXIST Specified logical file table entry does not exist REG$_MOREDATA Buffer provided is too small for requested data REG$_NOBLOCKFOUND Registry database has no available blocks REG$_NOKEY Specified key does not exist REG$_NOMEMORY Insufficient memory REG$_NOMOREITEMS No more items for specified key REG$_NOMORESEG No more segments available REG$_NOMORESUBSTRING No substring found REG$_NOPATHFOUND Path not found REG$_NORESPONSE OpenVMS Registry server not available REG$_NOSUCHFILE No such file 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$_OBJWITHLINK Deleted key or value had link(s)pointing to it REG$_REQRECEIVED Received request for key change notification REG$_RESERVED Cannot delete or modify a reserved key or value REG$_ROOTINSFILE Insufficient file list in root file REG$_RUIDMISMATCH Root key UID mismatch; LTE = !@XQ !@XQ; Root key = !@XQ !@XQ REG$_SECVIO Violates the security access method specified when this key was last opened REG$_SEGREADERR Error reading segment !UL of file !AZ REG$_STRINGTOOLONG Input string too long REG$_STRINGTRUNC Output buffer is not large enough to contain the converted string REG$_SVRVERMISMATCH Version mismatch: Server=V!UL.!UL Database=V!UL.!UL REG$_SVRSHUTDOWN Server shutdown in progress REG$_TOOMANYOPENKEY Number of opened keys exceeds the limit; close some opened key REG$_UNKTHRREQ Unknown thread request code REG$_VALUEEXIST Value already exists REG$_VOLMISMATCH Cannot create nonvolatile subkey for a volatile key
The OpenVMS Registry identifier is required only if you do not provide a valid NT access token and you do not have the SYSPRV privilege. If you have a granted REG$UPDATE identifier, you can perform all the functions in Table 10-3.
| Function Code | Identifier | Description |
|---|---|---|
| REG$FC_CLOSE_KEY | REG$LOOKUP | Closes an open key or subkey. |
| REG$FC_CREATE_KEY | REG$UPDATE | Creates (and opens) a subkey. |
| REG$FC_DELETE_KEY | REG$UPDATE | Removes a subkey from a key. |
| REG$FC_DELETE_VALUE | REG$UPDATE | Removes a value from a key. |
| REG$FC_ENUM_KEY | REG$LOOKUP | Lists (enumerates) the subkeys of a key. |
| REG$FC_ENUM_VALUE | REG$LOOKUP | Lists (enumerates) the values of a key. |
| REG$FC_FLUSH_KEY | REG$UPDATE | Ensures that all information for the key is backed to disk. |
| REG$FC_MODIFY_KEY | REG$UPDATE | Modifies a key. |
| REG$FC_MODIFY_TREE_KEY | REG$UPDATE | Modifies a key and all its subkeys. |
| REG$FC_NOTIFY_CHANGE_KEY_VALUE | REG$UPDATE | Notifies when a key or value has changed. |
| REG$FC_OPEN_KEY | REG$LOOKUP | Opens a key or subkey. |
| REG$FC_QUERY_KEY | REG$LOOKUP | Fetches information about a key. |
| REG$FC_QUERY_VALUE | REG$LOOKUP | Fetches information about a value. |
| REG$FC_SEARCH_TREE_DATA | REG$LOOKUP | Searches the value data of key and its subkeys. |
| REG$FC_SEARCH_TREE_KEY | REG$LOOKUP | Searches the names of a key and its subkeys. |
| REG$FC_SEARCH_TREE_VALUE | REG$LOOKUP | Searches the values of a key and its subkeys. |
| REG$FC_SET_VALUE | REG$UPDATE | Changes the data associated with a value name. |
Item Codes Table 10-4 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.REG$FC_CLOSE_KEY
This request releases the open resources of the specified key. If REG$_KEYID indicates a predefined key, the system ignores the action and returns success.Specify the item codes as follows:
Item Code Required Parameter Type REG$_KEYID Yes Input REG$_RETURNSTATUS No Output REG$FC_CREATE_KEY
If the key does not exist, this request creates a new subkey under the key specified by REG$_KEYID. If the key does exist, the system does not modify it.If you specify the REG$_KEYRESULT item code, the system opens the specified subkey.
The system returns the result in the REG$_DISPOSITION item code buffer.
Using this function code, you can group multiple requests into a single call to the $REGISTRY service. To use the multiple-request feature, you must 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.
To set a value for a key, call the $REGISTRY service with the REG$FC_SET_VALUE function code.
Specify the item codes as follows:
Item Code Required Parameter Type REG$_CACHEACTION No Input REG$_CLASSNAME No Input (Pointer to Unicode string. Unicode character is 4 bytes long.) REG$_DISPOSITION No Output REG$_KEYFLAGS No Input REG$_KEYID Yes Input REG$_KEYRESULT No Output REG$_LINKPATH No Input (Pointer to Unicode string. Unicode character is 4 bytes long.) REG$_LINKTYPE No Input REG$_RETURNSTATUS No Output REG$_SECACCESS No Input REG$_SECURITYPOLICY No Input REG$_SEPARATOR No n/a REG$_SUBKEYNAME Yes Input (Pointer to Unicode string. Unicode character is 4 bytes long.) REG$_VOLATILE No Input If you specify the REG$_LINKPATH item code, it must point to a key path already defined in the OpenVMS Registry; otherwise the system returns the REG$_INVALIDPATH error.
Note
If you do not specify the REG$_CACHEACTION item code, the new key is created with the same cache action value as the parent key. The same rule applies to the REG$_VOLATILE and REG$_SECURITYPOLICY item codes.REG$FC_DELETE_KEY
This request removes the specified subkey and its values from the OpenVMS Registry database. If the specified key has subkeys, the key is not deleted. You must delete the subkeys first.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.
Specify the item codes as follows:
Item Code Required Parameter Type REG$_KEYID Yes Input REG$_KEYPATH No Input (Pointer to Unicode string. Unicode character is 4 bytes long.) REG$_RETURNSTATUS No Output REG$_SEPARATOR No n/a REG$_SUBKEYNAME Yes Input (Pointer to Unicode string. Unicode character is 4 bytes long.) REG$FC_DELETE_VALUE
This request deletes the specified value from the key.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.
Specify the item codes as follows:
Item Code Required Parameter Type REG$_KEYID Yes Input REG$_KEYPATH No Input (Pointer to Unicode string. Unicode character is 4 bytes long.) REG$_RETURNSTATUS No Output REG$_SEPARATOR No n/a REG$_VALUENAME Yes Input REG$FC_ENUM_KEY
This request retrieves information about one subkey of the key. You identify the subkey in the REG$_SUBKEYINDEX item code. To enumerate all the key's subkeys, the application must call the $REGISTRY service repeatedly using the REG$FC_ENUM_KEY function code. Begin with a REG$_SUBKEYINDEX of zero, then increment the count until the request returns a REG$_NOMOREITEMS error.Specify the item codes as follows:
Item Code Required Parameter Type REG$_CACHEACTION No Output REG$_CLASSNAME No Output (Pointer to Unicode string. Unicode character is 4 bytes long.) REG$_KEYFLAGS No Output REG$_KEYID Yes Input REG$_KEYPATH No Input (Pointer to Unicode string. Unicode character is 4 bytes long.) REG$_LASTWRITE No Output REG$_LINKCOUNT No Output REG$_LINKPATH No Output (Pointer to Unicode string. Unicode character is 4 bytes long.) REG$_LINKTYPE No Output REG$_RETURNSTATUS No Output REG$_SECURITYPOLICY No Output REG$_SUBKEYINDEX Yes Input REG$_SUBKEYNAME No Output (Pointer to Unicode string. Unicode character is 4 bytes long.) REG$_VOLATILE No Output REG$FC_ENUM_VALUE
This request retrieves information about a value of the specified key identifier. The value to retrieve is identified in the REG$_VALUEINDEX item code.To enumerate all a key's values, the application must call the $REGISTRY service repeatedly using the REG$FC_ENUM_VALUE function code. Begin with a REG$_VALUEINDEX of zero, then increment the count until the request returns a REG$_NOMOREITEMS error.
Specify the item codes as follows:
Item Code Required Parameter Type REG$_DATAFLAGS No Output REG$_DATATYPE No Output REG$_KEYID Yes Input REG$_KEYPATH No Input (Pointer to Unicode string. Unicode character is 4 bytes long.) REG$_RETURNSTATUS No Output REG$_VALUEDATA No Output REG$_VALUEINDEX Yes Input REG$_VALUENAME No Output REG$_VOLATILE No Output REG$FC_FLUSH_KEY
This request writes all the information about a specified key to disk. This request returns only after the operation is complete and all attributes of the key have been written to the OpenVMS Registry database.Specify the item codes as follows:
Item Code Required Parameter Type REG$_KEYID Yes Input REG$_KEYPATH No Input (Pointer to Unicode string. Unicode character is 4 bytes long.) REG$_RETURNSTATUS No Output REG$FC_MODIFY_KEY
This request modifies a specified key's attributes.Specify the item codes as follows:
Item Code Required Parameter Type REG$_CACHEACTION No Input REG$_CLASSNAME No Input (Pointer to Unicode string. Unicode character is 4 bytes long.) REG$_KEYFLAGS 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$_NEWNAME No Input REG$_RETURNSTATUS No Output REG$_SECURITYPOLICY No Input To remove the link from the specified key, enter a REG$_LINKPATH item code with an address of zero. You cannot add a link to a key that has either values or subkeys (or both).
REG$FC_MODIFY_TREE_KEY
This request modifies a specified key and all its subkey attributes. No link will be followed or modified.Specify the item codes as follows:
Item Code Required Parameter Type REG$_CACHEACTION No Input REG$_CLASSNAME No Input (Pointer to Unicode string. Unicode character is 4 bytes long.) REG$_KEYID Yes Input REG$_KEYPATH No Input (Pointer to Unicode string. Unicode character is 4 bytes long.) REG$_RETURNSTATUS No Output REG$_SECURITYPOLICY No Input REG$FC_NOTIFY_CHANGE_KEY_VALUE
This request notifies the calling process when a specified key or any of its subkeys has changed. That is, the requested function waits for the specified condition before returning.Specify the item codes as follows:
Item Code Required Parameter Type REG$_FLAGSUBKEY Yes Input REG$_KEYID Yes Input REG$_KEYPATH No Input (Pointer to Unicode string. Unicode character is 4 bytes long.) REG$_NOTIFYFILTER Yes Input REG$_RETURNSTATUS No Output REG$FC_OPEN_KEY
This request opens the specified key. If you do not specify a subkey, the system opens the key specified in REG$_KEYID. If REG$_KEYID specifies a key other than a predefined key, the system opens the key again (duplicates the key).Specify the item codes as follows:
Item Code Required Parameter Type REG$_KEYID Yes Input REG$_KEYRESULT Yes Output REG$_KEYPATH No Input (Pointer to Unicode string. Unicode character is 4 bytes long.) REG$_RETURNSTATUS No Output REG$_SECACCESS Yes Input REG$_SUBKEYNAME No Input (Pointer to Unicode string. Unicode character is 4 bytes long.) REG$FC_QUERY_KEY
This request retrieves attributes about a specified key.Specify the item codes as follows:
Item Code Required Parameter Type REG$_CACHEACTION No Output REG$_CLASSNAME No Output (Pointer to Unicode string. Unicode character is 4 bytes long.) REG$_CLASSNAMEMAX No Output REG$_KEYFLAGS No Output REG$_KEYID Yes Input REG$_KEYPATH No Input (Pointer to Unicode string. Unicode character is 4 bytes long.) REG$_LASTWRITE No Output REG$_LINKCOUNT No Output REG$_LINKPATH No Output (Pointer to Unicode string. Unicode character is 4 bytes long.) REG$_LINKTYPE No Output REG$_RETURNSTATUS No Output REG$_SECURITYPOLICY No Output REG$_SUBKEYNAMEMAX No Output REG$_SUBKEYSNUMBER Yes Output REG$_VALUEDATAMAX No Output REG$_VALUENAMEMAX No Output REG$_VALUENUMBER No Output REG$_VOLATILE No Output REG$FC_QUERY_VALUE
This request retrieves the type, data flags, and data for the specified value name.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.
Specify the item codes as follows:
Item Code Required Parameter Type REG$_DATAFLAGS No Output REG$_DATATYPE No Output REG$_KEYPATH No Input (Pointer to Unicode string. Unicode character is 4 bytes long.) REG$_KEYID Yes Input REG$_LINKCOUNT No Output REG$_LINKPATH No Output (Pointer to Unicode string. Unicode character is 4 bytes long.) REG$_LINKTYPE No Output REG$_RETURNSTATUS No Output REG$_SEPARATOR No n/a REG$_VALUEDATA No Output REG$_VALUENAME Yes Input REG$_VOLATILE No Output REG$FC_SEARCH_TREE_DATA
This request scans a specified key and all its descendants for a match with a specified set of data information. The set of data information can be either the REG$_DATAFLAGS item code, or the pair REG$_DATATYPE and REG$_VALUEDATA item codes, or all three item codes.The REG$_FLAGOPCODE item code specifies how the REG$_DATAFLAGS item code should be matched against the database. (See the item codes description for more information about the REG$_FLAGOPCODE item code.)
Every time the system finds a match, it appends the path name relative to the specified key to the REG$_PATHBUFFER item code. A Unicode null character is used to separate the value path names.
If the buffer supplied by the application is not big enough to hold all the value path names found, the system returns the SS$_BUFFEROVF error message in the iosb argument, and the length required to complete the operation successfully is returned in the REG$_REQLENGTH item (if specified).
Use the ellipsis (...) wildcard to match zero or more subkeys in the REG$_KEYPATH item code. (For example, Hardware\...\disks finds all the paths that start with the Hardware subkey and end with the disk subkey, with zero or more subkeys in between.) Use the asterisk (*) wildcard to match an entire subkey or a portion of a subkey in the REG$_KEYPATH item code. Use the percent (%) wildcard to match one character in a key name in the REG$_KEYPATH item code.
Specify the item codes as follows:
Item Code Required Parameter Type REG$_DATAFLAGS No Input REG$_DATATYPE No Input REG$_FLAGOPCODE No Input 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$_VALUEDATA No Input REG$FC_SEARCH_TREE_KEY
This request scans a specified key and all its descendants for a specified key path.For this function code, a valid key path is a Unicode string that can include the ellipsis (...), asterisk (*), or percent (%) wildcard character, but that cannot start with the backslash character (\).
Use the ellipsis (...) wildcard to match zero or more subkeys in the REG$_KEYPATH item code. (For example, Hardware\...\disks finds all the paths that start with the Hardware subkey and end with the disk subkey, with zero or more subkeys in between.) Use the asterisk (*) wildcard to match an entire subkey or a portion of a subkey in the REG$_KEYPATH item code. Use the percent (%) wildcard to match one character in a key name in the REG$_KEYPATH item code.
An example of a valid key path is as follows:
hardware\system\*\disk%%Every time the system finds a match, the system appends its path name relative to the specified key identifier to the REG$_PATHBUFFER item code. A Unicode null character (4 bytes) separates the subkey path names.
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$_KEYID Yes Input REG$_KEYPATH No Input (Pointer to Unicode string. Unicode character is 4 bytes long.) REG$_PATHBUFFER Yes Output REG$_REQLENGTH No Output REG$_RETURNSTATUS No Output REG$FC_SEARCH_TREE_VALUE
This request scans a specified key and all its descendants for a specified value name.For this function code a valid key name is a Unicode string that can include the ellipsis (...), asterisk (*), or percent (%) wildcard character, but cannot start with the backslash character (\).
Use the ellipsis (...) wildcard to match zero or more subkeys in the REG$_KEYPATH item code. (For example, Hardware\...\disks finds all the paths that start with the Hardware subkey and end with the disk subkey, with zero or more subkeys in between.) Use the asterisk (*) wildcard to match an entire subkey or a portion of a subkey in the REG$_KEYPATH item code. Use the percent (%) wildcard to match one character in a key name in the REG$_KEYPATH item code.
An example of a valid key path is as follows:
hardware\system\...For this function code, a valid name is a Unicode string that can include the asterisk (*) and percent (%) wildcard characters.
Every time the system finds a match, the system appends its path name relative to the specified key identifier to the REG$_PATHBUFFER item code. A Unicode null character (4 bytes) separates the subkey path names.
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
This request sets value and type information for a specified key.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 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$_FILELOAD | Input | Unicode string |
| REG$_FLAGOPCODE | Input | Longword |
| REG$_FLAGSUBKEY | Input | Longword |
| REG$_KEYPATH | Input | (Pointer to Unicode string. Unicode character is 4 bytes long.) |
| REG$_KEYFLAGS | Input, output | Longword |
| REG$_KEYID | Input, output | Longword |
| 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$_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
Previous Next Contents Index
privacy and legal statement 6539PRO_005.HTML