HP OpenVMS System Services Reference Manual

Contents

Index

$DLCEFC

Marks a permanent common event flag cluster for deletion.

Format

SYS$DLCEFC name

C Prototype

int sys$dlcefc (void *name);

Argument

name

OpenVMS usage: ef_cluster_name

type: character-coded text string

access: read only

mechanism: by descriptor--fixed-length string descriptor

Name of the common event flag cluster to be deleted. The name argument is the address of a character string descriptor pointing to the name of the cluster.
The names of event flag clusters are unique to UIC groups, and the UIC group number of the calling process is part of the name.

Description

The Delete Common Event Flag Cluster service marks a permanent common event flag cluster for deletion. The cluster is actually deleted when no more processes are associated with it. The $DLCEFC service does not disassociate a process from a common event flag cluster; the Disassociate Common Event Flag Cluster ($DACEFC) service does this. However, the system disassociates a process from an event flag cluster at image exit.
If the cluster has already been deleted or does not exist, the $DLCEFC service returns the status code SS$_NORMAL.
Required Access or Privileges

Delete access is required.
Required Quota

None
Related Services

$ASCEFC, $CLREF, $DACEFC, $READEF, $SETEF, $WAITFR, $WFLAND, $WFLOR

Condition Values Returned

SS$_NORMAL The service completed successfully.

SS$_IVLOGNAM The cluster name string has a length of 0 or has more than 15 characters.

SS$_NOPRIV The process does not have the privilege to delete a permanent common event flag cluster, or the process does not have the privilege to delete a common event flag cluster in memory shared by multiple processors.

$DNS (VAX Only)

On VAX systems, the DIGITAL Distributed Name Service (DECdns) clerk allows client applications to store resource names and addresses.
The $DNS system service completes asynchronously; that is, it returns to the client immediately after making a name service call. The status returned to the client call indicates whether a request was successfully queued to the name service.
The DIGITAL Distributed Name Service Clerk Wait ($DNSW) system service is the synchronous equivalent of $DNS. $DNSW is identical to $DNS in every way except that $DNSW returns to the caller after the operation completes.

Format

SYS$DNS [efn] ,func ,itmlst ,[dnsb] ,[astadr] ,[astprm]

Arguments

efn

OpenVMS usage: ef_number

type: longword (unsigned)

access: read only

mechanism: by value

Number of the event flag to be set when $DNS completes. The efn argument is a longword containing this number. The efn argument is optional; if not specified, event flag 0 is used.
When $DNS begins execution, it clears the event flag. Even if the service encounters an error and completes without queuing a name service request, the specified event flag is set.
func

OpenVMS usage: function_code

type: longword (unsigned)

access: read only

mechanism: by value

Function code specifying the action that $DNS is to perform. The func argument is a longword containing this function code.
A single call to $DNS can specify one function code. Most function codes require or allow for additional information to be passed in the call with the itmlst argument.
itmlst

OpenVMS usage: item_list_3

type: longword (unsigned)

access: read only

mechanism: by reference

Item list supplying information to be used in performing the function specified by the func argument. The itmlst argument is the address of the item list. The item list consists of one or more item descriptors, each of which is three longwords.
The descriptors can be in any order in the item list. Each item descriptor specifies an item code. Item codes are specified as either input or output parameters. Input parameters modify functions, set context, or describe the information to be returned. Output parameters return the requested information. The item list is terminated by a longword of 0.
The item list is a standard format item list. The following figure depicts the general structure of an item descriptor:

The following table defines the item descriptor fields:

Descriptor Field Definition

Buffer length A word specifying the length of the buffer; the buffer either supplies information to be used by $DNS or receives information from $DNS. The required length of the buffer varies, depending on the item code specified. Each item code description specifies the required length.

Item code A word containing a symbolic code describing the nature of the information currently in the buffer or to be returned in the buffer. The location of the buffer is pointed to by the buffer address field.

Buffer address A longword containing the address of the buffer that specifies or receives the information.

Return length address A longword containing the address of a word specifying the actual length (in bytes) of the information returned by $DNS. The information resides in a buffer identified by the buffer address field. The field applies to output item list entries only and must be 0 for input entries. If the return length address is 0, it is ignored.

