![[OpenVMS documentation]](../../images/openvms_doc_banner_top.gif)
|
![[Site home]](../../images/buttons/bn_site_home_off.gif)
![[Send comments]](../../images/buttons/bn_comments_off.gif)
![[Help with this site]](../../images/buttons/bn_site_help_off.gif)
![[How to order documentation]](../../images/buttons/bn_order_docs_off.gif)
![[OpenVMS site]](../../images/buttons/bn_openvms_off.gif)
![[Compaq site]](../../images/buttons/bn_compaq_off.gif)
|
| Updated: 11 December 1998 |
|
|
|
|
| Updated: 11 December 1998 |
OpenVMS System Services Reference Manual
| Previous | Contents | Index |
This section describes each item code.
DNS$_ATTRIBUTENAME
The DNS$_ATTRIBUTENAME item code specifies the opaque simple name of an attribute. An attribute name cannot be longer than 31 characters.DNS$_ATTRIBUTETYPE
The DNS$_ATTRIBUTETYPE item code specifies whether an attribute is set valued (DNS$K_SET) or single valued (DNS$K_SINGLE).DNS$_CLASS
The DNS$_CLASS item code specifies the DNS$Class attribute of an object for the $DNS function DNS$_CREATE_OBJECT. DNS$_CLASS is an opaque simple name.DNS$_CLASSFILTER
DNS$_CLASSFILTER specifies a filter that limits the scope of an enumeration to those objects belonging to a certain class or group of classes. DNS$_CLASSFILTER is used by the $DNS function DNS$_ENUMERATE_OBJECTS. DNS$_CLASSFILTER is an opaque simple name, which can contain a wildcard (either the asterisk or question mark).DNS$_CLASSFILTER is optional. A wildcard simple name using an asterisk (*) is used by default, meaning that objects of all classes are enumerated.
DNS$_CLEARINGHOUSE
DNS$_CLEARINGHOUSE specifies the clearinghouse in which the directory will be added or removed. DNS$_CLEARINGHOUSE is an opaque full name.DNS$_CONF
DNS$_CONF specifies for $DNS whether to use the clerk's cache or a DECdns server to complete the request. DNS$_CONF is 1 byte long and can take one of the following values:
Confidence Level Description DNS$K_LOW On read requests, services the DECdns request from the clerk's cache. On create or modify requests, services the request from a master or secondary directory. DNS$K_MEDIUM Bypasses any cached information and services the request directly from a DECdns server. DNS$K_HIGH Services the request from the master directory. DNS$_CONF is optional; if it is not specified, the DECdns clerk assumes a value of DNS$K_LOW.
DNS$_CONTEXTVARNAME
DNS$_CONTEXTVARNAME specifies and returns a context for the enumeration functions. On input, specify null to set the initial context. On output, DNS$_CONTEXTVARNAME returns the opaque simple name of the last item enumerated.DNS$_CONTEXTVARNAME is optional. If you do not specify or you specify a null value for the context variable item, the clerk returns the results from the beginning of the set. To restart an enumeration where it left off, specify the last value returned in DNS$_CONTEXTVARNAME.
DNS$_CONTEXTVARTIME
DNS$_CONTEXTVARTIME specifies and returns a timestamp for the DNS$_READ_ATTRIBUTE function. On input, specify a timestamp to set up the context for reading attributes. On output, DNS$_CONTEXTVARNAME returns the timestamp of the last item read.DNS$_CONTEXTVARTIME is optional. If you do not specify or you specify a null value for the context variable item, the clerk returns the results from the beginning of the set. To restart a read operation where it left off, specify the last value returned in DNS$CONTEXTVARTIME.
DNS$_DIRECTORY
DNS$_DIRECTORY specifies the directory in which the child directories, soft links, or objects to be enumerated reside. DNS$_DIRECTORY is an opaque full name.DNS$_ENTRY
DNS$_ENTRY specifies the opaque full name of an object, soft link, directory, or clearinghouse in the namespace.DNS$_EXPIRETIME
DNS$_EXPIRETIME specifies the absolute time when the soft link will expire. The clerk deletes the soft link at the expiration time. If this item code is a null value, the clerk neither checks nor deletes the link.DNS$_EXTENDTIME
DNS$_EXTENDTIME specifies an extension factor to be added to the absolute time if the soft link still exists. A new expiration time is created by adding the expiration time and the extend time together.DNS$_FROMFULLNAME
DNS$_FROMFULLNAME specifies for the DNS$_FULL_OPAQUE_TO_STRING function the opaque full name that is to be converted into string format.DNS$_FROMSIMPLENAME
DNS$_FROMSIMPLENAME specifies for the DNS$_SIMPLE_OPAQUE_TO_STRING function the opaque simple name that is to be converted into string format.DNS$_FROMSTRINGNAME
DNS$_FROMSTRINGNAME specifies, in string format, a simple or full name that is to be converted to opaque format for the parse functions DNS$_PARSE_FULLNAME_STRING and DNS$_PARSE_SIMPLENAME_STRING.DNS$_GROUP
DNS$_GROUP specifies for the DNS$_TEST_GROUP function the opaque full name of the group that is to be tested. DNS$_GROUP must be the name of a group object.DNS$_INOUTDIRECT
DNS$_INOUTDIRECT specifies a value that controls the scope of a test for group membership.
Value Definition 1 Tests the top-level group specified by the DNS$_GROUP item (the default) 0 Tests all subgroups of the group named in DNS$_GROUP DNS$_INOUTDIRECT is a single-byte value.
DNS$_LINKNAME
DNS$_LINKNAME specifies the opaque full name of a soft link.DNS$_LOOKINGFOR
DNS$_LOOKINGFOR specifies the type of entry in the namespace on which the call is to operate. DNS$_LOOKINGFOR can take one of the following values:
- DNS$K_DIRECTORY
- DNS$K_OBJECT
- DNS$K_CHILDDIRECTORY
- DNS$K_SOFTLINK
- DNS$K_CLEARINGHOUSE
DNS$_MAYBEMORE
DNS$_MAYBEMORE is used with the DNS$_READ_ATTRIBUTE function to indicate that the results of the read operation are to be cached. This is a single-byte item.When this item is set to 1, the clerk returns all of the entry's attributes in the return buffer. The clerk caches all of this information to make later lookups of attribute information for the same entry quicker and more efficient.
If you do not specify this item, only the requested information is returned.
DNS$_MEMBER
DNS$_MEMBER specifies for the DNS$_TEST_GROUP function of $DNS the opaque full name of a member that is to be tested for inclusion within a given group.DNS$_MODOPERATION
DNS$_MODOPERATION specifies for the DNS$_MODIFY_ATTRIBUTE function the type of operation that is to take place. There are two types of modifications: adding an attribute or deleting an attribute. To add an attribute, specify DNS$K_PRESENT. To delete an attribute, specify DNS$K_ABSENT.DNS$_MODVALUE
DNS$_MODVALUE specifies for the DNS$_MODIFY_ATTRIBUTE function the value that is to be added to or deleted from an attribute. The structure of this value is dependent on the application.DNS$_MODVALUE is an optional argument that affects the overall operation of the DNS$_MODIFY_ATTRIBUTE function. Note that the DNS$_MODVALUE item code must be specified to add a single-valued attribute. You can specify a null value for a set-valued attribute. (See the DNS$_MODIFY_ATTRIBUTE item code description for more information.)
DNS$_NEXTCHAR_PTR
DNS$_NEXTCHAR_PTR is an optional item code that can be used with the parse functions DNS$_PARSE_FULLNAME_STRING and DNS$_PARSE_SIMPLENAME_STRING to return the address of an invalid character that immediately follows a valid DECdns name. This option is most useful when applications are parsing command line strings.Without this item code, the parse functions return an error if any portion of the name string is invalid.
DNS$_OBJECTNAME
DNS$_OBJECTNAME specifies the opaque full name of an object.DNS$_OUTATTRIBUTESET
DNS$_OUTATTRIBUTESET returns a set of enumerated attribute names. This item code is used with the DNS$_ENUMERATE_ATTRIBUTES functions. The item code returns either DNS$K_SET or DNS$K_SINGLE along with the set of attribute names.The names returned in this set can be extracted from the buffer with the DNS$REMOVE_FIRST_SET_VALUE routine. The resulting values are contained in the $DNSATTRSPECDEF structure. This 1-byte structure indicates whether an attribute is set-valued or single-valued followed by an opaque simple name.
DNS$_OUTCHILDREN
DNS$_OUTCHILDREN returns the set of opaque simple names enumerated by the DNS$_ENUMERATE_CHILDREN function.You can extract the values resulting from the enumeration using the DNS$REMOVE_FIRST_SET_VALUE run-time library routine. These values are the opaque simple names of the child directories found in the parent directory.
DNS$_OUTCTS
DNS$_OUTCTS returns the creation timestamp (CTS) that the specified entry received when it was created. This item code is optional and can be used by the $DNS create functions.DNS$_OUTNAME
DNS$_OUTNAME returns the opaque full name of the target pointed to by a soft link. This item code is used with the DNS$_RESOLVE_NAME function.DNS$_OUTOBJECTS
DNS$_OUTOBJECTS returns the set of opaque simple names enumerated by the DNS$_ENUMERATE_OBJECTS function.Each object name is followed by the object's class if you specify the DNS$_RETURNCLASS item code on input. The object's class is the value of the DNS$Class attribute.
You can extract the values resulting from the enumeration using the DNS$REMOVE_FIRST_SET_VALUE run-time library routine. The resulting values are the opaque simple names of the objects found in the directory.
DNS$_OUTSOFTLINKS
DNS$_OUTSOFTLINKS returns the set of opaque simple names enumerated by the DNS$_ENUMERATE_SOFTLINKS function.You can extract the values resulting from the enumeration using the DNS$REMOVE_FIRST_SET_VALUE run-time library routine. The resulting values are the opaque simple names of the soft links found in the directory.
DNS$_OUTVALSET
DNS$_OUTVALSET returns for the DNS$_READ_ATTRIBUTE function a set of values for the given attribute.You can extract the values resulting from the enumeration using the DNS$REMOVE_FIRST_SET_VALUE run-time library routine. The extracted values are the values of the attribute.
DNS$_READCHSET
DNS$_READCHSET specifies the names of clearinghouses that contain read-only replicas of the directory being reconstructed with DNS$_NEW_EPOCH.DNS$_REPLICATYPE
DNS$_REPLICATYPE specifies the type of directory replica being added in the specified clearinghouse. You can add a secondary replica (DNS$K_SECONDARY) or a read-only replica (DNS$K_READONLY).DNS$_RETURNCLASS
DNS$_RETURNCLASS specifies that the class of object entries enumerated with the DNS$_ENUMERATE_OBJECTS function should be returned along with the object names in the DNS$_OUTOBJECTS item code. The object's class is the value of the DNS$Class attribute.DNS$_SECCHSET
DNS$_SECCHSET specifies the names of clearinghouses that contain secondary replicas of the directory being reconstructed with DNS$_NEW_EPOCH.DNS$_SUPPRESS_NSNAME
DNS$_SUPPRESS_NSNAME specifies that the leading namespace name should not be returned in the converted full name string. This item code is used by the DNS$_FULL_OPAQUE_TO_STRING function. This is an optional single-byte value.A value of 1 suppresses the leading namespace name in the resulting full name string.
DNS$_TARGETNAME
DNS$_TARGETNAME specifies the name of an existing entry in the namespace to which the soft link will point. This item code is used by the DNS$_CREATE_LINK function.DNS$_TOFULLNAME
DNS$_TOFULLNAME returns for the DNS$_PARSE_FULLNAME_STRING function the address of a buffer that contains the resulting opaque full name.DNS$_TOSIMPLENAME
DNS$_TOSIMPLENAME specifies for the DNS$_PARSE_SIMPLENAME_STRING function the address of a buffer that will contain the resulting opaque simple name.DNS$_TOSTRINGNAME
DNS$_TOSTRINGNAME returns the string name resulting from one of the conversion functions: DNS$_FULL_OPAQUE_TO_STRING or DNS$_SIMPLE_OPAQUE_TO_STRING. DNS$_TOSTRINGNAME has the following structure:
[NS_name:] [.] Namestring [.Namestring]
- NS_name, if present, is a local system representation of the namespace creation timestamp (NSCTS), the unique identifier of the DECdns server. The DECdns clerk supplies a namespace name (node-name_NS) if the value is omitted.
- Namestring represents a simple name component. Multiple simple names are separated by periods.
DNS$_VALUE
DNS$_VALUE specifies for the DNS$_TEST_ATTRIBUTE function the value that is to be tested. This item contains the address of a buffer holding the value.DNS$_VERSION
DNS$_VERSION specifies the DNS$ClassVersion attribute for the DNS$_CREATE_OBJECT function. This is a 2-byte structure: the first byte contains the major version number, the second contains the minor version number.DNS$_WAIT
DNS$_WAIT enables the client to specify a timeout value to wait for a call to complete. If the timeout expires, the call returns either DNS$K_TIMEOUTNOTDONE or DNS$K_TIMEOUTMAYBEDONE, depending on whether the namespace was updated by the incomplete operation.The parameter is optional; if it is not specified, a default timeout value of 30 seconds is assumed.
DNS$_WILDCARD
DNS$_WILDCARD is an optional item code that specifies to the enumeration functions of $DNS the opaque simple name used to limit the scope of the enumeration. (The simple name does not have to use a wildcard.) Only those simple names that match the wildcard are returned by the enumeration.
Table SYS-7 provides a summary of the data types for $DNS item codes. The data types define the encoding of each item list element.
The $DNS system service provides a low-level interface between an application (client) and DECdns. The DECdns clerk interface is used to create, delete, modify, and retrieve DECdns names in a namespace.A single system service call supports the DECdns clerk. It has two main parameters:
- A function code identifying the specific service to perform
- An item list specifying all the parameters for the required function
The use of this item list is similar to that of other system services that use a single item list for both input and output operations.
The $DNS system service performs DECnet I/O on behalf of the DECdns client. It requires system dynamic memory to construct a database to queue the I/O request and might require additional memory on a device-dependent basis.
In addition to the system services, DECdns provides a set of callable run-time library routines. You can use the clerk run-time library routines to manipulate output from the system service and to write data that can be specified in a system service function code.
For further information, see the OpenVMS Programming Concepts Manual.
None
- The buffered I/O byte count (BYTLM) quota for the process
- The quota for buffered I/O limit (BIOLM) or direct I/O limit (DIOLM) for the process
- The AST limit (ASTLM) quota, if an AST service routine is specified, for the process
$DNSW
SS$_NORMAL Normal completion of the request. SS$_BADPARAM Either an item code in the item list is out of range or the item list contains more than the maximum allowable number of items.
| DNS$_ACCESSDENIED | Caller does not have required access to the entry in question. This error is returned only if the client has some access to the entry. Otherwise, the unknown entry status is returned. |
| DNS$_BADCLOCK | The clock at the name server has a value outside the permissible range. |
| DNS$_BADEPOCH | Copies of directories are not synchronized. |
| DNS$_BADITEMBUFFER | Invalid output item buffer detected. (This normally indicates that the buffer has been modified during the call.) |
| DNS$_CACHELOCKED | Global client cache locked. |
| DNS$_CLEARINGHOUSEDOWN | Clearinghouse is not available. |
| DNS$_CLERKBUG | Internal clerk error detected. |
| DNS$_CONFLICTINGARGUMENTS | Two or more optional arguments conflict; they cannot be specified in the same function code. |
| DNS$_DANGLINGLINK | Soft link points to nonexistent target. |
| DNS$_DATACORRUPTION | An error occurred in accessing the data stored at a clearinghouse. The clearinghouse might be corrupted. |
| DNS$_ENTRYEXISTS | An entry with the same full name already exists in the namespace. |
| DNS$_FALSE | Unsuccessful test operation. |
| DNS$_INVALIDARGUMENT | A syntactically incorrect, out of range, or otherwise inappropriate argument was specified in the call. |
| DNS$_INVALID_ATTRIBUTENAME | The name given for function is not a valid DECdns attribute name. |
| DNS$_INVALID_CLASSNAME | The name given for function is not a valid DECdns class name. |
| DNS$_INVALID_CLEARINGHOUSENAME | The name given for function is not a valid DECdns clearinghouse name. |
| DNS$_INVALID_CONTEXTNAME | The name given for function is not a valid DECdns context name. |
| DNS$_INVALID_DIRECTORYNAME | The name given for function is not a valid DECdns directory name. |
| DNS$_INVALID_ENTRYNAME | The name given for function is not a valid DECdns entry name. |
| DNS$_INVALIDFUNCTION | Invalid function specified. |
| DNS$_INVALID_GROUPNAME | The name given for function is not a valid DECdns group name. |
| DNS$_INVALIDITEM | Invalid item code was specified in the item list. |
| DNS$_INVALID_LINKNAME | The name given for function is not a valid DECdns soft link name. |
| DNS$_INVALID_MEMBERNAME | The name given for function is not a valid DECdns member name. |
| DNS$_INVALIDNAME | A name containing invalid characters was specified in the call. |
| DNS$_INVALID_NSNAME | Namespace name given in name string is not a valid DECdns name. |
| DNS$_INVALID_OBJECTNAME | The name given for function is not a valid DECdns object name. |
| DNS$_INVALID_TARGETNAME | The name given for function is not a valid DECdns target name. |
| DNS$_INVALIDUPDATE | An update was attempted to an attribute that cannot be directly modified by the client. |
| DNS$_INVALID_WILDCARDNAME | The name given for function is not a valid DECdns wildcard name. |
| DNS$_LOGICAL_ERROR | Error translating logical name in given string. |
| DNS$_MISSINGITEM | Required item code is missing from the item list. |
| DNS$_MOREDATA | More output data to be returned. |
| DNS$_NAMESERVERBUG | A name server encountered an implementation bug. Please contact your Compaq support representative. |
| DNS$_NOCACHE | Client cache file not initialized. |
| DNS$_NOCOMMUNICATION | No communication was possible with any name server capable of processing the request. Check NCP event 353.5 for the DECnet error. |
| DNS$_NONSNAME | Unknown namespace name specified. |
| DNS$_NONSRESOURCES | The call could not be performed due to lack of memory or communication resources at the local node to process the request. |
| DNS$_NOTAGROUP | The full name given is not the name of a group. |
| DNS$_NOTIMPLEMENTED | This function is defined by the architecture as optional and is not available in this implementation. |
| DNS$_NOTLINKED | A soft link is not contained in the name. |
| DNS$_NOTNAMESERVER | The node contacted by the clerk does not have a DECdns server running. This can happen when the application supplies the clerk with inaccurate replica information. |
| DNS$_NOTSUPPORTED | This version of the architecture does not support the requested function. |
| DNS$_POSSIBLECYCLE | Loop detected in soft link or group. |
| DNS$_RESOURCEERROR | Failure to obtain system resource. |
| DNS$_TIMEOUTMAYBEDONE | The operation did not complete in the time allotted. Modifications might or might not have been made to the namespace. |
| DNS$_TIMEOUTNOTDONE | The operation did not complete in the time allotted. No modifications have been performed even if the operation requested them. |
| DNS$_TRUE | Successful test operation. |
| DNS$_UNKNOWNCLEARINGHOUSE | The clearinghouse does not exist. |
| DNS$_UNKNOWNENTRY | Either the requested entry does not exist or the client does not have access to the entry. |
| DNS$_UNTRUSTEDCH | A DECdns server is not included in the object's access control set. |
| DNS$_WRONGATTRIBUTETYPE | The caller specified an attribute type that did not match the actual type of the attribute. |
| Previous | Next | Contents | Index |
|
|
![[OpenVMS documentation]](../../images/openvms_doc_banner_bottom.gif) |
|
Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal |
4527PRO_032.HTML
|