-------------------------------------------------------------------------------
help for stcmd, inputst, outputst and outputstold                (Roger Newson)
-------------------------------------------------------------------------------


Running the Stat/Transfer command from inside Stata

        stcmd [ filetype1 ] infilename.ext1 [ filetype2 ] outfilename.ext2 [
                     switches ]

        stcmd command_filename.stcmd

        inputst [ filetype ] infilename.ext [ switches ]

        outputst [ filetype ] outfilename.ext [ switches ]

        outputstold [ filetype ] outfilename.ext [ switches ]


Description

    stcmd calls the Stat/Transfer command st to convert the data file
    infilename.ext1 to a new data file outfilename.ext2, or to obey the
    commands in the Stat/Transfer command file command_filename.stcmd.
    inputst inputs into the memory a Stata-converted version of the data file
    infilename.ext, overwriting any existing dataset.  outputst outputs a
    converted version of the Stata dataset in memory to the data file
    outfilename.ext.  outputstold is an alternative version of outputst, for
    use if the user's version of Stat/Transfer is not advanced enough to read
    datasets in the format of the user's version of Stata.  File types are
    determined by filetype, filetype1 and/or filetype2, if present, and by
    Stat/Transfer from the extensions ext, ext1 and/or ext2 otherwise.  File
    names containing spaces must be given in quotes.  stcmd, inputst or
    outputst output a running commentary on the transfer process (including
    the Stat/Transfer command to be submitted) to the Stata log or Results
    window, unless the user uses the quietly prefix.


Switches for use with  stcmd, inputst, outputst and outputstold

    These are prefixed by / under Windows and by - under Unix.  A list of
    these switches can be found in the Stat/Transfer manual for the user's
    installation.  The Windows switches for Version 9 of Stat/Transfer are as
    follows:

    /o- specifies that Stat/Transfer will not optimize the output data set to
        be as small as possible (as Stat/Transfer does by default).

    /oc specifies that Stat/Transfer will optimize the output data set to be
        as small as possible, and automatically drop constant or missing
        variables.

    /od specifies that Stat/Transfer will optimize the output data set to be
        as small as possible, but produce double precision variables where
        appropriate.

    /ocd specifies that Stat/Transfer will optimize the output data set to be
        as small as possible, and automatically drop constant or missing
        variables, but produce double precision variables where appropriate.

    /q specifies that Stat/Transfer will execute quietly, producing no
        messages, with the exception of error messages and warnings that a
        file is about to be overwritten.

    /r[page!]coor specifies a worksheet range, limited to page page and
        coordinates specified by coor, in an input worksheet file.  The
        coordinates specify a top left and bottom right cell in the
        worksheet.  For instance, /r2!b5:e75 specifies that the data are on
        page 2 of the input file, between the top left cell b5 and the bottom
        right cell e75.

    /s will turn on messages and leave the Stat/Transfer window open until
        the return key is pressed.  This may be useful if Stat/Transfer
        appears not to be working.

    /ttablename is used in order to specify a table (or worksheet) within a
        data source containing multiple tables (or worksheets).

    /vversion_number specifies that Stat/Transfer will write the output
        dataset in the version of the appropriate format specified by the
        version_number, which should be a positive integer.  If this switch
        is not specified, then Stat/Transfer writes the output dataset in the
        latest version of the appropriate format.

    /y specifies that outfilename.ext will be overwritten, if it already
        exists.  (If /y is not specified, then Stat/Transfer consults the
        user before overwriting files.)


Remarks

    Stat/Transfer can be installed on Microsoft Windows, MacOS, and some Unix
    platforms.  It is available from Stata Corporation and developed by
    Circle Systems.

    inputst, outputst and outputstold call stcmd, which in turn calls the
    Stat/Transfer st command.  For a list of file types and standard
    extensions used by Stat/Transfer, see the Stat/Transfer manual or on-line
    help.

    inputst, outputst and outputstold all use temporary Stata datafiles to
    pass the data in the memory to and from Stat/Transfer.  These temporary
    Stata datafiles are automatically deleted when inputst and outputst
    finish execution.  In the case of outputstold, the temporary Stata
    datafile is written using saveold, and will be in the format of an
    earlier Stata version, which may be recognized by out-of-date versions of
    Stat/Transfer.  If the user does not use the quietly prefix, then inputst
    and outputst give a running commentary to the user on the creation of
    these temporary Stata datafiles, and on their use as input or output by
    Stata and Stat/Transfer.  This is done in order to inform the user of the
    state of progress of the transfer, in case the transfer is not completed
    successfully.  The /s or -s switch mentioned above, may also be useful,
    if Stat/Transfer does not appear to be working.

Technical notes

    The path for the Stat/Transfer st command varies from system to system.
    stcmd assumes that this path is simply st, unless the global macro
    StatTransfer_path is evaluated, in which case stcmd assumes that the path
    is equal to the value of that macro.  Therefore, if the directory
    containing Stat/Transfer is on the user's default path, then the user
    need not set a value for the global macro StatTransfer_path.  Otherwise,
    the user should set a value for the global macro StatTransfer_path.  This
    is probably done most easily by inserting a line into the user's profile
    do-file to initialize this global macro every time the user starts Stata.
    For instance, under Windows, if the user's profile do-file contains the
    line

        . global StatTransfer_path `"c:\Program Files\StatTransfer10\st.exe"'

    and the st program of Stat/Transfer, in the user's system, has path
    "c:\Program Files\StatTransfer10\st.exe", then stcmd will find the st
    command of Stat/Transfer correctly on that path.

    Note that, when the user upgrades to a new version of Stat/Transfer, the
    upgrade creates a new directory, containing the new version of st.exe.
    Therefore, when Stat/Transfer is upgraded, either the user's default
    directory search path should be altered, or the line of code in the
    user's profile do-file setting the global macro StatTransfer_path should
    be altered.

    The user may also find, after a Stat/Transfer upgrade, that the stcmd
    package has been downgraded to Stata Version 6.  This is because the
    Stat/Transfer installation program may install the Stata Version 6
    version of Stat/Transfer in the user's PERSONAL directory (see help for 
    adopath).  This installation in the PERSONAL directory typically contains
    the Stata Version 6 files stcmd.ado, inputst.ado, outputst.ado,
    stcmd.hlp, inputst.hlp, and outputst.hlp.  If the user has a higher
    version of Stat/Transfer installed in a directory in a position after
    PERSONAL of the adopath, then the user should probably remove these files
    from the PERSONAL directory.  After the user has done this, Stata will
    use the higher version of stcmd.


Examples

        . inputst spss.sav

        . outputst mydata.Rdata /y

        . inputst mydata.Rdata /o-

        . stcmd R mydata.Rdata hisdata.csv /y
        . insheet using hisdata.csv, comma clear

        . stcmd mystcom.stcmd


Author

    Roger Newson, National Heart and Lung Institute, Imperial College London,
    UK.
    Email: r.newson@imperial.ac.uk


Also see

     Manual: [P] macro, [P] sysdir, [D] save,
             [GSW] C.3 Executing commands every time Stata is started,
             [GSM] C.1 Executing commands every time Stata is started,
             [GSU] C.1 Executing commands every time Stata is started
    On-line: help for macro, adopath, sysdir, saveold, profile, profilew, 
             profilem, profileu
      Other: Stat/Transfer .PDF Manual if installed