Descriptor Field	Definition
Buffer length	A word specifying the length of the buffer; the buffer either supplies information to be used by $DNS or receives information from $DNS. The required length of the buffer varies, depending on the item code specified. Each item code description specifies the required length.
Item code	A word containing a symbolic code describing the nature of the information currently in the buffer or to be returned in the buffer. The location of the buffer is pointed to by the buffer address field.
Buffer address	A longword containing the address of the buffer that specifies or receives the information.
Return length address	A longword containing the address of a word specifying the actual length (in bytes) of the information returned by $DNS. The information resides in a buffer identified by the buffer address field. The field applies to output item list entries only and must be 0 for input entries. If the return length address is 0, it is ignored.

dnsb

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

Status block to receive the final completion status of the $DNS operation. The dnsb argument is the address of the quadword $DNS status block.

The following figure depicts the structure of a $DNS status block:

The following table defines the status block fields:

Status Block Field Definition

Return status Set on completion of a DECdns clerk request to indicate the success or failure of the operation. Check the qualifying status word for additional information about a request marked as successful.

Qualifying status This field consists of two flags that provide additional information about a successful request to the DECdns server.

Status Block Field	Definition
Return status	Set on completion of a DECdns clerk request to indicate the success or failure of the operation. Check the qualifying status word for additional information about a request marked as successful.
Qualifying status	This field consists of two flags that provide additional information about a successful request to the DECdns server.

The two qualifying status flags, DNS$V_DNSB_INOUTDIRECT and DNS$V_DNSB_OUTLINKED, are defined as follows:

DNS$V_DNSB_INOUTDIRECT---Indicates whether the members were found in the top-level group or in one of the subgroups. The values are defined as follows:
1: The member was found in the top-level group.
0: The member was found in one of the subgroups of the top-level group.
DNS$V_DNSB_OUTLINKED---If set, indicates that one or more soft links were encountered while resolving the name specified in a call.

Functions that access the DECdns server return a qualifying status. Name conversion functions do not return qualifying status.

astadr

OpenVMS usage:	ast_procedure
type:	procedure value
access:	call without stack unwinding
mechanism:	by reference

Asynchronous system trap (AST) routine to be executed when I/O completes. The astadr argument is the address of the AST routine.

The AST routine executes in the access mode of the caller of $DNS.

astprm

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

Asynchronous system trap parameter passed to the AST service routine. The astprm argument is a longword value containing the AST parameter.

Function Codes

DNS$_ADD_REPLICA
This request adds a directory replica in the specified clearinghouse. Specify the item code DNS$_REPLICATYPE as either a secondary directory (DNS$K_SECONDARY) or a read-only directory (DNS$K_READONLY).
You must have control access to the directory being replicated and write access to the new replica's clearinghouse.
You must specify the following input value item codes:
DNS$_CLEARINGHOUSE
DNS$_DIRECTORY
DNS$_REPLICATYPE

You can specify the following input value item codes:
DNS$_CONF
DNS$_WAIT

$DNS returns the following qualifying status:
DNS$V_DNSB_OUTLINKED

DNS$_ALLOW_CH
This request permits a directory to store clearinghouse objects. This request takes as input the name of a directory (DNS$_DIRECTORY).
You must have control access to the parent directory.
You must specify the following input value item code:
DNS$_DIRECTORY

You can specify the following input value item codes:
DNS$_CONF
DNS$_WAIT

DNS$_CREATE_DIRECTORY
This request creates a master directory in the specified clearinghouse.
You must have write or control access to the parent directory and write access to the master replica's clearinghouse.
You must specify the following input value item code:
DNS$_DIRECTORY

You can specify the following input value item codes:
DNS$_CLEARINGHOUSE
DNS$_WAIT

You can specify the following output value item code:
DNS$_OUTCTS

DNS$_CREATE_LINK
This request creates a soft link to a directory, object, soft link, or clearinghouse in the namespace. Specify the target to which the soft link points in the DNS$_TARGETNAME item code. Use the DNS$_RESOLVE_NAME function code to check the existence of the target.
You must have write or control access to the directory in which the soft link is being created.
You must specify the following input value item codes:
DNS$_LINKNAME
DNS$_TARGETNAME

You can specify the following input value item codes:
DNS$_CONF
DNS$_EXPIRETIME
DNS$_EXTENDTIME
DNS$_WAIT

You can specify the following output value item code:
DNS$_OUTCTS

