Home  /  Resources & support  /  Stata for Mac  /  Stata 9 Console for Mac

Stata 9 Console for Mac

Last updated: 17 October 2006
Stata release: 9
Note:   the following section is recommended for Stata 9 users only. Stata 10 SE and MP both include console versions of Stata. Stata 10 users should see appendix D.5 Stata(console) for Mac OS X in the Getting Started with Stata for Macintosh manual for more information.

Contents


Introduction

The GUI version of Stata allows users to run batch files, but it is not suited for remote access or concurrent usage of Stata hosted from a single machine. The console version of Stata/SE or Stata/MP allows users with local or remote access to a Mac to use Stata interactively through a command line interface or to run batch files. With remote access, multiple users may use Stata at the same time.

The best way for us to describe the console version of Stata is to answer any potential questions you may have about it. Throughout this document, we will refer to the console version of Stata as Stata(console). We will refer to the GUI version of Stata as Stata(GUI). Both GUI and console versions of Stata 9 are available as universal binaries. This means that they will run at peak performance on both Intel and PowerPC-based Mac computers.

Stata 8 users may download the console version of Stata/SE 8 for the Mac here. Stata 8 users who wish to run Stata at peak performance on an Intel-based Mac must upgrade to Stata 9.

  1. How much does Stata(console) cost?

    Stata/SE(console) is free to registered users of Stata/SE for the Mac. Stata/MP(console) is free to registered users of Stata/MP for the Mac. Users of Intercooled Stata or Small Stata must upgrade to Stata/SE or Stata/MP to use the console version.

  2. Do I need a new license?

    Your Stata for Mac may use a single-user license that allows one login ID to use Stata at once. If more than one login ID will need to use Stata at a time, please contact our sales department to purchase an upgrade for a multiuser license.

  3. Is Stata(console) faster than Stata(GUI)?

    With respect to statistical operations, there is no difference in speed between the two versions.

    However, Stata(console) is faster at outputting text. Stata(GUI) has the overhead of maintaining a graphical interface while Stata(console) only outputs ASCII text. Interactively, you won't notice much difference between the two versions, but when running a batch file with a lot of output, you may notice a difference.

  4. Can I display graphs with Stata(console)?

    No. Stata(console) is a text-based application and has no graphical display capabilities. However, it can generate and save Stata graphs, which can then be viewed with Stata(GUI). Stata(console) can also convert Stata graphs to PostScript and save them as files.

  5. Do you plan to release an X-Windows version that can display graphs?

    No.

  6. Do you plan to release a console version of Intercooled Stata?

    No, but you can still use the existing batch mode features of Stata for the Mac.

  7. Is more documentation available for using Stata(console)?

    Because Stata(console) is essentially the Unix console version of Stata, the Getting Started with Stata for Unix (GSU) may seem useful. However, most of the documentation within the GSU is already covered in the Getting Started with Stata for Macintosh manual. All the relevant information that you need to set up Stata(console) is contained in this document.

  8. Will I have to update the console executable separately from the GUI executable?

    Yes, they are separate executables. Stata ado-files only need to be updated once.

  9. Is there a native version of Stata(console) available for Intel-based Mac computers?

    Yes. Both Stata(GUI) and Stata(console) are available as universal binaries. This means they will run at peak performance on both Intel- and PowerPC-based Mac computers. Please see Stata(console) for Intel-based Mac for additional notes on installing Stata(console) on an Intel-based Mac if you have already installed Stata(console) on a PowerPC-based Mac.


Requirements

You must already have Stata/SE or Stata/MP for the Mac installed and your license initialized before installing Stata(console). If you have a single-user license and wish to have more than one login ID use Stata at a time, please contact our sales department to purchase an upgrade to a multiuser license.

You should have some experience in working from a shell in Unix before attempting to install Stata(console). You must also have administrator access to your computer to complete the installation. With administrator access, there is always the potential for doing serious harm to your computer.

If you are not comfortable with Unix or are wary of doing any damage to your computer, do not attempt the installation. If you do not know when to use

	setenv PATH /Applications/Stata:$PATH

and when to use

	PATH=/Applications/Stata:$PATH

do not attempt the installation.


