help for msdirb(Roger Newson)

Create a dataset of file names from the output of a MS-DOS dir/b command

msdirb [ , dirspec(dir_spec) filespec(file_spec)
dname(newvarname) fname(newvarname) dfname(newvarname)
clear lowercase
attribute(attribute_specs) sortorder(sort_order_specs)
]

lmsdirb [ , dirspec(dir_spec) filespec(file_spec)
dname(name) fname(name) dfname(name)
lowercase
attribute(attribute_specs) sortorder(sort_order_specs)
]

where dir_spec is a MS-DOS directory specification, file_spec is a MS-DOS file list specification,
attribute_specs is a MS-DOS attribute specification recognised by the MS-DOS dir command,
and sort_order_specs is a MS-DOS sort order specification recognised by the MS-DOS dir command.
For more about these specifications, see the MS-DOS online help under help dir in MS-DOS,
or refer to Jamsa (1993).

Description

msdirb inputs a directory specification and a file list specification recognised by MS-DOS,
and generates in the memory a new Stata dataset, with 1 observation per file in the list,
and data on the directory and/or the name of the file.
This new Stata dataset can then be used for mass-processing of the specified files.
lmsdirb inputs a directory specification and a file list specification recognised by MS-DOS,
and generates local macros containing lists, with 1 list item per file in the list,
and data on the directory and/or the name of the file.
msdirb and lmsdirb work by using the MS-DOS dir command,
with the switch /b to specify display of filenames only.
They are designed to work only under a Microsoft Windows operating environment.

Options for msdirb and lmsdirb

dirspec(dir_spec) specifies a directory in the language of MS-DOS.
This directory is where the specified files are located.
If not supplied, then it is set to dirspec(.),
specifying the current working directory,
which can be found by typing pwd in Stata.
The specification may be an absolute directory location,
or a relative directory location specified from the current working directory.
For instance, dirspec(..) specifies the parent directory of the current directory,
and dirspec(..\..\myfolder) specifies a subdirectory myfolder,
located in the grandparent directory of the current directory.
Note that msdirb replaces all forward slashes in the dirspec() option with backward slashes,
to harmonize with MS-DOS conventions.
For instance, dirspec(../../myfolder) is interpreted as dirspec(..\..\myfolder).

filespec(file_spec) specifies a list of files in the directory specified by the dirspec() option,
in the language of MS-DOS.
If not specified, then it is set to filespec(*),
specifying the set of all files in the directory specified by dirspec(),
or possibly a variant of this set,
after modification by the attribute() option
(see below).
These file specifications may contain wildcards such as *.
For instance, filespec(*.txt) specifies a list of all files with the extension .txt.

lowercase specifies that the directory and file specifications in the output dataset will contain only lower case letters.
If lowercase is absent,
then the directory and file specifications may contain upper case letters.

attribute(attribute_specs) specifies a file attribute specification,
recognised as a suboption list for the /a switch of the MS-DOS dir command,
which specifies subsets of files.
For instance, attribute(d) specifies that only directories will be included.
The prefix - specifies exclusions.
For instance, attribute(-d) specifies that only non-directories will be included.

sortorder(sort_order_specs) specifies th a sorting order specification,
recognised as a suboption list for the /o switch of the MS-DOS dir command.
For instance, sortorder(n) specifies sorting by ascending alphanumeric order of file name.
The prefix - is used to specify descending sorts.
For instance, sortorder(-n) specifies sorting by descending alphanumeric order of file name.

Options for msdirb only

dname(varname) specifies the name for a variable in the output dataset,
containing the directory specification.
This variable will have the same value in all the observations of the output dataset.
If dname() is unset, then such a variable will not be present in the output dataset.

fname(varname) specifies the name for a variable in the output dataset,
containing the filename without the directory specification.
If fname() is unset, then such a variable will not be present in the output dataset.

dfname(varname) specifies the name for a variable in the output dataset,
containing the filename with the directory specification.
The directory specification will be separated from the filename by a backslash character ("\").
If dfname() is unset, then such a variable will not be present in the output dataset.

Note that the user must specify one of the 3 options dname(), fname(),
and/or dfname().

clear specifies that the output dataset will overwrite any existing dataset that may be present in the memory.
If clear is not specified,
then msdirb will refuse to create an output dataset if data are already in memory.
This convention protects the user from deleting important data.

Options for lmsdirb only

dname(name) specifies the name for a local macro,
containing the list of directory specifications.
This list will have the same value in all items.
If dname() is unset, then such a macro will not be created.

fname(name) specifies the name for a local macro,
containing the list of filenames without the directory specifications.
If fname() is unset, then such a macro will not be created.

dfname(name) specifies the name for a local macro,
containing the list of filenames with the directory specifications.
The directory specifications will be separated from the filenames by a backslash character ("\").
If dfname() is unset, then such a macro will not be created.

Note that the user must specify one of the 3 options dname(), fname(),
and/or dfname().

Examples

The following example creates a dataset of all filenames with the extension .txt in the current directory,
with a single variable containing the file name:

. msdirb, filespec(*.txt) fname(filename) clear

. describe, full

. list

The following example creates a dataset of all filenames with the extension .txt in the directory .\mysub1,
with separate variables containing the directory specification, the short file name, and the full file name,
sorted in ascending name order:

. msdirb, dirspec(.\mysub1) filespec(*.txt) dname(folder) fname(shortname) dfname(fullname) sortorder(n) clear

. describe, full

. list

The following example creates a dataset of all directory names in the parental folder,
and a single variable containing the directory name as a file in the parental filder,
sorted in ascending name order:

. msdirb, dirspec(..) dfname(fulldir) sortorder(n) attribute(d) clear

. describe, full

. list

The following example uses lmsdirb to create a local macro paths,
containing a list of all files with the extension .txt
in the directory .\mysub1.
It then uses the tfconcat module of the intext package
to concatenate these text files into a Stata dataset in memory,
with 1 string variable line1,
containing the lines of all the concatenated .txt files.
The intext package is downloadable from SSC.

. lmsdirb, dirspec(.\mysub1) filespec(*.txt) dfname(paths)

. tfconcat `paths', gene(line)

. describe, full

. list

Author

Roger Newson, Imperial College London, UK.

Email: r.newson@imperial.ac.uk

References

Jamsa, K.
1993.
DOS: the Pocket Reference. Third Edition.
Berkeley, CA: McGraw-Hill.

Also see

Manual: [D] shell, [D] insheet, [D] cd

On-line: help for shell, insheet, pwd, cd

help for tfconcat, intext if installed

MS-DOS help for the dir command under help dir in MS-DOS