 |
HP OpenVMS System Services Reference Manual
$DISCONNECT
The Disconnect service breaks the connection between a RAB and a FAB,
thereby terminating a record stream. All system resources, such as I/O
buffers and data structure space, are deallocated.
For additional information about this service, see the OpenVMS Record Management Services Reference Manual.
$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_FORCE
|
If connectivity to a device has been lost and the shadow set is in
mount verification, this flag causes a named shadow set member to be
immediately expelled from the shadow set.
|
|
DMT$M_MINICOPY_OPTIONAL
|
$DISMOU takes place, regardless of whether minicopy is enabled on the
disk.
|
|
DMT$M_MINICOPY_REQUIRED
|
$DISMOU fails if minicopy has not been enabled on the disk.
|
|
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
The Display service retrieves file attribute information about a file
and places this information in fields in the FAB, in XABs chained to
the FAB, and in a NAM block (if one is requested).
For additional information about this service, see the OpenVMS Record Management Services Reference Manual.
$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 additional details on
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 names:
| 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.
Description
The Display Proxy Information 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.
|
|
