OpenVMS System Services Reference Manual

The first longword specifies, in its low-order 3 bits, the matching criteria. The valid values, the symbolic names by which they can be specified, and their meanings are listed in the following table.

Value Name Match Criteria

0 SEC$K_MATALL Match all versions of the section

1 SEC$K_MATEQU Match only if major and minor identifications match

2 SEC$K_MATLEQ Match if the major identifications are equal and the minor identification of the mapper is less than or equal to the minor identification of the global section

Value	Name	Match Criteria
0	SEC$K_MATALL	Match all versions of the section
1	SEC$K_MATEQU	Match only if major and minor identifications match
2	SEC$K_MATLEQ	Match if the major identifications are equal and the minor identification of the mapper is less than or equal to the minor identification of the global section

If you specify no address or specify it as 0 (the default), the version number and match control fields default to 0.

DESCRIPTION

The Delete Global Section service marks an existing permanent global section for deletion. The actual deletion of the global section takes place when all processes that have mapped the global section have deleted the mapped pages.
After a global section has been marked for deletion, any process that attempts to map it receives the warning return status code SS$_NOSUCHSEC.
Temporary global sections are automatically deleted when the count of processes using the section goes to 0.
On VAX systems, a section located in memory that is shared by multiple processors can be marked for deletion only by a process running on the same processor that created the section.
Required Access or Privileges

Depending on the operation, the calling process might need one or more of the following privileges:

SYSGBL privilege to delete a system global section
PRMGBL privilege to delete a permanent global section
PFNMAP privilege to delete a page frame section
SHMEM privilege to delete a global section located in memory shared by multiple processors

Required Quota

None
Related Services

$ADJSTK, $ADJWSL, $CRETVA, $CRMPSC, $DELTVA, $EXPREG, $LCKPAG, $LKWSET, $MGBLSC, $PURGWS, $SETPRT, $SETSTK, $SETSWM, $ULKPAG, $ULWSET, $UPDSEC, $UPDSECW
The $DGBLSC service does not unmap a global section from a process's virtual address space. To do this, the process should call the Delete Virtual Address Space ($DELTVA or $DELTVA_64) service, which deletes the pages to which the section is mapped.

Condition Values Returned

SS$_NORMAL The service completed successfully.

SS$_ACCVIO The global section name or name descriptor or the section identification field cannot be read by the caller.

SS$_INTERLOCK The bit map lock for allocating global sections from the specified shared memory is locked by another process.

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

SS$_IVSECFLG You set an invalid flag, reserved flag, or flag requiring a user privilege.

SS$_IVSECIDCTL The section identification match control field is invalid.

SS$_NOPRIV The caller does not have the privilege to delete a system global section, does not have read/write access to a group global section, or does not have the privilege to delete a global section located in memory that is shared by multiple processors.

SS$_NOSUCHSEC The specified global section does not exist, or the identifications do not match.

SS$_NOTCREATOR The section is in memory shared by multiple processors and was created by a process on another processor.

+SS$_SHMNOTCNCT The shared memory named in the name argument is not known to the system. This error can be caused by a spelling error in the string, an improperly assigned logical name, or the failure to identify the multiport memory as shared at system generation time.

SS$_TOOMANYLNAM The logical name translation of the gsdnam string exceeded the allowed depth of 10.

+VAX specific

$DISMOU

Dismounts a mounted volume or volume sets.

Format

SYS$DISMOU devnam ,[flags]

C Prototype

int sys$dismou (void *devnam, unsigned int flags);

ARGUMENTS

devnam

OpenVMS usage: device_name

type: character-coded text string

access: read only

mechanism: by descriptor--fixed-length string descriptor

Device name of the device to be dismounted. The devnam argument is the address of a character string descriptor pointing to the device name string. The string can be either a physical device name or a logical name. If it is a logical name, it must translate to a physical device name.
flags

OpenVMS usage: mask_longword

