 |
HP OpenVMS System Services Reference Manual
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-26 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 HP
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_BRANCH
Removes a branch from a transaction and returns the outcome of the
transaction.
Format
SYS$END_BRANCH [efn] ,[flags] ,iosb ,[astadr] ,[astprm] ,tid ,bid
C Prototype
int sys$end_branch (unsigned int efn, unsigned int flags, struct _iosb
*iosb, void (*astadr)(__unknown_params), int astprm, unsigned int tid
[4], unsigned int bid [4]);
Arguments
efn
| OpenVMS usage: |
ef_number |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Number of the event flag set when the service completes. If this
argument is omitted, event flag 0 is used.
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, described in Table SYS-27. All undefined bits must be 0. If
this argument is omitted, no flags are used.
Table SYS-27 $END_BRANCH Option Flags
| Flag Name |
Description |
|
DDTM$M_SYNC
|
Specifies successful synchronous completion by returning SS$_SYNCH.
When SS$_SYNCH is returned, the AST routine is not called, the event
flag is not set, and the I/O status block is not filled in.
|
|
DDTM$M_NOWAIT
|
Indicates that the service should return to the caller without waiting
for final cleanup. Note that $END_BRANCHW with the DDTM$M_NOWAIT flag
set is not equivalent to $END_BRANCH. The latter returns when the
operation has been queued. The former does not return until the
operation has been initiated. The full range of status values may be
returned from a nowait call.
|
iosb
| OpenVMS usage: |
io_status_block |
| type: |
quadword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
The 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 for more
information.
- The outcome of the transaction. If the service completes
successfully, the outcome of the transaction is commit. If it 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.
See $ACK_EVENT for a list of the codes that are currently defined.
The following diagram shows the structure of the I/O status block:
astadr
| OpenVMS usage: |
ast_procedure |
| type: |
procedure entry mask |
| access: |
call without stack unwinding |
| mechanism: |
by reference |
The AST routine executed when the service completes, if SS$_NORMAL is
returned in R0. The astadr argument is the address of
the entry mask of this routine. The routine is executed in the same
access mode as that of the caller of the $END_BRANCH service.
astprm
| OpenVMS usage: |
user_arg |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
The AST parameter passed to the AST routine specified by the
astadr argument.
tid
| OpenVMS usage: |
trans_id |
| type: |
octaword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
The identifier (TID) of the transaction from which the branch is to be
removed.
bid
| OpenVMS usage: |
branch_id |
| type: |
octaword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
The identifier (BID) of the branch to be removed from the transaction.
Description
The $END_BRANCH system service:
- Removes the specified branch from the specified transaction.
- Returns the outcome of the specified transaction.
If $END_BRANCH completes successfully, the outcome of the transaction
is commit. If it returns SS$_ABORT, the outcome is abort.
Preconditions for the successful completion of $END_BRANCH are:
- The calling process must contain the specified branch of the
specified transaction.
- The specified branch must be a synchronized branch.
- The access mode of the caller must be the same as or more
privileged than that of any branch of the specified transaction in this
process. (See $START_BRANCH and $START_TRANS.)
$END_BRANCH may fail for the following reasons:
- Preconditions were not met.
- An abort event has occurred for the transaction.
Postconditions on successful completion of $END_BRANCH are described in
Table SYS-28:
Table SYS-28 Postconditions When$END_BRANCH Completes Successfully
| Postcondition |
Meaning |
|
The branch that started the transaction has initiated a call to
$END_TRANS.
|
The completion of $END_BRANCH is delayed until this occurs. If the
transaction was not started on the local node, the successful
completion of $END_BRANCH may be indefinitely postponed by network
failure.
|
|
Every other authorized and synchronized branch of the transaction has
initiated a call to $END_BRANCH.
|
The completion of $END_BRANCH is delayed until this occurs.
|
|
The transaction is ended.
|
The result is that:
- The TID of the transaction is invalid. Calls to any DECdtm system
services except $GETDTI and $SETDTI that pass that TID will fail, and
calls to resource managers that pass that TID will fail.
- The transaction no longer has any application or RM participants on
the local node.
- All communications about the transaction between the local DECdtm
transaction manager and other DECdtm transaction managers are finished
(including the final "cleanup" acknowledgments).
|
|
The outcome of the transaction is commit.
|
All the transaction operations that completed successfully before
$END_TRANS was called will take effect; that is, the effects of these
operations will be made permanent.
Operations by any unauthorized branches will be aborted. (An
unauthorized branch is one without a matching $ADD_BRANCH.)
|
|
DECdtm quotas are returned.
|
All quotas allocated for the transaction by calls on the local node to
DECdtm services are now returned.
|
|
The transaction is not the default transaction of the calling process.
|
If the transaction was the default transaction of the calling process,
then it is now no longer the default.
|
Postconditions on completion with the SS$_ABORT error are listed in
Table SYS-29. $END_BRANCH does not complete with this error until all
branches on the local node have been removed from the transaction. Thus
this call to $END_BRANCH cannot complete with the SS$_ABORT error until
after every authorized and synchronized branch on the local node has
initiated a call to $END_TRANS, $END_BRANCH, or $ABORT_TRANS.
Table SYS-29 Postconditions When$END_BRANCH Completes with the SS$_ABORT Error
| Postcondition |
Meaning |
|
The transaction is ended.
|
If DDTM$M_NOWAIT is clear:
- The TID of the transaction is invalid. Calls to any DECdtm system
services except $GETDTI and $SETDTI that pass that TID will fail, and
calls to resource managers that pass that TID will fail.
- The transaction no longer has any application or RM participants on
the local node.
- All communications about the transaction between the local DECdtm
transaction manager and other DECdtm transaction managers are finished
(including the final cleanup acknowledgments).
|
|
The outcome of the transaction is abort.
|
None of the operations of the transaction will ever take effect.
The I/O status block contains one reason why the transaction was
aborted. If there are multiple reasons for the transaction aborting,
the DECdtm transaction manager returns one of the reasons in the I/O
status block. It may return different reasons to different branches in
the transaction.
For example, if the transaction timeout expires and a
communications link fails, then either the DDTM$_TIMEOUT or
DDTM$_COMM_FAIL abort reason code may be returned.
|
|
DECdtm quotas are returned.
|
If DDTM$M_NOWAIT is clear, all quotas allocated for the transaction by
calls on the local node to DECdtm services are now returned.
|
|
The transaction is not the default transaction of the calling process.
|
If DDTM$M_NOWAIT is clear and the transaction was the default
transaction of the calling process, then it is no longer the default.
|
There is also a wait form of the service, $END_BRANCHW.
Required Privileges
None
Required Quotas
ASTLM
Related Services
$ABORT_TRANS, $ABORT_TRANSW, $ACK_EVENT, $ADD_BRANCH, $ADD_BRANCHW,
$CREATE_UID, $DECLARE_RM, $DECLARE_RMW, $END_BRANCHW, $END_TRANS,
$END_TRANSW, $FORGET_RM, $FORGET_RMW, $GETDTI, $GETDTIW,
$GET_DEFAULT_TRANS, $JOIN_RM, $JOIN_RMW, $SETDTI, $SETDTIW,
$SET_DEFAULT_TRANS, $SET_DEFAULT_TRANSW, $START_BRANCH, $START_BRANCHW,
$START_TRANS, $START_TRANSW, $TRANS_EVENT, $TRANS_EVENTW
Condition Values Returned
|
SS$_NORMAL
|
If returned in R0, the request was successfully queued. If returned in
the I/O status block, the service completed successfully.
|
|
SS$_SYNCH
|
The service completed successfully and synchronously (returned only if
the DDTM$M_SYNC flag is set).
|
|
SS$_ABORT
|
The transaction aborted. See the abort reason code returned in the I/O
status block for one reason why the transaction aborted.
|
|
SS$_ACCVIO
|
An argument was not accessible to the caller.
|
|
SS$_BADPARAM
|
Either the options flags were invalid or the
tid argument was omitted but the
bid argument was not zero.
|
|
SS$_BRANCHENDED
|
Either the calling process had already called $END_BRANCH or
$ABORT_TRANS specifying that BID, or the branch was unsynchronized.
|
|
SS$_EXASTLM
|
The process AST limit (ASTLM) was exceeded.
|
|
SS$_ILLEFC
|
The event flag number was invalid.
|
|
SS$_INSFARGS
|
A required argument was missing.
|
|
SS$_INSFMEM
|
There was insufficient system dynamic memory for the operation.
|
|
SS$_NOSUCHBID
|
The calling process did not contain the branch identified by the BID
passed in the bid argument.
|
|
SS$_NOSUCHTID
|
The calling process did not contain any branches in the transaction.
|
|
SS$_WRONGACMODE
|
The access mode of the caller was less privileged than that of a branch
of the specified transaction in this process.
|
|
