OpenVMS System Services Reference Manual
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-8 provides a summary of the data types for $DNS item codes.
The data types define the encoding of each item list element.
Description
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, refer to the OpenVMS Programming Concepts Manual.
Required Access or Privileges
None
Required Quota
- 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
Related Services
$DNSW
Condition Values Returned
|
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.
|
Condition Values Returned in the $DNS Status Block
|
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.
|
$DNSW (VAX Only)
On VAX systems, is the client interface to the DIGITAL Distributed Name
Service.
The $DNSW service completes synchronously; that is, it returns to the
caller after the operation completes.
For asynchronous completion, use the $DNS service, which returns to the
caller immediately after making a name service call. The return status
to the client call indicates whether a request was successfully queued
to the name service.
In all other respects, $DNSW is identical to $DNS. Refer to the $DNS
description for complete information about the $DNSW service.
Format
SYS$DNSW [efn] ,func ,itmlst [,dnsb] [,astadr] [,astprm]
$END_TRANS
Ends a transaction by attempting to commit it, and returns the outcome
of the transaction.
Format
SYS$END_TRANS [efn] ,[flags] ,iosb [,[astadr] ,[astprm] ,[tid]]
C Prototype
int sys$end_trans (unsigned int efn, unsigned int flags, struct _iosb
*iosb,...);
Arguments
efn
| OpenVMS usage: |
ef_number |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Number of the event flag that is set when the service completes. If
this argument is omitted, event flag 0 is set.
flags
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Flags specifying options for the service. The flags
argument is a longword bit mask in which each bit corresponds to an
option flag. The $DDTMDEF macro defines symbolic names for these option
flags.
All undefined bits must be 0. If this argument is omitted, no flag is
set.
The flag currently defined is shown in the following table:
| Flag |
Description |
|
DDTM$M_SYNC
|
Set this flag to specify that successful synchronous completion is to
be indicated by returning SS$_SYNCH. When SS$_SYNCH is returned, the
asynchronous system trap (AST) routine is not called, the event flag is
not set, and the I/O status block is not filled in.
|
iosb
| OpenVMS usage: |
io_status_block |
| type: |
quadword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
I/O status block in which the following information is returned:
- The completion status of the service. This is returned as a
condition value. See the Condition Values Returned section.
- The outcome of the transaction.
If the service returns
SS$_NORMAL, the outcome of the transaction is commit. If the service
returns SS$_ABORT, the outcome of the transaction is abort.
- An abort reason code that gives one reason why the transaction
aborted, if the completion status of the service is SS$_ABORT.
The $DDTMMSGDEF macro defines symbolic names for these abort reason
codes; those currently defined are shown in the following table:
| Symbolic Name |
Description |
|
DDTM$_ABORTED
|
The application aborted the transaction.
|
|
DDTM$_COMM_FAIL
|
A communications link failed.
|
|
DDTM$_INTEGRITY
|
A resource manager integrity constraint check failed.
|
|
DDTM$_LOG_FAIL
|
A write operation to the transaction log failed.
|
|
DDTM$_PART_SERIAL
|
A resource manager serialization check failed.
|
|
DDTM$_PART_TIMEOUT
|
The timeout specified by a resource manager expired.
|
|
DDTM$_SEG_FAIL
|
A process or image terminated.
|
|
DDTM$_SERIALIZATION
|
A DECdtm transaction manager serialization check failed.
|
|
DDTM$_SYNC_FAIL
|
The transaction was not globally synchronized.
|
|
DDTM$_TIMEOUT
|
The timeout specified on $START_TRANS expired.
|
|
DDTM$_UNKNOWN
|
The reason is unknown.
|
|
DDTM$_VETOED
|
A resource manager was unable to commit the transaction.
|
The following diagram shows the structure of the I/O status block:
astadr
| OpenVMS usage: |
ast_procedure |
| type: |
procedure value |
| access: |
call without stack unwinding |
| mechanism: |
by reference |
AST routine that is executed when the service completes. The
astadr argument is the address of this routine. The
routine is executed in the access mode of the caller.
astprm
| OpenVMS usage: |
user_arg |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
AST parameter that is passed to the AST routine specified by the
astadr argument.
tid
| OpenVMS usage: |
transaction_id |
| type: |
octaword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Identifier of the transaction to be ended.
If this argument is omitted, $END_TRANS ends the default transaction of
the calling process.
Description
The End Transaction service ends a transaction by attempting to commit
it, and returns the outcome of the transaction.
$END_TRANS initiates the commit protocol to determine whether the
outcome of the transaction is commit or abort.
Caution
Do not call $END_TRANS while any transaction operations are still in
progress. If there are any of these operations in progress when
$END_TRANS is called, an unintended set of operations could be
committed, invalidating the data managed by the resource managers
participating in the transaction.
|
$END_TRANS returns the outcome of the transaction. If it completes
successfully, the outcome of the transaction is commit. If it returns
the SS$_ABORT error, the outcome is abort, and the I/O status block
contains one reason why the transaction aborted.
$END_TRANS must be called from the process that started the
transaction. The access mode of the caller must be the same as or more
privileged than that specified in the call to $START_TRANS that started
the transaction.
$END_TRANS does not complete either successfully or with the SS$_ABORT
error until all quotas allocated for the transaction by calls on the
local node to DECdtm services have been returned.
$END_TRANS will not complete successfully (that is, the event flag will
not be set, the AST routine will not be called, and the I/O status
block will not be filled in) while the calling process is either:
- In an access mode that is more privileged than the DECdtm calls
made by any resource manager participant in the transaction.
RMS
Journaling calls DECdtm in executive mode. Oracle Rdb and Oracle
CODASYL DBMS call DECdtm in user mode.
- At AST level (in any access mode).
For example, if Oracle Rdb is a participant in the transaction,
$END_TRANS will not complete successfully while the calling process is
in supervisor, executive, or kernel mode, or while the calling process
is at AST level.
|