type: longword (unsigned)

access: read only

mechanism: by value

A longword bit vector specifying options for the dismount operation. The flags argument is a longword bit vector wherein a bit, when set, selects the corresponding option. Each bit has a symbolic name; these names are defined by the $DMTDEF macro. The flags and their meanings are listed in the following table.

Flag Meaning

DMT$M_ABORT The volume is to be dismounted even if the caller did not mount the volume. If the volume was mounted with MNT$M_SHARE specified, $DISMOU dismounts the volume for all of the users who mounted it.
To specify DMT$M_ABORT, the caller must: (1) have GRPNAM privilege for a group volume, (2) have SYSNAM privilege for a system volume, or (3) either own the volume or have VOLPRO privilege.

DMT$M_CLUSTER The volume is to be dismounted clusterwide, that is, from all nodes in the OpenVMS Cluster system. $DISMOU dismounts the volume from the caller's node first and then from every other node in the existing cluster.
DMT$M_CLUSTER dismounts only system or group volumes. To dismount a group volume clusterwide, the caller must have GRPNAM privilege. To dismount a system volume clusterwide, the caller must have SYSNAM privilege.
DMT$M_CLUSTER has no effect if the system is not a member of a cluster. DMT$M_CLUSTER applies only to disks.

DMT$M_NOUNLOAD Specifies that the volume is not to be physically unloaded after the dismount. If both the DMT$M_UNLOAD and DMT$M_NOUNLOAD flags are specified, the DMT$M_NOUNLOAD flag is ignored. If neither flag is specified, the volume is physically unloaded, unless the DMT$M_NOUNLOAD flag was specified on the $MOUNT system service or the /NOUNLOAD qualifier was specified on the MOUNT command when the volume was mounted.

DMT$M_OVR_CHECKS Specifies that the volume should be dismounted without checking for open files, spooled devices, installed images, or installed swap and page files.

DMT$M_UNIT The specified device, rather than the entire volume set, is dismounted.

DMT$M_UNLOAD Specifies that the volume is to be physically unloaded after the dismount. If both the DMT$M_UNLOAD and DMT$M_NOUNLOAD flags are specified, the DMT$M_NOUNLOAD flag is ignored. If neither flag is specified, the volume is physically unloaded, unless the DMT$M_NOUNLOAD flag was specified on the $MOUNT system service or the /NOUNLOAD qualifier was specified on the MOUNT command when the volume was mounted.

Flag	Meaning
DMT$M_ABORT	The volume is to be dismounted even if the caller did not mount the volume. If the volume was mounted with MNT$M_SHARE specified, $DISMOU dismounts the volume for all of the users who mounted it. To specify DMT$M_ABORT, the caller must: (1) have GRPNAM privilege for a group volume, (2) have SYSNAM privilege for a system volume, or (3) either own the volume or have VOLPRO privilege.
DMT$M_CLUSTER	The volume is to be dismounted clusterwide, that is, from all nodes in the OpenVMS Cluster system. $DISMOU dismounts the volume from the caller's node first and then from every other node in the existing cluster. DMT$M_CLUSTER dismounts only system or group volumes. To dismount a group volume clusterwide, the caller must have GRPNAM privilege. To dismount a system volume clusterwide, the caller must have SYSNAM privilege. DMT$M_CLUSTER has no effect if the system is not a member of a cluster. DMT$M_CLUSTER applies only to disks.
DMT$M_NOUNLOAD	Specifies that the volume is not to be physically unloaded after the dismount. If both the DMT$M_UNLOAD and DMT$M_NOUNLOAD flags are specified, the DMT$M_NOUNLOAD flag is ignored. If neither flag is specified, the volume is physically unloaded, unless the DMT$M_NOUNLOAD flag was specified on the $MOUNT system service or the /NOUNLOAD qualifier was specified on the MOUNT command when the volume was mounted.
DMT$M_OVR_CHECKS	Specifies that the volume should be dismounted without checking for open files, spooled devices, installed images, or installed swap and page files.
DMT$M_UNIT	The specified device, rather than the entire volume set, is dismounted.
DMT$M_UNLOAD	Specifies that the volume is to be physically unloaded after the dismount. If both the DMT$M_UNLOAD and DMT$M_NOUNLOAD flags are specified, the DMT$M_NOUNLOAD flag is ignored. If neither flag is specified, the volume is physically unloaded, unless the DMT$M_NOUNLOAD flag was specified on the $MOUNT system service or the /NOUNLOAD qualifier was specified on the MOUNT command when the volume was mounted.

