|
HP OpenVMS Systems Documentation |
|
OpenVMS System Services Reference Manual
You must have read access to the directory. You must specify the following input value item code: DNS$_DIRECTORY You must specify the following output value item code: DNS$_OUTOBJECTS You can specify the following input value item codes: DNS$_CLASSFILTER You can specify the following output value item code: DNS$_CONTEXTVARNAME $DNS returns the following qualifying status: DNS$V_DNSB_OUTLINKED DNS$_ENUMERATE_SOFTLINKSThis request takes as input the name of a directory and a wildcarded simple name. The DECdns clerk matches these against soft links in the directory. It returns (in DNS$_OUTSOFTLINKS) a set consisting of simple names of soft links in the directory that match the wildcarded name. If no soft link entries match the wildcard or the directory contains no soft links, a null set is returned.If no wildcard is specified, then all soft links in the directory are returned. To manipulate the values returned by this call, use the DNS$REMOVE_FIRST_SET_VALUE run-time library routine. The value returned is a simple name. The clerk enumerates soft links in alphabetical order. If the call returns DNS$_MOREDATA, not all matching soft links have been enumerated and the client should make further calls, setting DNS$_CONTEXTVARNAME to the last soft link in the set returned, until the procedure returns SS$_NORMAL. This function code returns the following: SS$_NORMAL You must have read access to the directory. You must specify the following input value item code: DNS$_DIRECTORY You must specify the following output value item code: DNS$_OUTSOFTLINKS You can specify the following input value item codes: DNS$_CONF You can specify the following output value item code: DNS$_CONTEXTVARNAME $DNS returns the following qualifying status: DNS$V_DNSB_OUTLINKED DNS$_FULL_OPAQUE_TO_STRINGThis request converts a full name in opaque format to its equivalent in string format. To prevent the namespace nickname from being included in the string name, set the byte referred to by DNS$_SUPPRESS_NSNAME to 1.This function code returns the following: SS$_NORMAL You must specify the following input value item code: DNS$_FROMFULLNAME You must specify the following output value item code: DNS$_TOSTRINGNAME You can specify the following input value item code: DNS$_SUPPRESS_NSNAME DNS$_MODIFY_ATTRIBUTEThis request applies one update to the specified entry in the namespace. The update operations are as follows:
To add a value to a single-valued or set-valued attribute, specify a value in the DNS$_MODVALUE item code. If you do not specify a value for a single-valued attribute, you receive the error DNS$_INVALIDUPDATE. Single-valued attributes cannot exist without a value. If you do not specify a value for a set-valued attribute, the clerk creates the attribute with an empty set. To delete an attribute value, use the DNS$_MODVALUE item code to remove the specified value from an attribute set. If you do not specify the item code, the name service removes the attribute and all its values. This function code returns the following: SS$_NORMAL You must have write or delete access to the directory, object, soft link, or clearinghouse whose attribute is being modified, depending on whether the operation adds or removes the attribute. You must specify the following input value item codes: DNS$_ATTRIBUTENAME You can specify the following input value item codes: DNS$_CONF $DNS returns the following qualifying status: DNS$V_DNSB_OUTLINKED DNS$_NEW_EPOCHThis request reconstructs an entire replica set of a directory and synchronizes the copies to recover as much of the original directory state as possible. You can also use the function to change a replica type for configuration management purposes.This request takes as input the full name of a clearinghouse (DNS$_CLEARINGHOUSE) and directory (DNS$_DIRECTORY). Specify, optionally, the full names of clearinghouses in which to store secondary and read-only replicas (DNS$_SECCHSET and DNS$_READCHSET). You must have control access to the parent directory and write access to each clearinghouse for which the replica type will be changed from its current value to a new value. You must specify the following input value item codes: DNS$_CLEARINGHOUSE You can specify the following input value item codes: DNS$_READCHSET DNS$_PARSE_FULLNAME_STRINGThis request takes a full name in string format and converts it to its equivalent in opaque format. If you specify the DNS$_NEXTCHAR_PTR item code, the clerk examines the name specified in DNS$_FROMSTRINGNAME for invalid characters. The buffer returns the address of the character in the name that immediately follows a valid DECdns name.This function code returns the following: SS$_NORMAL You must specify the following input value item code: DNS$_FROMSTRINGNAME You must specify the following output value item code: DNS$_TOFULLNAME You can specify the following input value item code: DNS$_NEXTCHAR_PTR DNS$_PARSE_SIMPLENAME_STRINGThis request takes a simple name in string format and converts it to its equivalent in opaque format. If you specify the DNS$_NEXTCHAR_PTR item code, the clerk examines the name specified in DNS$_FROMSTRINGNAME for invalid characters. The buffer returns the address of the character in that name that immediately follows a valid DECdns name.This function code returns the following: SS$_NORMAL You must specify the following input value item code: DNS$_FROMSTRINGNAME You must specify the following output value item code: DNS$_TOSIMPLENAME You can specify the following input value item code: DNS$_NEXTCHAR_PTR DNS$_READ_ATTRIBUTEThis request returns (in DNS$_OUTVALSET) a set whose members are the values of the specified attribute.To manipulate the values returned by this call, use the DNS$REMOVE_FIRST_SET_VALUE run-time library routine. The run-time library routine returns the value of a single-valued attribute or the first value from a set-valued attribute. The contents of DNS$_OUTVALSET are passed to DNS$REMOVE_FIRST_SET_VALUE, and the routine returns the value of the attribute. The attribute values are returned in the order in which they were created. If the call returns DNS$_MOREDATA, not all of the set members have been returned. The client application can make further calls, setting DNS$_CONTEXTVARTIME to the timestamp of the last attribute in the set returned, until the procedure returns SS$_NORMAL. If the client sets the DNS$_MAYBEMORE item code to 1, the name service attempts to make subsequent DNS$_READ_ATTRIBUTE calls for the same value more efficient. This function code returns the following: SS$_NORMAL You must have read access to the object whose attribute is to be read. You must specify the following input value item codes: DNS$_ATTRIBUTENAME You must specify the following output value item code: DNS$_OUTVALSET You can specify the following input value item codes: DNS$_CONF You can specify the following output value item code: DNS$_CONTEXTVARTIME $DNS returns the following qualifying status: DNS$V_DNSB_OUTLINKED DNS$_REMOVE_LINKThis request deletes a soft link from the namespace. Only the soft link is deleted. Any DECdns name that is referenced by the soft link remains unaffected by the operation.You must have delete access to the soft link, or delete or control access to its parent directory. You must specify the following input value item code: DNS$_LINKNAME You can specify the following input value item codes: DNS$_CONF DNS$_REMOVE_REPLICAThis request removes the specified replica of a directory.You must have control access to the replica being removed and write access to the replica's clearinghouse. You must specify the following input value item codes: DNS$_CLEARINGHOUSE You can specify the following input value item codes: DNS$_CONF DNS$_RESOLVE_NAMEThis request follows a chain of soft links to its target. The function returns the full name of the target.Applications that maintain their own databases of opaque DECdns names should use DNS$_RESOLVE_NAME any time they receive the qualifying status DNS$V_DNSB_OUTLINKED. The qualifying status indicates that a soft link was followed to make the request to the DECdns server. After receiving the resolved name, the application should store it, so future references to the name do not incur the overhead of following a soft link. If the application provides a name that does not contain any soft links, DNS$_NOTLINKED status is returned. If the target of any of the chain of soft links followed does not exist, the DNS$_DANGLINGLINK status is returned. To obtain the target of any particular soft link, use the DNS$_READ_ATTRIBUTE function with DNS$_LOOKINGFOR set to DNS$K_SOFTLINK and request the attribute DNS$LINKTARGET. This can be useful in discovering which link in a chain does not point to an existing target. If the DECdns clerk detects a loop, it returns DNS$_POSSIBLECYCLE status. This function code returns the following: SS$_NORMAL You must have read access to each of the soft links in the chain. You must specify the following input value item code: DNS$_LINKNAME You must specify the following output value item code: DNS$_OUTNAME You can specify the following input value item codes: DNS$_CONF $DNS returns the following qualifying status: DNS$V_DNSB_OUTLINKED DNS$_SIMPLE_OPAQUE_TO_STRINGThis request takes a simple name in opaque format and converts it to its equivalent in string format.This function code returns the following: SS$_NORMAL You must specify the following input value item code: DNS$_FROMSIMPLENAME You must specify the following output value item code: DNS$_TOSTRINGNAME DNS$_SKULKThis request attempts to ensure that all replicas of the specified directory have absorbed all updates applied to any replica prior to the time the skulk began. Successful update of the replica set requires all replicas to be available for an extended time.You must have control access to the directory being skulked. You must specify the following input value item code: DNS$_DIRECTORY DNS$_TEST_ATTRIBUTEThis request tests an object for the presence of a particular attribute value. This function returns DNS$_TRUE in the $DNS status block if the specified attribute has one of the following characteristics:
If the attribute is not present or if the specified attribute does not exist, the function returns DNS$_FALSE in the $DNS status block. This function code returns the following: DNS$_INVALID_ENTRYNAME You must have test or read access to the directory, object, soft link, or clearinghouse whose attribute is to be tested. You must specify the following input value item codes: DNS$_ATTRIBUTENAME You can specify the following input value item codes: DNS$_CONF $DNS returns the following qualifying status: DNS$V_DNSB_OUTLINKED DNS$_TEST_GROUPThis request tests a group object for a particular member. It returns DNS$_TRUE in the $DNS status block if the specified member is a member of the specified group (or a subgroup thereof), and DNS$_FALSE otherwise. If the clerk searches a subgroup and one or more of the subgroups is unavailable, the clerk returns the status encountered in trying to access that group.The DNS$_INOUTDIRECT argument, on input, controls the scope of the search. If you set this item code to 1, the clerk searches only the top-level group. If you set it to 0, the clerk searches all of the subgroups. On output, the clerk returns a 1 in the DNS$V_DNSB_INOUTDIRECT qualifying status if the member was found in the top-level group; it returns a 0 if the member was found in a subgroup. This function code returns the following: SS$_NORMAL You must have test or read access to each of the groups being tested or control access to their respective directories. You must specify the following input value item codes: DNS$_GROUP You can specify the following input value item codes: DNS$_CONF $DNS returns the following qualifying status: DNS$V_DNSB_INOUTDIRECTItem Codes Table SYS-8 provides a summary of item codes that are valid as an item descriptor in the itmlst argument. The table lists the item codes and their data types. Complete descriptions of each item code are provided after the table.
This section describes each item code.
|