Step-by-step download and installation instructions

  1. Log in to your Mac with an account that has administrator privileges.
  2. Install Stata/SE or Stata/MP in /Applications/Stata and initialize your license if Stata is not already installed.
  3. Open the Terminal application from /Applications/Utitilities/.
  4. Change to the Stata directory
            mymac:~> cd /Applications/Stata/
    
  5. Download stata-se.bin.Z for Stata/SE, or download stata-mp.bin.Z for Stata/MP.
  6. In the instructions that follow, use stata-mp in place of stata-se if you are installing the console version of Stata/MP.
  7. Extract the executable if necessary and move it to the Stata directory. If you do not have write permission to the Stata directory, you must precede each command with sudo to execute the command as administrator.

    For example, if your browser automatically saved stata-se.bin.Z to the Desktop and uncompressed the file as stata-se.bin, enter
            mymac:/Applications/Stata> mv ~/Desktop/stata-se.bin stata-se
    
    However, if your browser automatically saved stata-se.bin.Z to the Desktop but did not uncompress it, enter
            mymac:/Applications/Stata> mv ~/Desktop/stata-se.bin.Z .
            mymac:/Applications/Stata> uncompress stata-se.bin.Z
            mymac:/Applications/Stata> mv stata-se.bin stata-se
    
  8. Set the file permissions for stata-se so it is executable by everyone.
            mymac:/Applications/Stata> chmod 755 stata-se
    
  9. You must now execute stata-se as administrator using sudo to create the license-tracking file. This file tracks the number of simultaneous users at your site. You must complete this step even if you have a single-user license, as the console version will not run unless this file is created. The . is Stata’s prompt. Commands shown below preceded by the . prompt are to be entered while Stata is running.
            mymac:/Applications/Stata> sudo mkdir .license
            mymac:/Applications/Stata> sudo ./stata-se
            . simulinit
            . exit
    
    simulinit creates the file /Applications/Stata/.license/stata.sim, which must be readable and writable by all Stata users. This only needs to be done once.

You have completed the installation process. We now wish to verify that everything is installed properly as a regular user. In order to use Stata as a regular user, your path must include /Applications/Stata/. For a quick test, we are going to be quite crude.

        mymac:/Applications/Stata> cd
        mymac:~> setenv PATH /Applications/Stata:$PATH
        mymac:~> rehash
        mymac:~> stata-se

Stata should come up.

Once you have verified that everything is working, make sure that your users modify their shell startup script to include /Applications/Stata in their path. If you use csh(1) or tcsh(1), there is a line in your .cshrc or .tcshrc file that looks similar to

        set path = (/bin /usr/bin .)

Edit the file, and add /Applications/Stata to the list:

        set path = (/Applications/Stata /bin /usr/bin .)

Updating Stata(console) in the future

Stata(console) is updated separately from Stata(GUI). You must have write permissions to the Stata directory and stata-se or stata-mp. To update, start Stata(console) and type

        . update all
        
        . update swap

If you have already updated your ado-files in Stata(GUI), it is not necessary to do so in Stata(console) and vice versa, but if you do, it won't matter.


Advanced topics

Switching from Stata(console) for PowerPC to Intel

As of 20 January 2006, both Stata(GUI) and Stata(console) are available as universal binaries. The installation instructions are exactly the same regardless of whether you're installing Stata on an Intel-based Mac or a PowerPC-based Mac. However, if you've already installed the PowerPC version of Stata(console) on an Intel-based Mac, there are a couple of additional steps you must take.

After you have downloaded and installed the latest version of Stata(console), you must start Stata(console) as administrator using sudo and then reinitialize Stata’s license-tracking file.

        mymac:/Applications/Stata> sudo ./stata-se
        . simulinit, replace

Installation locations

Although we suggest that you install Stata in /Applications/Stata, you may install Stata anywhere you wish. However, Stata(console) requires that it be installed in either /Applications/Stata, /usr/local/stata9, or /usr/local/stata. If you wish to install Stata in a different location, you must create a symbolic link (not an alias). For example, if Stata is installed in the directory /opt/Stata9 and you wish to create the symbolic link /usr/local/stata9, enter

        mymac:~> sudo ln -s /opt/Stata9 /usr/local/stata9

Then have your users modify their shell startup script to include /usr/local/stata9 in their path.

        set path = (/bin /usr/bin /usr/local/stata9 .)

/opt/Stata9 is not required to be in the path, but if it is, /usr/local/stata9 must be anywhere before it in the path.

        set path = (/bin /usr/bin /opt/Stata9 .)

becomes

        set path = (/bin /usr/bin /usr/local/stata9 /opt/Stata9 .)

Relocating Stata’s license-tracking file

If you are at a large networked site and the network drive supplying /usr/local/stata9 is mounted read-only, later when your users try to invoke Stata, they will be told that the file /usr/local/stata9/.license/stata.sim is not writable, and Stata will not start.

As administrator, you may relocate the Stata license-tracking file:

  1. Create the file /usr/local/stata9/stata.lfn containing one line with the full path of the file you wish to use as the license-tracking file; stata.lfn must be readable by all users, and the file referred to within it must be writable by everyone.
  2. Ensure the directory containing the file exists.
  3. Invoke Stata as administrator (using sudo), and type simulinit. This will create the file and give it the correct permissions.

How Stata counts license positions

Each user counts as one access. If russell is using Stata and spgbob is using Stata, that counts as two accesses.

Actually, each hostname/userid combination counts as one access. That is, if user russell is running four Statas at once from computer mymac, Stata counts this as only one access. However if user russell is running Stata from computer mymac and another Stata from computer pollo, Stata counts this as two accesses.

When a user invokes Stata, Stata checks how many simultaneous users there currently are. If you have an n-user license and there are currently n simultaneous users, Stata will not start.