DESCRIPTION

The Dismount Volume service dismounts a mounted volume or volume sets. To dismount a private volume, the caller must own the volume.
When you issue the $DISMOU service, $DISMOU removes the volume from your list of mounted volumes, deletes the logical name (if any) associated with the volume, and decrements the mount count.
If the mount count does not equal 0 after being decremented, $DISMOU does not mark the volume for dismounting (because the volume must have been mounted shared). In this case, the total effect for the issuing process is that the process is denied access to the volume and a logical name entry is deleted.
If the mount count equals 0 after being decremented, $DISMOU marks the volume for dismounting. After marking the volume for dismounting, $DISMOU waits until the volume is idle before dismounting it. A native volume is idle when no user has an open file to the volume, and a foreign volume is idle when no channels are assigned to the volume.
Native volumes are Files-11 structured disks or ANSI-structured tapes. Foreign volumes are not Files-11 or ANSI structured media.
After a volume is dismounted, nonpaged pool is returned to the system. Paged pool is also returned if you mounted the volume using the /GROUP or /SYSTEM qualifier.
If a volume is part of a Files-11 volume set and the flag bit DMT$V_UNIT is not set, the entire volume set is dismounted.
When a Files-11 volume has been marked for dismount, new channels can be assigned to the volume, but no new files can be opened.
Note that the SS$_NORMAL status code indicates only that $DISMOU has successfully performed one or more of the actions just described: decremented the mount count, marked the volume for dismount, or dismounted the volume. The only way to determine that the dismount has actually occurred is to check the device characteristics using the Get Device/Volume Information ($GETDVI) service.
By specifying the DVI$_DEVCHAR item code in a call to $GETDVI, you can learn whether a volume is mounted (it is if the DEV$V_MNT bit is set) or whether it is marked for dismounting (it is if the DEV$M_DMT bit is set). If DEV$V_MNT is clear or if DEV$M_DMT is set, the mount count is 0.
Required Access or Privileges

Depending on the operation, the calling process might need one of the following privileges to use $DISMOU:

GRPNAM privilege to dismount a volume mounted with the /GROUP qualifier
SYSNAM privilege to dismount a volume mounted with the /SYSTEM qualifier

Required Quota

None
Related Services

$ALLOC, $ASSIGN, $BRKTHRU, $BRKTHRUW, $CANCEL, $CREMBX, $DALLOC, $DASSGN, $DELMBX, $DEVICE_SCAN, $GETDVI, $GETDVIW, $GETMSG, $GETQUI, $GETQUIW, $INIT_VOL, $MOUNT, $PUTMSG, $QIO, $QIOW, $SNDERR, $SNDJBC, $SNDJBCW, $SNDOPR

Condition Values Returned

SS$_NORMAL The service completed successfully.

SS$_ACCVIO The device name descriptor cannot be read or does not describe a readable device name.

SS$_DEVALLOC The device is allocated to another process and cannot be dismounted by the caller.

SS$_DEVOFFLINE The specified device is not available.

SS$_DEVNOTMOUNT The specified device is not mounted.

SS$_IVDEVNAM The device name string is not valid.

SS$_IVLOGNAM The device logical name has a length of 0 or is longer than the allowable logical name length.

SS$_NOGRPNAM GRPNAM privilege is required to dismount a volume mounted for groupwide access.

