OpenVMS System Services Reference Manual

Document revision date: 30 March 2001

OpenVMS System Services Reference Manual

Contents

Index

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.

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:

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.

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.

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.

Previous Next Contents Index

privacy and legal statement

4527PRO_035.HTML

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.

OpenVMS usage:	ef_number
type:	longword (unsigned)
access:	read only
mechanism:	by value

OpenVMS usage:	mask_longword
type:	longword (unsigned)
access:	read only
mechanism:	by value

OpenVMS usage:	io_status_block
type:	quadword (unsigned)
access:	write only
mechanism:	by reference