DNS$_CREATE_OBJECT
This request creates an object in the namespace. Initially, the object has the attributes of DNS$CTS, DNS$UTS, DNS$Class, DNS$ClassVersion, and DNS$ACS. The name service creates the DNS$CTS, DNS$UTS, and DNS$ACS attributes. The client application supplies the DNS$Class and DNS$ClassVersion attributes. You can add attributes using the DNS$_MODIFY_ATTRIBUTE function.
The DECdns clerk cannot guarantee that an object has been created. Another DNS$_CREATE_OBJECT request could supersede the object created by your call. To verify an object creation, wait until the directory is skulked and then check to see if the requested object is present. If the value of the directory's DNS$ALLUPTO attribute is greater than the DNS$CTS of the object, your object has been successfully created.
If specified, DNS$_OUTCTS holds the creation timestamp of the newly created object.
This function code returns the following:
SS$_NORMAL
DNS$_ENTRYEXISTS
DNS$_INVALID_OBJECTNAME
DNS$_INVALID_CLASSNAME
Any condition listed in the section Condition Values Returned

You must have write access to the directory where the object will reside.
You must specify the following input value item codes:
DNS$_CLASS
DNS$_OBJECTNAME
DNS$_VERSION

You can specify the following input value item codes:
DNS$_CONF
DNS$_WAIT

You can specify the following output value item code:
DNS$_OUTCTS

DNS$_DELETE_DIRECTORY
This request removes a directory from the namespace.
You must have delete access to the directory being deleted and write, control, or delete access to the parent directory.
You must specify the following input value item code:
DNS$_DIRECTORY

You can specify the following input value item codes:
DNS$_CONF
DNS$_WAIT

DNS$_DELETE_OBJECT
This request removes the specified object from the namespace.
This function code returns the following:
SS$_NORMAL
DNS$_INVALID_OBJECTNAME
Any condition listed in the section Condition Values Returned

You must have delete access to the object.
You must specify the following input value item code:
DNS$_OBJECTNAME

You can specify the following input value item codes:
DNS$_CONF
DNS$_WAIT

$DNS returns the following qualifying status:
DNS$V_DNSB_OUTLINKED

DNS$_DISALLOW_CH
This request prevents a directory from storing clearinghouse objects. This request takes as input the name of a directory (DNS$_DIRECTORY).
You must have control access to the parent directory, and read or control access to any child directories.
You must specify the following input value item code:
DNS$_DIRECTORY

You can specify the following input value item codes:
DNS$_CONF
DNS$_WAIT

DNS$_ENUMERATE_ATTRIBUTES
This request returns a set of attribute names in DNS$_OUTATTRIBUTESET that are associated with the directory, object, soft link, or clearinghouse. Specify the entry type in the DNS$_LOOKINGFOR item code. The function returns either DNS$K_SET or DNS$K_SINGLE along with the set of attribute names.
To manipulate the attribute names returned by this call, you should use the DNS$REMOVE_FIRST_SET_VALUE run-time library routine.
The DECdns clerk enumerates attributes in alphabetical order. A return status of DNS$_MOREDATA implies that not all attributes have been enumerated. You should make further calls, setting DNS$_CONTEXTVARNAME to the last attribute in the set returned, until the procedure returns SS$_NORMAL.
This function code returns the following:
SS$_NORMAL
DNS$_MOREDATA
DNS$_INVALID_ENTRYNAME
DNS$_INVALID_CONTEXTNAME
Any condition listed in the section Condition Values Returned

You must have read access to the directory, object, soft link, or clearinghouse.
You must specify the following input value item codes:
DNS$_ENTRY
DNS$_LOOKINGFOR

You must specify the following output value item code:
DNS$_OUTATTRIBUTESET

You can specify the following input value item codes:
DNS$_CONF
DNS$_CONTEXTVARNAME
DNS$_WAIT

You can specify the following output value item code:
DNS$_CONTEXTVARNAME

$DNS returns the following qualifying status:
DNS$V_DNSB_OUTLINKED

DNS$_ENUMERATE_CHILDREN
This request takes as input a directory name with an optional simple name that uses a wildcard. The DECdns clerk matches the input against child directory entries in the specified directory.
The DECdns clerk returns a set of simple names of child directories in the target directory that match the name with the wildcard. A null set is returned when there is no match or the directory has no child directories.
To manipulate the values returned by this call, you should use the DNS$REMOVE_FIRST_SET_VALUE run-time routine. The value returned is a simple name.
The clerk enumerates child directories in alphabetical order. If the call returns DNS$_MOREDATA, not all child directories have been enumerated and the client should make further calls, setting DNS$_CONTEXTVARNAME to the last child directory in the set returned, until the procedure returns SS$_NORMAL. Subsequent calls return the child directories, starting with the directory specified in DNS$_CONTEXTVARNAME and continuing in alphabetical order.
This function code returns the following:
SS$_NORMAL
DNS$_MOREDATA
DNS$_INVALID_DIRECTORYNAME
DNS$_INVALID_CONTEXTNAME
DNS$_INVALID_WILDCARDNAME