SS$_NOIOCHAN No I/O channel is available. To use $DISMOU, a channel must be assigned to the volume.

SS$_NONLOCAL The device is on a remote node.

SS$_NOSUCHDEV The specified device does not exist.

SS$_NOSYSNAM SYSNAM privilege is required to dismount a volume mounted for systemwide access.

SS$_NOTFILEDEV The specified device is not file structured.

$DISPLAY_PROXY

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

OpenVMS usage: char_string

type: character-coded text string

access: write only

mechanism: by descriptor--fixed-length string descriptor

Node name of a proxy matching the remote node name specified by the rem_node argument and the remote user name specified by the rem_user argument. The proxy_node argument is the address of a character-string descriptor pointing to a buffer to receive the proxy node name.
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

OpenVMS usage: char_string

type: character-coded text string

access: write only

mechanism: by descriptor--fixed-length string descriptor

User name of a proxy matching the remote node name specified by the rem_node argument and the remote user name specified by the rem_user argument. The proxy_user argument is a character-string descriptor pointing to a buffer to receive the remote user name of a proxy.
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

OpenVMS usage: char_string

type: character-coded text string

access: write only

mechanism: by descriptor--fixed-length string descriptor

Default user of a proxy matching the node name specified by the rem_node argument and the remote user name specified by the rem_user argument. The default_user argument is the address of a character-string descriptor pointing to a buffer to receive the default user name.
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

OpenVMS usage: buffer

type: array of 0 to 16 user name buffers

access: write only

mechanism: by reference

Array of local user names associated with a proxy matching the remote node name specified by the rem_node argument and the remote user name specified by the rem_user argument. The local_users argument is the address of a buffer to receive an array of local user names.
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

OpenVMS usage: mask_longword

type: longword (unsigned)

access: read only

mechanism: by value

Functional specification for the service and type of user the local_user argument represents. The flags argument is a longword bit mask wherein each bit corresponds to an option.
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

OpenVMS usage: context

type: longword (unsigned)

access: write only

mechanism: by reference

Context information to keep between related calls to the $DISPLAY_PROXY service. The context argument is the address of a longword to receive a context from the $DISPLAY_PROXY service.
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.

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.

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.

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.

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.

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

Previous | Next | Contents | [Home] | [Comments] | [Ordering info] | [Help]
  4527P026.HTM
  OSSG Documentation
  22-NOV-1996 12:59:23.66
Copyright © Digital Equipment Corporation 1996. All Rights Reserved.

Legal

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The global section name or name descriptor or the section identification field cannot be read by the caller.
SS$_INTERLOCK	The bit map lock for allocating global sections from the specified shared memory is locked by another process.
SS$_IVLOGNAM	The global section name has a length of 0 or has more than 15 characters.
SS$_IVSECFLG	You set an invalid flag, reserved flag, or flag requiring a user privilege.
SS$_IVSECIDCTL	The section identification match control field is invalid.
SS$_NOPRIV	The caller does not have the privilege to delete a system global section, does not have read/write access to a group global section, or does not have the privilege to delete a global section located in memory that is shared by multiple processors.
SS$_NOSUCHSEC	The specified global section does not exist, or the identifications do not match.
SS$_NOTCREATOR	The section is in memory shared by multiple processors and was created by a process on another processor.
+SS$_SHMNOTCNCT	The shared memory named in the name argument is not known to the system. This error can be caused by a spelling error in the string, an improperly assigned logical name, or the failure to identify the multiport memory as shared at system generation time.
SS$_TOOMANYLNAM	The logical name translation of the gsdnam string exceeded the allowed depth of 10.

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

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

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

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

OpenVMS usage:	buffer
type:	array of 0 to 16 user name buffers
access:	write only
mechanism:	by reference

OpenVMS usage:	context
type:	longword (unsigned)
access:	write only
mechanism:	by reference

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