From:	HENRY::IN%"carl%cithex.caltech.edu%kl.sri.com%csnet-relay.CSNET%relay.cs.net@RCA.COM" 15-JUN-1987 08:40
To:	gatech!hubcap!ncrcae!usceast!still@rutgers.edu, 
Subj:	Re: 2 questions: VAX-C RTL calls and VMS .DIR file entries

 > 	I have 2 (possibly) strange questions for netland. The first concerns
 > the VAX-C run-time library. Listed in the VAX-C manual are references to some
 > run-time functions that are otherwise undocumented. I did a lib/list on the
 > VAXCRTL.OLB file and verified that the following routines do exist:

 > 	shell$from_vms	-- translate VMS filespecs to UNIX filespecs
 > 	shell$to_vms    -- translate UNIX filespecs to VMS filespecs
 > 	shell$cli_name  -- determine user's command interpreter
 > 	shell$fix_time  -- convert VMS time to UNIX format
 > 	shell$clint     -- interface to argument lists under shell
 > 	shell$wild      -- wildcard expansion to infinite names.

 > Does anyone have a copy of the correct calling sequences for these ? (I have
 > tried to experiment, and can guess at some of the arguments, like string
 > descriptors, etc. but I cannot seem to get them all.) We do not run DEC/Shell
 > (yet, we probably will buy it in the future), and I suspect that the answer
 > lies therein. In the meantime, can some kind soul please send me a copy of
 > the calling sequences to any/all of the above?
 > 
    SHELL$FROM_VMS

            num_files_found =
            shell$from_vms( vms_filespec, action_routine, wild_flag )

           char *vms_filespec;
           int wild_flag;
           int action_routine();
           int shell$from_vms();

    SHELL$TO_VMS

            num_files_found =
            shell$to_vms( shell_filespec, action_routine, wild_flag )

           char *shell_filespec;
           int wild_flag;
           int action_routine();
           int shell$to_vms();

    SHELL$CLI_NAME

            status = shell$cli_name( cli_name_desc )

            # include descrip
            int shell$cli_name();
            struct dsc$descriptor *cli_name_desc;

    SHELL$FIX_TIME

            unxtim = shell$fix_time( vmstim )

            int quadword[2];
            int *vmstim = quadword;
            int shell$fix_time();

    SHELL$MATCH_WILD

            status = shell$match_wild( string, pattern )

            char *string;
            char *pattern;
            int shell$match_wild();


 > 	The second question concerns VMS directories. I have perused the
 > "orange manuals" for the last two weeks looking for something that describes
 > the VMS directory files' organization. So far, by dumping the contents of
 > several .DIR files, I have determined that the entries begin with 32767, and
 > filenames are followed by an ASCII null (\0), and that the version number
 > immediately follows the filename. Does anyone have a complete description of
 > an entry in a .DIR file, or know where I can find the information?

4.3  Directory Structure

A directory is a contiguous file, organized as a  sequential
file  with  variable  length records, with the attribute set
that records do not cross block boundaries, and no  carriage
control attributes.  Directory entries within each block are
packed together to conform to  the  variable  length  record
format;  a -1 byte count signals the end of records for that
block.  (See Section 6 for a discussion of record  formats.)
The  entries  in a directory are sorted alphabetically, per-
mitting the use of an optimized search.  Entries  which  are
multiple  versions of the same name and type are arranged in
order of decreasing version number to optimize  version  re-
lated  operations.   Each  directory  record consists of the
following:


          |---------------------------------------|
          |           Record Byte Count           |
          |---------------------------------------|
          |             Version Limit             |
          |-------------------|-------------------|
          |  Name Byte Count  |       Flags       |
          |-------------------|-------------------|
          |                                       |
          |                                       |
          |                                       |
          |           File Name String            |
          |                                       |
          |                                       |
          |                                       |
          |---------------------------------------|
          |                                       |
          |                                       |
          |              Value Field              |
          |                                       |
          |                                       |
          |---------------------------------------|



Count     This two byte field is  the  standard  byte  count
          field of a variable length record.

Limit     This word contains the maximum number of  versions
          that  are  to  be retained for this name and type.
          An attempt to enter more versions than  the  limit
          will  result  in  the deletion of the least recent
          version, or an error return, at  the  implementing
          system's option.

Flags     This byte contains the type code of the  directory
          entry  and  assorted flags bits.  The type code is
          contained in the three low bits of the flags byte.
          It is one of the following values:

          DV.FID    The value field is  a  list  of  version
                    numbers and 48 bit File ID's.
          DV.SLK    The  value  field  is  a  symbolic  link
                    string.

          The following flag bits are defined:

          DV.PRV    Set if the  preceding  directory  record
                    contains  the same name and type as this
                    one.
          DV.NXV    Set if the next  directory  record  con-
                    tains  the  same  name  and type as this
                    one.

Name      This field contains the  file  name  and  type  in
          ASCII,  separated  by  a  dot.  The dot is present
          even if either name, or type, or both,  are  null.
          Only  upper case alphabetic and numeric characters
          may be present in  the  name  and  type.   If  the
          length  of  the  name  is odd, it is padded with a
          single null.

Value     This field contains the "value" of  the  directory
          entry;  i.e., the information returned to the user
          from a lookup operation.  If the directory  record
          is  a File ID list (the type field is DV.FID), the
          value field is a list of version numbers and  cor-
          responding  file  ID's,  appearing  in  descending
          order by version number.  The number of entries in
          the list is deduced from the record byte count.


              |---------------------------------------|
              |            Version number             |
              |---------------------------------------|
              |                                       |
              |--                                   --|
              |                File ID                |
              |--                                   --|
              |                                       |
              |---------------------------------------|
              |            Version number             |
              |---------------------------------------|
              |                                       |
              |--                                   --|
              |                File ID                |
              |--                                   --|
              |                                       |
              |---------------------------------------|
              |                                       |
                                  |
                                  |
                                  |
                                  |
                                  |
              |                                       |
              |---------------------------------------|
              |            Version number             |
              |---------------------------------------|
              |                                       |
              |--                                   --|
              |                File ID                |
              |--                                   --|
              |                                       |
              |---------------------------------------|


Version   This word contains the version number of  the  di-
          rectory entry in binary.  Version numbers must lie
          in the range from 1 to 32767.

File ID   These three words are the file ID that the  direc-
          tory entry points to.

          If the directory entry is  a  symbolic  link  (the
          flags  byte contains DV.SLK), then the value field
          is variable length.  Its  first  byte  is  a  byte
          count,  and the remainder is an ASCII string which
          describes the linkage.  The string  is  padded  to
          the  next  word boundary with a null if necessary.
          The format is the following:


          |-------------------|-------------------|
          |                   |    Byte Count     |
          |--                 |-------------------|
          |                                       |
          |                                       |
          |                                       |
          |         Symbolic Link String          |
          |                                       |
          |                                       |
          |                                       |
          |---------------------------------------|