You must have read access to the parent directory.
You must specify the following input value item code:
DNS$_DIRECTORY

You must specify the following output value item code:
DNS$_OUTCHILDREN

You can specify the following input value item codes:
DNS$_CONF
DNS$_CONTEXTVARNAME
DNS$_WAIT
DNS$_WILDCARD

You can specify the following output value item code:
DNS$_CONTEXTVARNAME

$DNS returns the following qualifying status:
DNS$V_DNSB_OUTLINKED

DNS$_ENUMERATE_OBJECTS
This request takes as input the directory name, a simple name that can use a wildcard, and a class name that uses a wildcard. The DECdns clerk matches these against objects in the directory. If a wildcard and class filter are not specified, all objects in the directory are returned.
The function returns (in DNS$_OUTOBJECTS) a set of simple names of object entries in the directory that match the name with the wildcard. The function also returns the class of the object entries, if specified with DNS$_RETURNCLASS. If no object entries match the wildcard or the directory contains no object entries, a null set is returned.
To manipulate the values returned by this call, you should use the DNS$REMOVE_FIRST_SET_VALUE run-time routine. The value returned is a simple name structure.
The clerk enumerates objects in alphabetical order. If the call returns DNS$_MOREDATA, not all objects have been enumerated and the client should make further calls, setting DNS$_CONTEXTVARNAME to the last object in the set returned, until the procedure returns SS$_NORMAL. If the class filter is specified, only those objects of the specified classes are returned.
This function code returns the following:
SS$_NORMAL
DNS$_MOREDATA
DNS$_INVALID_DIRECTORYNAME
DNS$_INVALID_CONTEXTNAME
DNS$_INVALID_WILDCARDNAME
DNS$_INVALID_CLASSNAME

You must have read access to the directory.
You must specify the following input value item code:
DNS$_DIRECTORY

You must specify the following output value item code:
DNS$_OUTOBJECTS

You can specify the following input value item codes:
DNS$_CLASSFILTER
DNS$_CONF
DNS$_CONTEXTVARNAME
DNS$_RETURNCLASS
DNS$_WAIT
DNS$_WILDCARD

You can specify the following output value item code:
DNS$_CONTEXTVARNAME

$DNS returns the following qualifying status:
DNS$V_DNSB_OUTLINKED

DNS$_ENUMERATE_SOFTLINKS
This request takes as input the name of a directory and a wildcarded simple name. The DECdns clerk matches these against soft links in the directory. It returns (in DNS$_OUTSOFTLINKS) a set consisting of simple names of soft links in the directory that match the wildcarded name. If no soft link entries match the wildcard or the directory contains no soft links, a null set is returned.
If no wildcard is specified, then all soft links in the directory are returned.
To manipulate the values returned by this call, use the DNS$REMOVE_FIRST_SET_VALUE run-time library routine. The value returned is a simple name.
The clerk enumerates soft links in alphabetical order. If the call returns DNS$_MOREDATA, not all matching soft links have been enumerated and the client should make further calls, setting DNS$_CONTEXTVARNAME to the last soft link in the set returned, until the procedure returns SS$_NORMAL.
This function code returns the following:
SS$_NORMAL
DNS$_INVALID_DIRECTORYNAME
DNS$_INVALID_CONTEXTNAME
DNS$_INVALID_WILDCARDNAME

You must have read access to the directory.
You must specify the following input value item code:
DNS$_DIRECTORY

You must specify the following output value item code:
DNS$_OUTSOFTLINKS

You can specify the following input value item codes:
DNS$_CONF
DNS$_CONTEXTVARNAME
DNS$_WAIT
DNS$_WILDCARD

You can specify the following output value item code:
DNS$_CONTEXTVARNAME

$DNS returns the following qualifying status:
DNS$V_DNSB_OUTLINKED

DNS$_FULL_OPAQUE_TO_STRING
This request converts a full name in opaque format to its equivalent in string format. To prevent the namespace nickname from being included in the string name, set the byte referred to by DNS$_SUPPRESS_NSNAME to 1.
This function code returns the following:
SS$_NORMAL
DNS$_INVALIDNAME

