Document revision date: 19 July 1999

Returns information about one or more existing proxies.

Format

SYS$DISPLAY_PROXY rem_node ,rem_user ,buffer_sizes ,proxy_node ,proxy_user ,default_user ,local_users ,flags ,[context]

C Prototype

int sys$display_proxy (void *rem_node, void *rem_user, unsigned short int buffer_sizes [4], void *proxy_node, void *proxy_user, void *default_user, unsigned int *local_users, unsigned int flags, unsigned int *context);

Arguments

rem_node

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

Remote node name of the proxy about which information is being requested. The rem_node argument is the address of a character-string descriptor pointing to the remote node name string.

A remote node name consists of 1 to 1024 characters. No specific characters, format, or case are required for a remote node name string. All node names are converted to their DECnet full name unless the PRX$M_BYPASS_EXPAND flag is set with the flags argument.

Asterisk (*) and percent sign (%) wildcards are allowed for the remote node specification. If you specify wildcards for the rem_node argument, the server searches the entire proxy database for matches to the remote node and remote user you specified. If a match is found, information about the matched proxy is returned. See the Description section for information about retrieving information about multiple proxies.

rem_user

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

Remote user name of the proxy about which information is being requested. The rem_user argument is the address of a character-string descriptor pointing to the user name string.

A remote user name consists of 1 to 32 alphanumeric characters, including dollar signs ($), underscores (_), and brackets ([ ]). Any lowercase characters specified are automatically converted to uppercase.

The rem_user argument can be specified in user identification code (UIC) format ([group, member]). Brackets are allowed only if the remote user name string specifies a UIC. Group and member are character-string representations of octal numbers with no leading zeros.

Asterisk (*) and percent sign (%) wildcards are allowed for the remote user specification. If you specify wildcards for the rem_user argument, the server searches the entire proxy database for matches to the remote node and remote user you specified. If a match is found, information about the matched proxy is returned. See the Description section for information about retrieving information about multiple proxies.

buffer_sizes

OpenVMS usage:	return length block
type:	array of 4 words (unsigned)
access:	write only
mechanism:	by reference

Array of return lengths for various input buffers. The buffer_sizes argument is the address of an array of four words with the following format.

The following table defines the buffer_sizes fields.

Descriptor Field	Definition
Proxy user length	Return length (in bytes) of the rem_user argument. The proxy user length field contains a value in the range of 0 to 32. A value of 0 in this field indicates that the service has failed or that there was no match for the user specified by the rem_user argument.
Proxy node length	Return length (in bytes) of the rem_node argument. A value of 0 in this field indicates that the service has failed or that there was no match for the node specified by the rem_node argument. The proxy node length field contains values in the range of 0 to 1024.
Local users count	Number of local users associated with the matched proxy. The local users count field contains a value in the range of 0 to 16. A value of 0 indicates that the matched proxy had no local users.
Default user length	Return length (in bytes) of the default_user argument. The default user length field contains a value in the range of 0 to 32. A value of 0 in this field indicates that the matched proxy did not have a default user.

proxy_node

The descriptor's buffer must be 1024 bytes long to receive a node name. The length of the returned node name is specified by the proxy node length field returned in the buffer specified by the buffer_sizes argument.

proxy_user

The descriptor's buffer must be 32 bytes long to receive a user name. The length of the returned user name is specified by the proxy user length field returned in the buffer specified by the buffer_sizes argument.

default_user

The descriptor's buffer must be 32 bytes long to receive a user name. The length of the returned user name is specified in the default user length field in the buffer specified by the buffer_sizes argument.

local_users

Each element in the array is a 36-byte block with the following format.

The following table defines the local_users fields.

Descriptor Field	Definition
User name length	Length (in bytes) of the associated user name string. The length can be in the range of 1 to 32 bytes.
Username	A fixed 32-byte blank padded character string containing a local user name associated with the matched proxy.

The buffer specified by the local_users argument must be able to contain up to 16 user name buffers. Therefore, the buffer length must be 576 bytes.

The number of elements returned in the buffer is specified in the local users count field returned in the buffer specified by the buffer_sizes argument.

flags

Each flag option has a symbolic name. The $PRXDEF macro defines the following symbolic name.

Symbolic Name	Description
PRX$M_BYPASS_EXPAND	The service should not convert the node name specified in the rem_node argument to its corresponding DECnet full name. If this flag is set, it is the caller's responsibility to ensure that the fully expanded node name is passed into the service.
PRX$M_EXACT	The service should match exactly the remote node and remote user and ignore wildcards.

context

The initial value contained in the longword pointed to by the context argument must be 0. The contents of the unsigned longword must not be changed after the service has set its value. If the contents of the buffer pointed to by the context argument are changed between calls to the $DISPLAY_PROXY service, the service will return SS$_BADCONTEXT. If the contents of the context argument are changed between calls to the $DISPLAY_PROXY service, you can change the value of the context argument back to 0 to start the search over again.

Contexts become invalid after one-half hour of non-use. This means that if you call the $DISPLAY_PROXY service with a wildcard rem_node or rem_user, and do not call the service to get the next matching record within one-half hour, the context becomes invalid. If the context has become invalid, you must start your search of the proxy database over from its beginning by resetting the context to 0.

Description

The Display Proxy service returns to the caller all information about a specified proxy in the proxy database.

Wildcards can be specified for the rem_node and rem_user arguments. Because $DISPLAY_PROXY can return information about only one matching proxy at a time, you must call this service repeatedly with the context argument to retrieve information about all matching proxies. $DISPLAY_PROXY returns SS$_NOMOREITEMS when information about all of the matching proxies has been returned. No proxy information is returned from the call that returns the SS$_NOMOREITEMS status.

Required Access or Privileges

The caller must have SYSPRV privilege or a UIC group less than or equal to the MAXSYSGRP system parameter.

Required Quota

None

Related Services

$ADD_PROXY, $DELETE_PROXY, $VERIFY_PROXY

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The rem_node or rem_user argument cannot be read by the service; or the buffer_sizes, proxy_node, proxy_user, default_user, or local_users argument cannot be written by the service; or the context argument cannot be read or written by the service.
SS$_BADBUFLEN	The length of the rem_node, rem_user, proxy_node, proxy_user, default_user, or local_users argument was out of range.
SS$_BADCONTEXT	The context argument did not contain a 0 on the first call to the service, or the context argument's value changed between consecutive calls to the service.
SS$_NOMOREITEMS	Information about all proxies matching the specification of the rem_node and rem_user arguments has been returned by the service.
SS$_NOREADALL	The caller does not have access to the proxy database.
This service can also return any of the following messages passed from the security server, or any OpenVMS RMS error message encountered during operations on the proxy database:
SECSRV$_BADNODENAMELEN	The node name length is out of range.
SECSRV$_BADREMUSERLEN	The remote user name length is out of range.
SECSRV$_NOSUCHPROXY	The proxy specified by the rem_node and rem_user arguments does not exist in the proxy database.
SECSRV$_NOSUCHUSER	The specified local user does not exist in the proxy's local user list, or is not the proxy's default user.
SECSRV$_PROXYNOTACTIVE	Proxy processing is currently stopped. Try the request again later.
SECSRV$_SERVERNOTACTIVE	The security server is not currently active. Try the request again later.

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.

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 set.

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.

dnsb

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.

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

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

astprm

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).

---

Previous

Next

Contents

Index

	privacy and legal statement
4527PRO_030.HTML