VMS Help System Services, $FILESCAN  *Conan The Librarian (sorry for the slow response - running on an old VAX)

    Searches a string for a file specification and parses the
    components of that file specification.

    Format

      SYS$FILESCAN  srcstr ,valuelst ,[fldflags] ,[auxout] ,[retlen]

    C Prototype

      int sys$filescan  (void *srcstr, void *valuelst, unsigned int

                        *fldflags, void *auxout, unsigned short int

                        *retlen);

1 - Arguments

 srcstr

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    String to be searched for the file specification. The srcstr
    argument is the address of a descriptor pointing to this string.

 valuelst

    OpenVMS usage:item_list_2
    type:         longword (unsigned)
    access:       modify
    mechanism:    by reference
    Item list specifying which components of the file specification
    are to be returned by $FILESCAN. The components are the full node
    specification, primary node name, primary node's access control,
    secondary node information, device, directory, file name, file
    type, and version number. The itmlst argument is the address of a
    list of item descriptors wherein each item descriptor specifies
    one component. The list of item descriptors is terminated by a
    longword of 0.

    Refer to the OpenVMS System Services Reference Manual to view the
    item code diagram and descriptor fields table.

 fldflags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference
    Longword flag mask in which $FILESCAN sets a bit for each file
    specification component found in the input string. The fldflags
    argument is the address of this longword flag mask.

    The $FSCNDEF macro defines a symbolic name for each significant
    flag bit. The following table shows the file specification
    component that corresponds to the symbolic name of each flag
    bit:

    Symbolic Name    Corresponding Component

    FSCN$V_DEVICE    Device name
    FSCN$V_          Directory name
    DIRECTORY
    FSCN$V_NAME      File name
    FSCN$V_NODE      Node name
    FSCN$V_NODE_ACS  Access control string of primary node
    FSCN$V_NODE_     Primary (first) node name
    PRIMARY
    FSCN$V_NODE_     Secondary (additional) node information
    SECONDARY
    FSCN$V_ROOT      Root directory name string
    FSCN$V_TYPE      File type
    FSCN$V_VERSION   Version number

    The fldflags argument is optional. When you want to know which
    components of a file specification are present in a string but
    do not need to know the contents or length of these components,
    specify fldflags instead of valuelst.

 auxout

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       write only
    mechanism:    by descriptor-fixed-length string descriptor
    Auxiliary output buffer. The auxout argument is the address of a
    character-string descriptor pointing to the auxiliary buffer.

    When you specify an auxiliary output buffer, $FILESCAN copies
    the entire source string, with quotation information reduced and
    simplified for only the primary node, into the auxiliary output
    buffer.

    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.