You must specify the following input value item code:
DNS$_FROMFULLNAME

You must specify the following output value item code:
DNS$_TOSTRINGNAME

You can specify the following input value item code:
DNS$_SUPPRESS_NSNAME

DNS$_MODIFY_ATTRIBUTE
This request applies one update to the specified entry in the namespace. The update operations are as follows:

Add or remove an attribute.
Add or remove an attribute value from either a single-valued attribute or a set-valued attribute.

To add a value to a single-valued or set-valued attribute, specify a value in the DNS$_MODVALUE item code. If you do not specify a value for a single-valued attribute, you receive the error DNS$_INVALIDUPDATE. Single-valued attributes cannot exist without a value.
If you do not specify a value for a set-valued attribute, the clerk creates the attribute with an empty set.
To delete an attribute value, use the DNS$_MODVALUE item code to remove the specified value from an attribute set. If you do not specify the item code, the name service removes the attribute and all its values.
This function code returns the following:
SS$_NORMAL
DNS$_WRONGATTRIBUTETYPE
DNS$_INVALIDUPDATE
DNS$_INVALID_ENTRYNAME
DNS$_INVALID_ATTRIBUTENAME

You must have write or delete access to the directory, object, soft link, or clearinghouse whose attribute is being modified, depending on whether the operation adds or removes the attribute.
You must specify the following input value item codes:
DNS$_ATTRIBUTENAME
DNS$_ATTRIBUTETYPE
DNS$_ENTRY
DNS$_LOOKINGFOR
DNS$_MODOPERATION

You can specify the following input value item codes:
DNS$_CONF
DNS$_MODVALUE
DNS$_WAIT

$DNS returns the following qualifying status:
DNS$V_DNSB_OUTLINKED

DNS$_NEW_EPOCH
This request reconstructs an entire replica set of a directory and synchronizes the copies to recover as much of the original directory state as possible. You can also use the function to change a replica type for configuration management purposes.
This request takes as input the full name of a clearinghouse (DNS$_CLEARINGHOUSE) and directory (DNS$_DIRECTORY). Specify, optionally, the full names of clearinghouses in which to store secondary and read-only replicas (DNS$_SECCHSET and DNS$_READCHSET).
You must have control access to the parent directory and write access to each clearinghouse for which the replica type will be changed from its current value to a new value.
You must specify the following input value item codes:
DNS$_CLEARINGHOUSE
DNS$_DIRECTORY

You can specify the following input value item codes:
DNS$_READCHSET
DNS$_SECCHSET

DNS$_PARSE_FULLNAME_STRING
This request takes a full name in string format and converts it to its equivalent in opaque format. If you specify the DNS$_NEXTCHAR_PTR item code, the clerk examines the name specified in DNS$_FROMSTRINGNAME for invalid characters. The buffer returns the address of the character in the name that immediately follows a valid DECdns name.
This function code returns the following:
SS$_NORMAL
DNS$_INVALIDNAME

You must specify the following input value item code:
DNS$_FROMSTRINGNAME

You must specify the following output value item code:
DNS$_TOFULLNAME

You can specify the following input value item code:
DNS$_NEXTCHAR_PTR

DNS$_PARSE_SIMPLENAME_STRING
This request takes a simple name in string format and converts it to its equivalent in opaque format. If you specify the DNS$_NEXTCHAR_PTR item code, the clerk examines the name specified in DNS$_FROMSTRINGNAME for invalid characters. The buffer returns the address of the character in that name that immediately follows a valid DECdns name.
This function code returns the following:
SS$_NORMAL
DNS$_INVALIDNAME

You must specify the following input value item code:
DNS$_FROMSTRINGNAME

Previous Next Contents Index

OpenVMS usage:	ef_cluster_name
type:	character-coded text string
access:	read only
mechanism:	by descriptor--fixed-length string descriptor

SS$_NORMAL	The service completed successfully.
SS$_IVLOGNAM	The cluster name string has a length of 0 or has more than 15 characters.
SS$_NOPRIV	The process does not have the privilege to delete a permanent common event flag cluster, or the process does not have the privilege to delete a common event flag cluster in memory shared by multiple processors.

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

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

OpenVMS usage:	item_list_3
type:	longword (unsigned)
access:	read only
mechanism:	by reference