| Previous | Contents | Index |
The parameter is optional; if it is not specified, a default timeout value of 30 seconds is assumed.
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.
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 HP 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 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. |
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. For complete information about the $DNSW service, see the $DNS description.
SYS$DNSW [efn] ,func ,itmlst [,dnsb] [,astadr] [,astprm]
Removes a branch from a transaction and returns the outcome of the transaction.
SYS$END_BRANCH [efn] ,[flags] ,iosb ,[astadr] ,[astprm] ,tid ,bid
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]);
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:
| OpenVMS usage: | ast_procedure |
| type: | procedure entry mask |
| access: | call without stack unwinding |
| mechanism: | by reference |
| OpenVMS usage: | user_arg |
| type: | longword (unsigned) |
| access: | read only |
| mechanism: | by value |
| OpenVMS usage: | trans_id |
| type: | octaword (unsigned) |
| access: | read only |
| mechanism: | by reference |
| OpenVMS usage: | branch_id |
| type: | octaword (unsigned) |
| access: | read only |
| mechanism: | by reference |
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.
None
ASTLM
$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
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.
| Previous | Next | Contents | Index |