HP OpenVMS System Services Reference Manual
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_ATTRIBUTE
This 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
DNS$_MOREDATA
DNS$_INVALID_ENTRYNAME
DNS$_INVALID_ATTRIBUTENAME
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
DNS$_ENTRY
DNS$_LOOKINGFOR
You must specify the following output value item code:
DNS$_OUTVALSET
You can specify the following input value item codes:
DNS$_CONF
DNS$_CONTEXTVARTIME
DNS$_MAYBEMORE
DNS$_WAIT
You can specify the following output value item code:
DNS$_CONTEXTVARTIME
$DNS returns the following qualifying status:
DNS$V_DNSB_OUTLINKED
DNS$_REMOVE_LINK
This 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$_WAIT
DNS$_REMOVE_REPLICA
This 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
DNS$_DIRECTORY
You can specify the following input value item codes:
DNS$_CONF
DNS$_WAIT
DNS$_RESOLVE_NAME
This 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
DNS$_INVALID_LINKNAME
DNS$_NOTLINKED
DNS$_POSSIBLECYCLE
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$_WAIT
$DNS returns the following qualifying status:
DNS$V_DNSB_OUTLINKED
DNS$_SIMPLE_OPAQUE_TO_STRING
This 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
DNS$_INVALIDNAME
You must specify the following input value item code:
DNS$_FROMSIMPLENAME
You must specify the following output value item code:
DNS$_TOSTRINGNAME
DNS$_SKULK
This 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_ATTRIBUTE
This 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:
- It is a single-valued attribute and its value matches the
specified value.
- It is a set-valued attribute and the attribute contains the
specified value as one of its members.
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
DNS$_INVALID_ATTRIBUTENAME
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
DNS$_ENTRY
DNS$_LOOKINGFOR
DNS$_VALUE
You can specify the following input value item codes:
DNS$_CONF
DNS$_WAIT
$DNS returns the following qualifying status:
DNS$V_DNSB_OUTLINKED
DNS$_TEST_GROUP
This 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
DNS$_NOTAGROUP
DNS$_INVALID_GROUPNAME
DNS$_INVALID_MEMBERNAME
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
DNS$_MEMBER
You can specify the following input value item codes:
DNS$_CONF
DNS$_INOUTDIRECT
DNS$_WAIT
$DNS returns the following qualifying status:
DNS$V_DNSB_INOUTDIRECT
DNS$V_DNSB_OUTLINKED
Item Codes Table SYS-26 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.
Table SYS-26 $DNS Item Codes and Their Data Types
Item Code |
Data Type |
DNS$_ATTRIBUTENAME
|
An opaque simple name, which is limited to 31 ISO Latin-1 characters.
|
DNS$_ATTRIBUTETYPE
|
A single byte, indicating whether the attribute is a set (DNSK$_SET) or
a single value (DNS$K_SINGLE), followed by an opaque simple name.
|
DNS$_CLASS
|
An opaque simple name, limited to 31 ISO Latin-1 characters.
|
DNS$_CLASSFILTER
|
An opaque simple name that can contain a wildcard.
|
DNS$_CLEARINGHOUSE
|
An opaque simple name of a clearinghouse.
|
DNS$_CONF
|
The confidence setting, which is a 1-byte field with the value
DNS$K_LOW, DNS$K_MEDIUM, or DNS$K_HIGH.
|
DNS$_CONTEXTVARNAME
|
An opaque simple name.
|
DNS$_CONTEXTVARTIME
|
A creation timestamp (CTS).
|
DNS$_DIRECTORY
|
An opaque full name of a directory.
|
DNS$_ENTRY
|
An opaque full name of a directory, soft link, group, or clearinghouse.
|
DNS$_EXPIRETIME
|
A quadword absolute time representation.
|
DNS$_EXTENDTIME
|
A quadword relative time representation.
|
DNS$_FROMFULLNAME
|
An opaque full name.
|
DNS$_FROMSIMPLENAME
|
An opaque simple name.
|
DNS$_FROMSTRINGNAME
|
A full or simple name consisting of a string of ISO-1 Latin characters.
The length of the name is length stored separately in an item list.
|
DNS$_GROUP
|
An opaque full name.
|
DNS$_INOUTDIRECT
|
A 1-byte Boolean field. Valid values are 0 and 1.
|
DNS$_LINKNAME
|
An opaque full name of a soft link.
|
DNS$_LOOKINGFOR
|
A 1-byte field. Valid values are DNS$K_OBJECT, DNS$K_SOFTLINK,
DNS$K_CHILDDIRECTORY, DNS$K_DIRECTORY, or DNS$K_CLEARINGHOUSE.
|
DNS$_MAYBEMORE
|
A 1-byte Boolean field. Valid values are DNS$_FALSE and DNS$_TRUE.
|
DNS$_MEMBER
|
A single byte, indicating whether the member is a principal
(DNS$K_GRPMEM_NOT_GROUP) or another group (DNS$K_GRPMEM_IS_GROUP),
followed by the opaque full name of the member.
|
DNS$_MODOPERATION
|
A value indicating that an attribute is being added (DNS$K_PRESENT) or
deleted (DNS$K_ABSENT).
|
DNS$_MODVALUE
|
The structure of this value is dependent on the application.
|
DNS$_NEXTCHAR_PTR
|
The address of an invalid character following a valid full or simple
name.
|
DNS$_OBJECTNAME
|
An opaque full name.
|
DNS$_OUTATTRIBUTESET
|
DNS$K_SET or DNS$K_SINGLE in the first byte followed by a single or set
of attribute names.
|
DNS$_OUTCHILDREN
|
A set of opaque simple names of the child directories found in the
parent directory.
|
DNS$_OUTCTS
|
A timestamp.
|
DNS$_OUTNAME
|
An opaque full name.
|
DNS$_OUTOBJECTS
|
A set of opaque simple names. Optionally, each simple name can be
followed by the value of the DNS$Class attribute.
|
DNS$_OUTSOFTLINKS
|
A set of opaque simple names of the soft links for an object.
|
DNS$_OUTVALSET
|
A set of attribute values.
|
DNS$_READCHSET
|
An opaque full name of a read-only directory.
|
DNS$_REPLICATYPE
|
The type of directory replica. Valid values are secondary replica
(DNS$K_SECONDARY) and read-only replica (DNS$K_READONLY).
|
DNS$_RETURNCLASS
|
A flag indicating that the value of DNS$Class is returned in
DNS$_OUTOBJECTS.
|
DNS$_SECCHSET
|
An opaque full name of a secondary directory.
|
DNS$_SUPPRESS_NSNAME
|
A 1-byte value: a value of DNS$_TRUE suppresses the namespace name, and
a value of DNS$_FALSE returns the namespace name.
|
DNS$_TARGETNAME
|
The opaque full name of an entry in the namespace to which a soft link
will point.
|
DNS$_TOFULLNAME
|
The opaque full name of an object. The maximum output of
DNS$PARSE_FULLNAME_STRING is 402 bytes.
|
DNS$_TOSIMPLENAME
|
An opaque simple name. It can be no longer than 257 bytes.
|
DNS$_TOSTRINGNAME
|
A name string of ISO-1 Latin characters. The name length is stored
separately in an item list.
|
DNS$_VALUE
|
An attribute value in string format.
|
DNS$_VERSION
|
A 2-byte field: the first byte contains the major version number, the
second contains the minor version number.
|
DNS$_WAIT
|
A quadword time representation.
|
DNS$_WILDCARD
|
An opaque simple name containing a wildcard character.
|
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.
|