![[Compaq]](../../images/compaq.gif)
![[Go to the documentation home page]](../../images/buttons/bn_site_home.gif)
![[How to order documentation]](../../images/buttons/bn_order_docs.gif)
![[Help on this site]](../../images/buttons/bn_site_help.gif)
![[How to contact us]](../../images/buttons/bn_comments.gif)
![[OpenVMS documentation]](../../images/ovmsdoc_sec_head.gif)
| Document revision date: 19 July 1999 | |
|
|
|
|
|
|
| Previous | Contents | Index |
Returns the names of all devices that match a specified set of search criteria.
SYS$DEVICE_SCAN return_devnam ,retlen ,[search_devnam] ,[itmlst] ,[contxt]
int sys$device_scan (void *return_devnam, unsigned short int *retlen, void *search_devnam, void *itmlst, struct _generic_64 *contxt);
return_devnam
OpenVMS usage: char_string type: character-coded text string access: write only mechanism: by descriptor--fixed-length string descriptor
Buffer to receive the device name. The return_devnam argument is the address of a character string descriptor pointing to a buffer into which $DEVICE_SCAN writes the name of the first or next device that matches the specified search criteria. The maximum size of any device name is 64 bytes.retlen
OpenVMS usage: word_unsigned type: word (unsigned) access: write only mechanism: by reference
Length of the device name string returned by $DEVICE_SCAN. The retlen argument is the address of a word into which $DEVICE_SCAN writes the length of the device name string.search_devnam
OpenVMS usage: device_name type: character-coded text string access: read only mechanism: by descriptor--fixed-length string descriptor
Name of the device for which $DEVICE_SCAN is to search. The search_devnam argument accepts the standard wildcard characters, the asterisk (*), which matches any sequence of characters, and the percent sign (%), which matches any one character. If the search_devnam argument does not include a wildcard character, an exact match is used for comparison. For example, to match all unit 0 DU devices on any controller, specify *DU%0. This string is compared to the most complete device name (DVI$_ALLDEVNAM). Only uppercase characters are accepted.
itmlst
OpenVMS usage: item_list_3 type: longword_unsigned access: read only mechanism: by reference
Item list specifying search criteria used to identify the device names for return by $DEVICE_SCAN. The itmlst argument is the address of a list of item descriptors, each of which describes one search criterion. The list of item descriptors is terminated by a longword of 0.The following diagram depicts the format of a single item descriptor.
The following table defines the item descriptor fields.
| Descriptor Field | Definition |
|---|---|
| Buffer length | A word containing a user-supplied integer specifying the length (in bytes) of the longword from which $DEVICE_SCAN is to read the information. The length of the buffer needed depends on the item code specified in the item code field of the item descriptor. |
| Item code | A word containing a user-specified symbolic code specifying the item of information that $DEVICE_SCAN is to return. The $DVSDEF macro defines these codes. Each item code is described in the Item Codes section. |
| Buffer address | A longword containing the address of a longword value that contains item code information. Examples include DC$_DISK and DC$_MAILBOX. |
| Return length address |
A longword containing the address of a word to receive the length (in
bytes) of information returned for the output value item code.
For the input value item code, this field is not used. Compaq recommends the placeholder value be 0. |
| OpenVMS usage: | quadword_unsigned |
| type: | quadword (unsigned) |
| access: | modify |
| mechanism: | by reference |
DVS$_DEVCLASS
An input value item code that specifies, as an unsigned longword, the device class being searched. The $DCDEF macro defines these classes.The DVS$_DEVCLASS argument is a longword containing this number; however, DVS$_DEVCLASS uses only the low-order byte of the longword.
DVS$_DEVTYPE
An input value item code that specifies, as an unsigned longword, the device type for which $DEVICE_SCAN is going to search. The $DCDEF macro defines these types.The DVS$_DEVTYPE argument is a longword containing this number; however, DVS$_DEVTYPE uses only the low-order byte of the longword. DVS$_DEVTYPE should be used in conjunction with $DVS_DEVCLASS to specify the device type being searched for.
The Device Scan system service returns the names of all devices that match a specified set of search criteria. The names returned by $DEVICE_SCAN can then be passed to another service; for example, $GETDVI or $MOUNT.The device names are returned for one process per call. A context value is used to continue multiple calls to $DEVICE_SCAN.
$DEVICE_SCAN allows wildcard searches based on device names, device classes, and device types. It also provides the ability to perform a wildcard search on other device-related services.
$DEVICE_SCAN makes it possible to combine search criteria. For example, to find only RA82 devices, use the following selection criteria:
DVS$_DEVCLASS = DC$_DISK and DVS$_DEVTYPE = DT$_RA82To find all mailboxes with MB as part of the device name (excluding mailboxes such as NLA0), use the following selection criteria:
DVS$_DEVCLASS = DC$_MAILBOX and DEVNAM = *MB*None
None
$ALLOC, $ASSIGN, $BRKTHRU, $BRKTHRUW, $CANCEL, $CREMBX, $DALLOC, $DASSGN, $DELMBX, $DISMOU, $GETDVI, $GETDVIW, $GETMSG, $GETQUI, $GETQUIW, $INIT_VOL, $MOUNT, $PUTMSG, $QIO, $QIOW, $SNDERR, $SNDJBC, $SNDJBCW, $SNDOPR
SS$_NORMAL The service completed successfully. SS$_ACCVIO The search_devnam, itmlst, or contxt argument cannot be read by the caller, or the retlen, return_devnam, or contxt argument cannot be written by the caller. SS$_BADPARAM The contxt argument contains an invalid value, or the item list contains an invalid item code. SS$_NOMOREDEV No more devices match the specified search criteria. SS$_NOSUCHDEV The specified device does not exist on the host system.
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.On Alpha systems, this service accepts 64-bit addresses.
SYS$DGBLSC [flags] ,gsdnam ,[ident]
int sys$dgblsc (unsigned int flags, void *gsdnam, struct _secid *ident);
flags
OpenVMS usage: mask_longword type: longword (unsigned) access: read only mechanism: by value
Mask indicating global section characteristics. The flags argument is a longword value. A value of 0 (the default) specifies a group global section; a value of SEC$M_SYSGBL specifies a system global section.gsdnam
OpenVMS usage: section_name type: character-coded text string access: read only mechanism: by 32- or 64-bit descriptor--fixed-length string descriptor (Alpha) mechanism: by 32-bit descriptor--fixed-length string descriptor (VAX)
Name of the global section to be deleted. The gsdnam argument is the address of a character string descriptor pointing to this name string.For group global sections, the operating system interprets the group UIC as part of the global section name; thus, the names of global sections are unique to UIC groups.
ident
OpenVMS usage: section_id type: quadword (unsigned) access: read only mechanism: by 32- or 64-bit reference (Alpha) mechanism: by 32-bit reference (VAX)
Identification value specifying the version number of the global section to be deleted and the matching criteria to be applied. The ident argument is the 32- or 64-bit address (on Alpha systems) or the 32-bit address (on VAX systems) of a quadword structure containing three fields.The version number is in the second longword. The version number contains two fields: a minor identification in the low-order 24 bits and a major identification in the high-order 8 bits. Values for these fields can be assigned by installation convention to differentiate versions of global sections. If you specify no version number when creating a section, processes that specify a version number when mapping cannot access the global section.
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 If you specify no address or specify it as 0 (the default), the version number and match control fields default to 0.
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.
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
None
$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.
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.
Dismounts a mounted volume or volume sets.
SYS$DISMOU devnam ,[flags]
int sys$dismou (void *devnam, unsigned int flags);
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.
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.
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
None
$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
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.
| Previous | Next | Contents | Index |
|
|
| privacy and legal statement | ||
| 4527PRO_029.HTML | ||