 |
HP OpenVMS System Services Reference Manual
When the auxiliary output buffer is provided, all addresses returned in
the item list point to locations in the auxiliary output buffer.
retlen
| OpenVMS usage: |
word_unsigned |
| type: |
word (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Length of the auxiliary buffer. The retlen argument is
the address of a word into which $FILESCAN writes the length of the
auxiliary buffer name string.
Item Codes
FSCN$_DEVICE
Returns the length and starting address of the device name. The device
name includes the single colon (:).
FSCN$_DIRECTORY
Returns the length and starting address of the directory name. The
directory name includes the brackets ([ ]) or angle brackets (<
>).
FSCN$_FILESPEC
Returns the length and starting address of the full file specification.
The full file specification contains the node, device, directory, name,
type, and version.
FSCN$_NAME
Returns the length and starting address of the file name. The file name
includes no syntactical elements.
$FILESCAN also returns the length and starting address of a quoted file
specification following a node specification (as in the specification
NODE::"FILE-SPEC"). The beginning and ending quotation marks
are included.
If there is no name component but there is either a type or version
component, the flags argument for FSCN$V_NAME is set and the address
field contains a nonzero pointer (pointing to the period for the type
component); however, the length field does contain zero.
FSCN$_NODE
Returns the length and starting address of the full node specification.
The full node specification includes the primary node name, the primary
node's access control string, any secondary node information, and the
final double colon (::).
FSCN$_NODE_ACS
Returns the length and starting address of the primary access control
string. If multiple nodes are specified, the primary access control
string represents the control information (if present) for the first
node specified. The primary access control string does not contain the
double colon (::), but does contain the double quotes.
FSCN$_NODE_PRIMARY
Returns the length and starting address of the primary node name. If
multiple nodes are specified, the primary node name represents the
first node specification. The node name does not include the double
colon (::) or any access control information. If an auxiliary output
buffer is specified, quotation information is reduced and simplified
for only the primary node.
FSCN$_NODE_SECONDARY
Returns the length and starting address of any secondary node
information. The secondary node string contains any node information
referring to additional nodes, including the final double colon (::),
as well as any access control strings (if present) for the additional
nodes.
FSCN$_ROOT
Returns the length and starting address of the root directory string.
The root directory name string includes the brackets ([ ]) or angle
brackets (< >).
FSCN$_TYPE
Returns the length and starting address of the file type. The file type
includes the preceding period (.).
FSCN$_VERSION
Returns the length and starting address of the file version number. The
file version number includes the preceding period (.) or semicolon (;)
delimiter.
Description
The Scan String for File Specification service searches a string for a
file specification and parses the components of that file
specification. When $FILESCAN locates a partial file specification (for
example, DISK:[FOO]), it returns the length and starting address of
those components that were requested in the item list and were found in
the string. If a component was requested in the item list but not found
in the string, $FILESCAN returns a length of 0 and an address of 0 to
the component address field in the item descriptor for that component
(see item code FSCB$_NAME for exception).
The information returned about all of the individual components
describes the entire contiguous file specification string. For example,
to extract only the file name and file type from a full file
specification string, you can add the length of these two components
and use the address of the first component (file name). However, the
specific node name and node control strings extracted using the
FSCN$_NODE_PRIMARY and FSCN$_NODE_ACS item codes cannot be recombined
because the double colon (::) is not included in either string.
If an auxiliary output buffer is provided, $FILESCAN copies the entire
source string, removing and reducing quotation marks from the primary
node name.
The $FILESCAN service does not perform comprehensive syntax checking.
Specifically, it does not check that a component has a valid length.
However, $FILESCAN does check for the following information:
- The component must have required syntactical elements; for example,
a directory component must be enclosed in brackets ([]), and a node
name must be followed by an unquoted double colon (::).
- The component must not contain invalid characters. Invalid
characters are specific to each component. For example, a comma (,) is
a valid character in a directory component but not in a file type
component.
- Spaces, tabs, and carriage returns are permitted within quoted
strings, but are invalid anywhere else.
- If a node name contains a space, tab, double quote ("), or double
colon (::), then the node name must be quoted.
The node component of a file specification contains one or more node
specifications. A node specification is a node name, followed by an
optional access control string, followed by a double colon (::). A node
name is either a standard name or a quoted name.
If the node name contains quotation marks, the quotes must be doubled
("") and the entire node name quoted. For example, the node
abc"def" would be represented as "abc""def""". An access
control string is a quoted string containing a user name, an optional
password, and an optional account name. Note that the double quotes are
only used to differentiate between a primary node name containing
embedded quotes and the access control string. See the Example section
for the proper use of this syntax.
Invalid characters are treated as terminators. For example, if
$FILESCAN encounters a space within a file name component, it assumes
that the space terminates the full file specification string.
For node names, a space, tab, double quote ("), and comma (,) are
treated as terminators and must be quoted if they are part of the node
name. In addition, the double colon (::) and the trailing colon (for
example, NODE:) are treated as terminators and must also be quoted if
they are part of the node name.
The $FILESCAN service recognizes the DEC Multinational alphabetical
characters (such as à) as alphanumeric characters.
The $FILESCAN service accepts extended (ODS-5) file names. The parsing
types and names are independent of the volume they reside on;
therefore, if the device name points to an ODS-2 volume, you can
specify an ODS-5 file name. Refer to the Guide to OpenVMS File Applications for information
on ODS-5 file specifications.
The $FILESCAN service does not (1) assume default values for
unspecified file specification components, (2) perform logical name
translation on components, (3) perform wildcard processing, or (4)
perform directory lookups.
Required Access or Privileges
None
Required Quota
None
Related Services
$ALLOC, $ASSIGN, $BRKTHRU, $BRKTHRUW, $CANCEL, $CREMBX, $DALLOC,
$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 service could not read the string pointed to by the
srcstr argument; or it could not write to an item
descriptor in the item list specified by the
valuelst argument; or it could not write to the
specified auxiliary output buffer; or the
retlen argument could not be written.
|
|
SS$_BADPARAM
|
The item list contains an invalid item code.
|
Example
|
! The following is a C example for using the $FILESCAN service.
#include <perror.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <descrip.h>
#include <iledef.h>
#include <fscndef.h>
#include <starlet.h>
#include <ssdef.h>
//
// Build table of names. Verify positions in table.
//
#if FSCN$_FILESPEC != 1
#error "table assumption for FILESPEC is invalid."
#endif
#if FSCN$_NODE_SECONDARY != 11
#error "table assumption for NODE_SECONDARY is invalid."
#endif
char *name_field[] = {
"",
"FILESPEC",
"NODE",
"DEVICE",
"ROOT",
"DIRECTORY",
"NAME",
"TYPE",
"VERSION",
"NODE_PRIMARY",
"NODE_ACS",
"NODE_SECONDARY" } ;
typedef struct fldflags FLDFLAGS ;
main(int argc, char *argv[] )
{
int status ;
int field_flags ;
char *filename;
struct dsc$descriptor_s file_name = { 0 } ;
struct dsc$descriptor_s output_string = { 0 } ;
short retlen ;
int i ;
ile2 itmlst[] = {
{0, FSCN$_FILESPEC, 0},
{0, FSCN$_NODE, 0},
{0, FSCN$_DEVICE, 0},
{0, FSCN$_ROOT, 0},
{0, FSCN$_DIRECTORY, 0},
{0, FSCN$_NAME, 0},
{0, FSCN$_TYPE, 0},
{0, FSCN$_VERSION, 0},
{0, FSCN$_NODE_PRIMARY, 0},
{0, FSCN$_NODE_ACS, 0},
{0, FSCN$_NODE_SECONDARY, 0},
{ 0, 0, 0 } } ;
output_string.dsc$w_length = 4096 ;
if ((output_string.dsc$a_pointer = malloc(4096)) == NULL) {
perror("Malloc Failure");
exit(0) ;
}
if ((file_name.dsc$a_pointer = filename = malloc(4096)) == NULL) {
perror("Malloc Failure");
exit(0) ;
}
for( ;; ) {
printf("\nEnter file name: ") ;
if (gets(filename) == NULL)
break ;
file_name.dsc$w_length = strlen(filename) ;
status = sys$filescan( &file_name, itmlst, &field_flags,
&output_string, &retlen) ;
if (!(status&1)) exit(status) ;
if ((itmlst[0].ile2$ps_bufaddr != NULL) && (retlen != 0))
printf("The file name returned is %.*s\n", retlen,
(char*)itmlst[0].ile2$ps_bufaddr ) ;
else
printf("There is no file name returned for FSCN$_FILESPEC\n");
for( i = 0; i < FSCN$_NODE_SECONDARY; i++) {
if ((int)field_flags & 1<<i)
printf("The component %s is present: %.*s\n", name_field[i+2],
itmlst[i+1].ile2$w_length,
(char*)itmlst[i+1].ile2$ps_bufaddr ) ;
}
}
exit(status) ;
}
|
This C example demonstrates the use of the $FILESCAN service.
Following is an example of the program output:
$ RUN TEST_SCAN
Enter file name: abc"def"
The file name is abc"def"
The component NAME is present: abc
Enter file name: "abc""def"""
There is no file name returned for FSCN$_FILESPEC
Enter file name: "abc""def"""::
The file name is abc"def"::
The component NODE is present: abc"def"::
The component NODE_PRIMARY is present: abc"def"
Enter file name: "abc""def""""user password"::
The file name is abc"def""user password"::
The component NODE is present: abc"def""user password"::
The component NODE_PRIMARY is present: abc"def"
The component NODE_ACS is present: "user password"
Enter file name: abc"def"::
The file name is abc"def"::
The component NODE is present: abc"def"::
The component NODE_PRIMARY is present: abc
The component NODE_ACS is present: "def"
Enter file name: "abc""def""""system password"::[dir.1]a^ ^".file;1
The file name returned is abc"def""system password"::[dir.1]a^ ^".file;1
The component NODE is present: abc"def""system password"::
The component DIRECTORY is present: [dir.1]
The component NAME is present: a^ ^"
The component TYPE is present: .file
The component VERSION is present: ;1
The component NODE_PRIMARY is present: abc"def"
The component NODE_ACS is present: "system password"
|
$FIND
The Find service locates a specified record in a file and returns its
record file address in the RAB$W_RFA field of the RAB. The Find service
can be used with all file organizations.
For additional information about this service, see the OpenVMS Record Management Services Reference Manual.
$FIND_HELD
Returns the identifiers held by a specified holder.
Format
SYS$FIND_HELD holder ,[id] ,[attrib] ,[contxt]
C Prototype
int sys$find_held (struct _generic_64 *holder, unsigned int *id,
unsigned int *attrib, unsigned int *contxt);
Arguments
holder
| OpenVMS usage: |
rights_holder |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Holder whose identifiers are to be found when $FIND_HELD completes
execution. The holder argument is the address of a
quadword data structure containing the holder identifier. This quadword
data structure consists of a longword containing the holder UIC,
followed by a longword containing the value 0.
id
| OpenVMS usage: |
rights_id |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Identifier value found when $FIND_HELD completes execution. The
id argument is the address of a longword containing
the identifier value with which the holder is associated.
attrib
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Attributes associated with the holder returned in id
when $FIND_HELD completes execution. The attrib
argument is the address of a longword containing a bit mask specifying
the attributes.
Symbol values are offsets to the bits within the longword. You can also
obtain the values as masks with the appropriate bit set using the
prefix KGB$M rather than KGB$V. The symbols are defined in the system
macro library ($KGBDEF). The following are the symbols for each bit
position:
| Bit Position |
Meaning When Set |
|
KGB$V_DYNAMIC
|
Allows holders of the identifier to remove it from or add it to the
process rights list by using the DCL command SET RIGHTS_LIST.
|
|
KGB$V_NOACCESS
|
Makes any access rights of the identifier null and void. This attribute
is intended as a modifier for a resource identifier or the Subsystem
attribute.
|
|
KGB$V_RESOURCE
|
Allows the holder to charge resources, such as disk blocks, to the
identifier.
|
|
KGB$V_SUBSYSTEM
|
Allows holders of the identifier to create and maintain protected
subsystems by assigning the Subsystem ACE to the application images in
the subsystem.
|
contxt
| OpenVMS usage: |
context |
| type: |
longword (unsigned) |
| access: |
modify |
| mechanism: |
by reference |
Context value used when repeatedly calling $FIND_HELD. The
contxt argument is the address of a longword used
while searching for all identifiers. The context value must be
initialized to 0, and the resulting context of each call to $FIND_HELD
must be presented to each subsequent call. After
contxt is passed to $FIND_HELD, you must not modify
its value.
Description
The Find Identifiers Held by User service returns a list of the
identifiers that another identifier holds. Use the $FIND_HELD service
to construct the process rights when a user logs in (unless that
process has read access to the rights database). To determine all the
identifiers held by the specified holder, call $FIND_HELD repeatedly
until it returns the status code SS$_NOSUCHID. When SS$_NOSUCHID is
returned, $FIND_HELD has returned all the identifiers, cleared the
context value, and deallocated the record stream.
If you complete your calls to $FIND_HELD before SS$_NOSUCHID is
returned, use $FINISH_RDB to clear the context value and deallocate the
record stream.
Note that, when you use wildcards with this service, the records are
returned in the order that they were originally written because the
first record is located on the basis of the holder ID. Thus, all the
target records have the same holder ID or, in other words, they have
duplicate keys, which leads to retrieval in the order in which they
were written.
Required Access or Privileges
Read access to the rights database is required to obtain information
about identifiers held by other users.
Required Quota
None
Related Services
$ADD_HOLDER, $ADD_IDENT, $ASCTOID, $CREATE_RDB, $FIND_HOLDER,
$FINISH_RDB, $GRANTID, $IDTOASC, $MOD_HOLDER, $MOD_IDENT, $REM_HOLDER,
$REM_IDENT, $REVOKID
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_ACCVIO
|
The
id argument cannot be written by the service, or the
holder,
attrib, or
contxt argument cannot be read by the service.
|
|
SS$_IVCHAN
|
The contents of the
contxt longword are not valid.
|
|
SS$_INSFMEM
|
The process dynamic memory is insufficient for opening the rights
database.
|
|
SS$_IVIDENT
|
The format of the specified holder identifier is invalid.
|
|
SS$_NOIOCHAN
|
No more rights database context streams are available.
|
|
SS$_NOSUCHID
|
The specified holder identifier does not exist, or no further
identifiers are held by the specified holder.
|
|
RMS$_PRV
|
You do not have read access to the rights database.
|
Because the rights database is an indexed file accessed with OpenVMS
RMS, this service can also return RMS status codes associated with
operations on indexed files. For descriptions of these status codes,
refer to the OpenVMS Record Management Services Reference Manual.
$FIND_HOLDER
Returns the holder of a specified identifier.
Format
SYS$FIND_HOLDER id ,[holder] ,[attrib] ,[contxt]
C Prototype
int sys$find_holder (unsigned int id, struct _generic_64 *holder,
unsigned int *attrib, unsigned int *contxt);
Arguments
id
| OpenVMS usage: |
rights_id |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Binary identifier value whose holders are found by $FIND_HOLDER. The
id argument is a longword containing the binary
identifier value.
holder
| OpenVMS usage: |
rights_holder |
| type: |
quadword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Holder identifier returned when $FIND_HOLDER completes execution. The
holder argument is the address of a quadword
containing the holder identifier. The first longword contains the UIC
of the holder with the high-order word containing the group number and
the low-order word containing the member number. The second longword
contains the value 0.
attrib
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Mask of attributes associated with the holder record specified by
holder. The attrib argument is the
address of a longword containing the attribute mask.
Symbol values are offsets to the bits within the longword. You can also
obtain the values as masks with the appropriate bit set using the
prefix KGB$M rather than KGB$V. The symbols are defined in the system
macro library ($KGBDEF). The following are the symbols for each bit
position:
| Bit Position |
Meaning When Set |
|
KGB$V_DYNAMIC
|
Allows holders of the identifier to remove it from or add it to the
process rights list by using the DCL command SET RIGHTS_LIST. For more
information about SET RIGHTS_LIST, see the HP OpenVMS DCL Dictionary.
|
|
KGB$V_NOACCESS
|
Makes any rights of the identifier null and void. This attribute is
intended as a modifier for a resource identifier or the Subsystem
attribute.
|
|
KGB$V_RESOURCE
|
Allows the holder of an identifier to charge disk space to the
identifier. It is used only for file objects.
|
|
KGB$V_SUBSYSTEM
|
Allows holders of an identifier to create and maintain protected
subsystems by assigning the Subsystem ACE to the application images in
the subsystem.
|
contxt
| OpenVMS usage: |
context |
| type: |
longword (unsigned) |
| access: |
modify |
| mechanism: |
by reference |
Context value used while searching for all the holders of the specified
identifier when executing $FIND_HOLDER. The contxt
argument is the address of a longword containing the context value.
When calling $FIND_HOLDER repeatedly, contxt must be
set initially to 0 and the resulting context of each call to
$FIND_HOLDER must be presented to each subsequent call. After the
argument is passed to $FIND_HOLDER, you must not modify its value.
Description
The Find Holder of Identifier service returns the holder of the
specified identifier. To determine all the holders of the specified
identifier, you call SYS$FIND_HOLDER repeatedly until it returns the
status code SS$_NOSUCHID, which indicates that $FIND_HOLDER has
returned all identifiers, cleared the context longword, and deallocated
the record stream. If you complete your calls to $FIND_HOLDER before
SS$_NOSUCHID is returned, you use the $FINISH_RDB service to clear the
context value and deallocate the record stream.
Note that when you use wildcards with this service, the records are
returned in the order in which they were originally written. (This
action results from the fact that the first record is located on the
basis of the identifier. Thus, all the target records have the same
identifier or, in other words, they have duplicate keys, which leads to
retrieval in the order in which they were written.)
Required Access or Privileges
Read access to the rights database is required to obtain information
about identifiers marked HOLDER_HIDDEN.
Required Quota
None
Related Services
$ADD_HOLDER, $ADD_IDENT, $ASCTOID, $CREATE_RDB, $FIND_HELD,
$FINISH_RDB, $GRANTID, $IDTOASC, $MOD_HOLDER, $MOD_IDENT, $REM_HOLDER,
$REM_IDENT, $REVOKID
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_ACCVIO
|
The
id argument cannot be read by the caller, or the
holder,
attrib, or
contxt argument cannot be written by the caller.
|
|
SS$_IVCHAN
|
The contents of the
contxt longword are not valid.
|
|
SS$_INSFMEM
|
The process dynamic memory is insufficient for opening the rights
database.
|
|
SS$_IVIDENT
|
The specified identifier or holder identifier is of invalid format.
|
|
SS$_NOIOCHAN
|
No more rights database context streams are available.
|
|
SS$_NOSUCHID
|
The specified identifier does not exist in the rights database, or no
further holders exist for the specified identifier.
|
|
RMS$_PRV
|
The user does not have read access to the rights database.
|
Because the rights database is an indexed file accessed with OpenVMS
RMS, this service can also return RMS status codes associated with
operations on indexed files. For descriptions of these status codes,
see the OpenVMS Record Management Services Reference Manual.
|
