 |
HP OpenVMS System Services Reference Manual
$CVT_FILENAME (Alpha and I64)
Converts a string from RMS format to file-system (ACP-QIO) format or
from file-system (ACP-QIO) format to RMS format.
Format
SYS$CVT_FILENAME cvttyp ,srcstr ,inflags ,outbuf ,outlen ,outflags
C Prototype
int sys$cvt_filename (unsigned int cvttyp, void *srcstr, unsigned int
inflags, void *outbuf, unsigned short int *outlen, unsigned int
*outflags);
Arguments
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.
Description
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.
Required Access or Privileges
None.
Required Quota
None.
Related Services
None.
Condition Values Returned
|
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.
|
$DACEFC
Releases the calling process's association with a common event flag
cluster.
Format
SYS$DACEFC efn
C Prototype
int sys$dacefc (unsigned int efn);
Argument
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.
Description
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.
Required Access or Privileges
A calling process must have PRMCEB privilege to delete a permanent
common event flag cluster.
Required Quota
None
Related Services
$ASCEFC, $CLREF, $DLCEFC, $READEF, $SETEF, $WAITFR, $WFLAND, $WFLOR
Condition Values Returned
|
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.
|
$DALLOC
Deallocates a previously allocated device.
Format
SYS$DALLOC [devnam] ,[acmode]
C Prototype
int sys$dalloc (void *devnam, unsigned int acmode);
Arguments
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.
Description
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.
Required Access or Privileges
None
Required Quota
None
Related Services
$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
Condition Values Returned
|
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.
|
$DASSGN
Deassigns (releases) an I/O channel previously acquired using the
Assign I/O Channel ($ASSIGN) service.
Format
SYS$DASSGN chan
C Prototype
int sys$dassgn (unsigned short int chan);
Argument
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.
Description
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.
Required Access or Privileges
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.
Required Quota
None
Related Services
$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
Condition Values Returned
|
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 or I64 systems, you specified an invalid channel number that
your process never assigned.
|
|
SS$_NOICHAN
|
On Alpha or I64 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.
|
$DCLAST
Queues an asynchronous system trap (AST) for the calling access mode or
for a less privileged access mode.
On Alpha and I64 systems, this service accepts 64-bit addresses.
Format
SYS$DCLAST astadr ,[astprm] ,[acmode]
C Prototype
int sys$dclast (void (*astadr)(__unknown_params), unsigned __int64
astprm, unsigned int acmode);
Arguments
astadr
| OpenVMS usage: |
ast_procedure |
| type: |
procedure value |
| access: |
call without stack unwinding |
| mechanism: |
by 32- or 64-bit reference (Alpha and I64) |
| mechanism: |
by 32-bit reference (VAX) |
AST service routine to be executed. On Alpha and I64 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 and I64) |
| mechanism: |
by 32-bit value (VAX) |
AST parameter to be passed to the AST routine specified by the
astadr argument. On Alpha and I64 systems, 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.
Description
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.
Required Access or Privileges
None
Required Quota
The $DCLAST service requires system dynamic memory and uses the AST
limit (ASTLM) quota of the process.
Related Services
$SETAST, $SETPRA
Condition Values Returned
|
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.
|
|
