![[OpenVMS documentation]](../../images/openvms_doc_banner_top.gif)
|
![[Site home]](../../images/buttons/bn_site_home_off.gif)
![[Send comments]](../../images/buttons/bn_comments_off.gif)
![[Help with this site]](../../images/buttons/bn_site_help_off.gif)
![[How to order documentation]](../../images/buttons/bn_order_docs_off.gif)
![[OpenVMS site]](../../images/buttons/bn_openvms_off.gif)
![[Compaq site]](../../images/buttons/bn_compaq_off.gif)
|
| Updated: 11 December 1998 |
|
|
|
|
| Updated: 11 December 1998 |
OpenVMS System Services Reference Manual
| Previous | Contents | Index |
Converts a string from RMS format to file-system (ACP-QIO) format or from file-system (ACP-QIO) format to RMS format.
SYS$CVT_FILENAME cvttyp ,srcstr ,inflags ,outbuf ,outlen ,outflags
int sys$cvt_filename (unsigned int cvttyp, void *srcstr, unsigned int inflags, void *outbuf, unsigned short int *outlen, unsigned int *outflags);
cvttyp
OpenVMS usage: unsigned_longword type: longword (unsigned) access: read only mechanism: by value
Longword value that indicates whether the conversion is from RMS format to ACP-QIO format or vice versa.There are two legal values for this parameter, represented by the symbols CVTFNM$C_ACPQIO_TO_RMS and CVTFNM$C_RMS_TO_ACPQIO, that are defined by the $CVTFNMDEF macro.
srcstr
OpenVMS usage: string of bytes or words type: string of bytes or words access: read only mechanism: by 32-bit descriptor--fixed-length string descriptor
String to be converted by the service.If the conversion is from RMS format to ACP-QIO format, srcstr is an ISO-Latin-1 or VTF-7-encoded character string. If the conversion is from ACP-QIO format to RMS format, srcstr is a string of byte-width or word-width characters.
The descriptor length field indicates the length of the input string in bytes, whether the characters are byte-width or word-width.
The srcstr argument is the 32-bit address of a descriptor that points to this string.
inflags
OpenVMS usage: mask_longword type: longword (unsigned) access: read only mechanism: by value
Longword flag mask indicating the characteristics of the input string.For conversion from RMS format to ACP-QIO format, only the CVTFNM$V_NO_DELIMITERS flag is valid.
For conversion from ACP-QIO format to RMS format, legal flags are CVTFNM$V_WORD_CHARS and CVTFNM$V_NO_DELIMITERS (defined by the $CVTFNMDEF macro).
Flag Description CVTFNM$V_WORD_CHARS Input source string contains word-width UCS-2 characters (ACPQIO_TO_RMS conversion only). CVTFNM$V_NO_DELIMITERS Input source string should be treated as an arbitrary string (such as a subdirectory name) rather than as a file name that contains (or should contain) dots or semicolons as type and version delimiters. CVTFNM$V_FORCE_UPCASE Causes this system service to convert each character to uppercase. (ACPQIO_TO_RMS conversion only). outbuf
OpenVMS usage: string of bytes or words type: string of bytes or words access: write only mechanism: by 32-bit descriptor--fixed-length string descriptor
The buffer into which the converted string is to be written.If the conversion is from RMS format to ACP-QIO format, the string may consist of byte-width ISO Latin-1 characters or word-width UCS-2 characters, depending on the characters in the source string. (If any character in the source string must be converted to UCS-2, then all characters in the output buffer will be converted to UCS-2.)
If the conversion is from ACP-QIO format to RMS format, then the output string will consist of ISO Latin-1 and VTF-7 characters in RMS canonical form. (Refer to the Guide to OpenVMS File Applications.)
For ACPQIO_TO_RMS conversion, if the output string contains word-width characters, the CVTFNM$V_WORD_CHARS flag in the outflags flag mask will be set.
The outbuf argument is the 32-bit address of a descriptor pointing to a buffer writable in the access mode of the caller.
outlen
OpenVMS usage: word_unsigned type: word (unsigned) access: write only mechanism: by 32-bit reference
The outlen argument is the 32-bit address of a (16-bit) word writable in the access mode of the caller.outflags
OpenVMS usage: mask_longword type: longword (unsigned) access: write only mechanism: by 32-bit reference
Longword flag mask in which the service sets or clears flags to indicate characteristics of the output string.For an RMS_TO_ACPQIO conversion, SYS$CVT_FILENAME sets the bit corresponding to CVTFNM$V_WORD_CHARS (defined by the $CVTFNMDEF macro) if the characters of the converted string are one-word wide rather than one-byte wide. If the characters of the converted string are one-byte wide, the service clears the CVTFNM$V_WORD_CHARS bit. All other bits are cleared by an RMS_TO_ACPQIO conversion.
The outflags argument is the 32-bit address of a 32-bit flag mask writable in the access mode of the caller.
This service is intended to provide the conversion of a file name or a subdirectory name between the RMS format (as seen at the RMS interface) and the ACP-QIO format (as stored on disk). A file name consists of a file name, a file type, and a file version; and a subdirectory name is a string to which ".DIR;1" can be appended to form a directory file name, as stored on disk.Prior to Version 7.2, these representations were the same. This is not necessarily the case for extended (ODS-5) file names. (Refer to the Guide to OpenVMS File Applications for details on ODS-5 file specifications.)
Depending on the value of cvttyp, the service will perform a conversion of a string from RMS format to ACP-QIO format or from ACP-QIO format to RMS format.
The source string is described by the argument srcstr, the output buffer is described by the argument outbuf, and the resultant string length is written to the argument outlen.
If any of the source string falls within the address range of the output buffer, the output string is unpredictable.
RMS-to-ACPQIO Conversion:
A string described by the srcstr descriptor argument is converted to an ISO Latin-1 or UCS-2 string with each character represented in a form that can be passed to the ACP-QIO by the $QIO service.
If the CVTFNM$V_NO_DELIMITERS input flag is not set, the source string will be scanned, and, if necessary, a dot and a semicolon will be inserted or appended as though a $PARSE were done with no default name, type, or version fields supplied. If the scan detects any delimiters indicating the presence of fields other than name (without FID), type, or version, a syntax error will be returned.
If the CVTFNM$V_NO_DELIMITERS input flag is set, individual characters will be validated and converted to their on-disk form. However, no scan will be done to determine if the type and version delimiters are present, and no delimiters will be added.
A percent sign (%) that is not preceded by the escape character (^) is converted to a question mark. An ISO Latin-1 character that is preceded by the escape character (^) is converted to the corresponding ISO Latin-1 character. A VTF-7 character (for example, ^U1234) that is preceded by the escape character (^) is converted to a UCS-2 character (for example, 0x1234).
If any character requires UCS-2 (word-width character) representation, all characters are represented in the output string with UCS-2. If no character requires word-width character representation, all characters are represented in the output string with ISO Latin-1 (byte-width) characters.
Valid characters are those that are legal in an RMS file name (file name, file type, and file version) or in an RMS subdirectory name. For example, directory delimiters "[" and "]" are not legal unless preceded by the escape character (^).
ACPQIO-to-RMS Conversion:
The string described by the srcstr descriptor argument is converted to the RMS canonical form for that string.
If the CVTFNM$V_NO_DELIMITERS input flag is clear, the source string must contain at least one semicolon, and, to the left of the semicolon, at least one dot. If it does not, RMS$_SYN (syntax error) is returned. In the output string, all other dots and semicolons are preceded by the RMS escape character (^).
If the CVTFNM$V_NO_DELIMITERS input flag is set, any dot or semicolon encountered is preceded in the output string by the RMS escape character (^).
The CVTFNM$V_WORD_CHARS flag of the inflags argument indicates whether the input string is to be interpreted as having byte-width (ISO Latin-1) or word-width (UCS-2) characters. If the argument indicates word-width characters, but the input length value is an odd number, a syntax error is returned.
Questions marks are converted to percent signs; percent signs are preceded by the escape character (^). UCS-2 characters are converted to VTF-7 characters. All characters are represented in RMS canonical form.
$CVT_FILENAME Usage:
You can use this service to compare two file names using the same conventions as RMS.
For an example program, refer to: [SYSHLP.EXAMPLES]FILENAME_COMPARE.C.
None.
None.
None.
SS$_NORMAL The service completed successfully. SS$_BADPARAM Unrecognized conversion type, extraneous input flags set, or zero-length input string. SS$_INSFARG Not enough arguments provided. SS$_TOO_MANY_ARGS Too many arguments provided. RMS$_SYN The service could not translate one or more characters in the strings described by the srcstr argument. Either the input string has word-width characters but odd byte-length (ACPQIO_TO_RMS only), or the CVTFNM$V_NO_DELIMITERS input flag was clear, and the input string did not contain both type and version delimiters. SS$_BUFFEROVF The output buffer was not large enough to accommodate the converted string.
Releases the calling process's association with a common event flag cluster.
SYS$DACEFC efn
int sys$dacefc (unsigned int efn);
efn
OpenVMS usage: ef_number type: longword (unsigned) access: read only mechanism: by value
Number of any event flag in the common cluster to be disassociated. The efn argument is a longword containing this number; however, $DACEFC uses only the low-order byte. The number must be in the range of 64 through 95 for cluster 2, and 96 through 127 for cluster 3.
The Disassociate Common Event Flag Cluster service disassociates the calling process from a common event flag cluster and decreases the count of processes associated with the cluster accordingly. When the image associated with a cluster exits, the system disassociates the cluster. When the count of processes associated with a temporary cluster or with a permanent cluster that is marked for deletion reaches 0, the cluster is automatically deleted.If a process issues this service specifying an event flag cluster with which it is not associated, the service completes successfully.
A calling process must have PRMCEB privilege to delete a permanent common event flag cluster.
None
$ASCEFC, $CLREF, $DLCEFC, $READEF, $SETEF, $WAITFR, $WFLAND, $WFLOR
SS$_NORMAL The service completed successfully. SS$_ILLEFC You specified an illegal event flag number. The number must be in the range of event flags 64 through 127. SS$_INTERLOCK The bit map lock for allocating common event flag clusters from the specified shared memory is locked by another process.
Deallocates a previously allocated device.
SYS$DALLOC [devnam] ,[acmode]
int sys$dalloc (void *devnam, unsigned int acmode);
devnam
OpenVMS usage: device_name type: character-coded text string access: read only mechanism: by descriptor--fixed-length string descriptor
Name of the device to be deallocated. The devnam argument is the address of a character string descriptor pointing to the device name string. The string might be either a physical device name or a logical name. If it is a logical name, it must translate to a physical device name.If you do not specify a device name, all devices allocated by the process from access modes equal to or less privileged than that specified are deallocated.
acmode
OpenVMS usage: access_mode type: longword (unsigned) access: read only mechanism: by value
Access mode from which the deallocation is to be performed. The acmode argument is a longword containing the access mode. The $PSLDEF macro defines the following symbols for the four access modes.
Symbol Access Mode PSL$C_KERNEL Kernel PSL$C_EXEC Executive PSL$C_SUPER Supervisor PSL$C_USER User The most privileged access mode used is the access mode of the caller.
The Deallocate Device service deallocates a previously allocated device. The issuing process relinquishes exclusive use of the device, thus allowing other processes to assign or allocate that device. You can deallocate an allocated device only from access modes equal to or more privileged than the access mode from which the original allocation was made.This service does not deallocate a device if, at the time of deallocation, the issuing process has one or more I/O channels assigned to the device; in such a case, the device remains allocated.
At image exit, the system automatically deallocates all devices that are allocated at user mode.
If you attempt to deallocate a mailbox, success is returned but no operation is performed.
None
None
$ALLOC, $ASSIGN, $BRKTHRU, $BRKTHRUW, $CANCEL, $CREMBX, $DASSGN, $DELMBX, $DEVICE_SCAN, $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 device name string or string descriptor cannot be read by the caller. SS$_DEVASSIGN The device cannot be deallocated because the process still has channels assigned to it. SS$_DEVNOTALLOC The device is not allocated to the requesting process. SS$_IVDEVNAM You did not specify a device name string, or the device name string contains invalid characters. SS$_IVLOGNAM The device name string has a length of 0 or has more than 63 characters. SS$_NONLOCAL The device is on a remote node. SS$_NOPRIV The device was allocated from a more privileged access mode. SS$_NOSUCHDEV The specified device does not exist in the host system.
Deassigns (releases) an I/O channel previously acquired using the Assign I/O Channel ($ASSIGN) service.
SYS$DASSGN chan
int sys$dassgn (unsigned short int chan);
chan
OpenVMS usage: channel type: word (unsigned) access: read only mechanism: by value
Number of the I/O channel to be deassigned. The chan argument is a word containing this number.
The Deassign I/O Channel service deassigns (releases) an I/O channel that it acquired using the Assign I/O Channel ($ASSIGN) service. You can deassign an I/O channel only from an access mode equal to or more privileged than the access mode from which the original channel assignment was made.When you deassign a channel, any outstanding I/O requests on the channel are canceled. If a file is open on the specified channel, the file is closed.
If a mailbox was associated with the device when the channel was assigned, the link to the mailbox is cleared.
If the I/O channel was assigned for a network operation, the network link is disconnected.
If the specified channel is the last channel assigned to a device that has been marked for dismounting, the device is dismounted.
I/O channels assigned from user mode are automatically deassigned at image exit.
None.
Note that you should use the SHARE privilege with caution. Applications, application protocols, and device drivers coded to expect only exclusive access can encounter unexpected and errant behavior when access to the device is unexpectedly shared. Unless the SHARE privilege is explicitly supported by the application, the application protocol, and the device driver, its use is generally discouraged. Refer to the OpenVMS Programming Concepts Manual for additional information.
None
$ALLOC, $ASSIGN, $BRKTHRU, $BRKTHRUW, $CANCEL, $CREMBX, $DALLOC, $DELMBX, $DEVICE_SCAN, $DISMOU, $GETDVI, $GETDVIW, $GETMSG, $GETQUI, $GETQUIW, $INIT_VOL, $MOUNT, $PUTMSG, $QIO, $QIOW, $SNDERR, $SNDJBC, $SNDJBCW, $SNDOPR
SS$_NORMAL The service completed successfully. SS$_IVCHAN You specified an invalid channel number, that is, a channel number of 0 or a number larger than the number of channels available. SS$_IVCHNLSEC A process section file is currently accessed using the specified channel number. SS$_IVIDENT On Alpha systems, you specified an invalid channel number that your process never assigned. SS$_NOICHAN On Alpha systems, you specified a channel number outside of the set of channel numbers available for your process. SS$_NOPRIV The specified channel is not assigned or was assigned from a more privileged access mode.
Queues an asynchronous system trap (AST) for the calling access mode or for a less privileged access mode.On Alpha systems, this service accepts 64-bit addresses.
SYS$DCLAST astadr ,[astprm] ,[acmode]
int sys$dclast (void (*astadr)(__unknown_params), unsigned __int64 astprm, unsigned int acmode);
astadr
OpenVMS usage: ast_procedure type: procedure value access: call without stack unwinding mechanism: by 32- or 64-bit reference (Alpha) mechanism: by 32-bit reference (VAX)
AST service routine to be executed. On Alpha systems, the astadr argument is the 32- or 64-bit address of this routine. On VAX systems, the astadr argument is the 32-bit address of this routine.astprm
OpenVMS usage: user_arg type: quadword (unsigned) access: read only mechanism: by 64-bit value (Alpha) mechanism: by 32-bit value (VAX)
AST parameter to be passed to the AST routine specified by the astadr argument. On Alpha sytems, the astprm argument is a quadword value containing this parameter. On VAX systems, the astprm argument is a longword value containing this parameter.acmode
OpenVMS usage: access_mode type: longword (unsigned) access: read only mechanism: by value
Access mode for which the AST is to be declared. The most privileged access mode used is the access mode of the caller. The resultant mode is the access mode for which the AST is declared.
The Declare AST service queues an AST for the calling access mode or for a less privileged access mode. For example, a routine executing in supervisor mode can declare an AST for either supervisor or user mode.The service does not validate the address of the AST service routine. If you specify an illegal address (such as 0), an access violation occurs when the AST service routine is given control.
None
The $DCLAST service requires system dynamic memory and uses the AST limit (ASTLM) quota of the process.
$SETAST, $SETPRA
SS$_NORMAL The service completed successfully. SS$_EXQUOTA The process has exceeded its AST limit (ASTLM) quota. SS$_INSFMEM The system dynamic memory is insufficient for completing the service.
| Previous | Next | Contents | Index |
|
|
![[OpenVMS documentation]](../../images/openvms_doc_banner_bottom.gif) |
|
Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal |
4527PRO_025.HTML
|