You can run short on license positions for two reasons: (1) you simply do not have enough for your user community, and (2) because some users have started Stata and forgotten to exit. (If the user did not exit due to a computer crash or some other unfortunate event, the license-tracking system will catch it after a few hours, so that is not a long-run problem.)

Stata will always let the administrator run Stata, even if all the license positions are in use, so you can see who is using it. If you have a 10-user license, Stata will let the administrator start Stata, even if there are already 10 other users. If you receive a complaint that a user is not able to start Stata because of too many users, start Stata and see who is using it. You can then contact these users and tell them to exit Stata if they can.

        mymac:~> sudo /Applications/Stata/stata-se
        . who
        User              Host                  Instances
        -------------------------------------------------
        russell           mymac                         2
        spgbob            mojo                          1
        dsanchez          pollo                         3
        
        3 Users
        
        .

The number of instances is shown only for your information. Note that the above list corresponds to using 3 license positions. Stata reports there are three users. Getting russell to exit one session will do no good in terms of freeing up a position.

Increasing the size of your license is easy. You can do it immediately by contacting StataCorp.

If you request a larger license, we will supply temporary codes before receiving any paperwork or formal authorizations. We can supply instructions and codes for upgrading your license over the telephone, via email, or fax. Of course, you will ultimately have to pay for the larger license. We will wait for the paperwork to follow your request. If, after thirty days, no paperwork appears, Stata itself will automatically revoke the increased license size. When the paperwork does appear, we will mail or fax your new License and Authorization Key so that you can make the change permanent.

Set the message of the day

Every time Stata is invoked, the contents of /Applications/Stata/stata.msg are displayed. This provides a convenient way for you to communicate with Stata users at large sites. As administrator, you may edit the file or erase it if you wish.

Advanced starting of Stata(console)

The syntax of the command to start Stata(console) is

stata-se [-option [ -option [...]]] [stata_command]

or

stata-mp [-option [ -option [...]]] [stata_command]

where the options are

-h display usage diagram
-q suppress logo and initialization messages
-m# allocate # memory; default is -m10
-w show users currently occupying Stata license position
-b run in background (batch) mode and write the log in ASCII text
-s run in background (batch) mode and write the log in SMCL

Typing stata-se -h or stata-mp -h does not start Stata but shows the syntax diagram for invoking Stata.

The -q option does invoke Stata but suppresses all the initialization messages including the Stata logo.

The -m option specifies the amount of memory to be allocated to Stata’s data areas; this is discussed in Specifying the amount of memory allocated. Most users find typing set memory after Stata has come up more convenient; see [U] 7 Setting the size of memory.

The -w option displays the users occupying Stata license positions. Specifying it is equivalent to starting Stata and typing who.

The -b and -s options specify batch mode; see Executing Stata in background (batch) mode.

Specifying the amount of memory allocated

If you start Stata without the -m option, Stata will come up with 10 megabytes allocated to its data area.

If you wish to start Stata with a different initial memory allocation, use the -m followed by the integer number of megabytes to allocate for data.

If you want 2 megabytes, type the -m2.

If you want 32 megabytes, type the -m32.

If you want 100 megabytes, type the -m100.

You can specify any amount your operating system can provide. If you make the amount too large, when Stata attempts to come up you will see a message telling you that the operating system refused to provide that much memory. Stata will then attempt to come up using its default setting of 10 megabytes. If you see this message, you should decrease the amount of memory that you are asking the operating system to provide to Stata.

You can also change the amount of memory once Stata is running by using the set memory command, and you can make that setting permanent rather than using the -m option on the command line; see [U] 7 Setting the size of memory. The setting is not global.

Executing Stata in background (batch) mode

Both Stata/SE and Stata/MP can be used in batch mode. We'll demonstrate using Stata/SE. If you are using Stata/MP, substitute stata-mp where stata-se appears below.

If you want to use Stata in batch mode, typing

	mymac:~> stata-se -s do bigjob

tells Stata to execute the commands in bigjob.do, suppress all screen output, and route the output to bigjob.smcl in the same directory.

You can also run the above examples in the background by typing

        mymac:~> stata-se -s do bigjob &

or

        mymac:~> stata-se -b do bigjob &

Alternatively, you may use redirection:

        mymac:~> stata-se < bigjob > bigjob.log &

Note: Stata runs profile.do before doing bigjob.do, just as it would interactively.

Warning: If your do-file contains either the #delimit command or comment delimiters (/* and */ or ///), redirection will not work. Also, redirection cannot produce SMCL output. We recommend that you run stata-se with either the -s or -b options, as in the examples above, rather than using redirection.

Summary of environment variables

Environment variable Description
HOME User’s home directory. Default is the directory specified in /etc/passwd.
PATH Unix executable search path.
SHELL Shell to execute when users try to shell out of Stata. Default is /bin/sh.
S_ADO Sets Stata’s ado-path.
STATATERM Only used if you want to use a different termcap or terminfo entry than what is in your TERM environment variable.
STATATMP Sets Stata’s temporary directory. Default is /tmp.