|17 October 2006
|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.
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.
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
do not attempt the installation.
mymac:~> cd /Applications/Stata/
mymac:/Applications/Stata> mv ~/Desktop/stata-se.bin stata-seHowever, 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
mymac:/Applications/Stata> chmod 755 stata-se
mymac:/Applications/Stata> sudo mkdir .license mymac:/Applications/Stata> sudo ./stata-se . simulinit . exitsimulinit 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 .)
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.
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
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 .)
set path = (/bin /usr/bin /usr/local/stata9 /opt/Stata9 .)
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:
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.
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.
The syntax of the command to start Stata(console) is
stata-se [-option [ -option [...]]] [stata_command]
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.
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.
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 &
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.
|User’s home directory. Default is the directory specified in /etc/passwd.
|Unix executable search path.
|Shell to execute when users try to shell out of Stata. Default is /bin/sh.
|Sets Stata’s ado-path.
|Only used if you want to use a different termcap or terminfo entry than what is in your TERM environment variable.
|Sets Stata’s temporary directory. Default is /tmp.