com.stata.sfi

Class Frame

java.lang.Object

com.stata.sfi.Frame

public final class Frame
extends Object

This class provides access to Stata frames. Functionality is provided by wrapping a Stata frame in a Java object of type Frame, which provides many methods for accessing the underlying Stata frame. If the underlying frame is renamed from Stata, Mata, etc., then access to the frame from its object will be lost. For more information about Stata frames, see help frames in Stata.

All variable and observation numbering begins at 1 unless otherwise stated.

Method Summary

Modifier and Type	Method and Description
int	addVarByte(String varname) Add a variable of type byte to the frame.
int	addVarDouble(String varname) Add a variable of type double to the frame.
int	addVarFloat(String varname) Add a variable of type float to the frame.
int	addVarInt(String varname) Add a variable of type int to the frame.
int	addVarLong(String varname) Add a variable of type long to the frame.
int	addVarStr(String varname, int length) Add a variable of type str to the frame.
int	addVarStrL(String varname) Add a variable of type strL to the frame.
int	allocateStrL(StrLConnector dsc, long size) Allocate a strL so that a buffer can be stored using writeBytes; the contents of the strL will not be initialized.
int	allocateStrL(StrLConnector dsc, long size, boolean binary) Allocate a strL so that a buffer can be stored using writeBytes; the contents of the strL will not be initialized.
int	changeToCWF() Set the Frame as the current working frame in Stata.
Frame	clone(String newName) Create a new Frame instance by cloning the current Frame and its contents.
static Frame	connect(String name) Connect to an existing frame in Stata and return a new Frame instance that can be used to access it.
static Frame	create(String name) Create a new frame in Stata and return a new Frame instance that can be used to access it.
int	drop() Drop the frame in Stata.
int	dropVar(int var) Drop the variable at the specified variable index.
String	getFormattedValue(int var, long obs, boolean bValueLabel) Read a value from the frame, applying its display format.
static String	getFrameAt(int index) Utility method for getting the name of a Stata frame at a given index.
static int	getFrameCount() Utility method for getting the number of frames in Stata.
double	getNum(int var, long obs) Read a numeric value from the frame.
long	getObsTotal() Get the number of observations in the frame.
String	getStr(int index, long obs) Read a string value from the frame.
String	getStrf(int index, long obs) Read a string value from the frame.
int	getStrVarWidth(int var) Get the width of a variable of type str.
int	getType(int var) Get the numeric data type for the specified variable.
int	getVarCount() Get the number of variables in the frame.
String	getVarFormat(int var) Get the format for a variable in the frame.
int	getVarIndex(String varname) Look up the variable index for the specified variable name in the frame.
String	getVarLabel(int var) Get the label for a variable in the frame.
String	getVarName(int var) Get the variable name at a given variable index.
boolean	isVarTypeStr(int var) Test if a variable is of type str.
boolean	isVarTypeString(int var) Test if a variable is string or numeric.
boolean	isVarTypeStrL(int var) Test if a variable is of type strL.
int	readBytes(StrLConnector dsc, byte[] b) Read a sequence of bytes from a strL in the current Stata dataset.
int	readBytes(StrLConnector dsc, byte[] b, int off, int len) Read a sequence of bytes from a strL in the current Stata dataset.
int	rename(String newName) Rename the frame in Stata.
int	renameVar(int var, String newname) Rename a variable.
int	setObsTotal(long obs) Set the number of observations in the frame.
int	setVarFormat(int var, String format) Set the format for a variable in the frame.
int	setVarLabel(int var, String label) Set the label for a variable in the frame.
int	storeBytes(int var, long obs, byte[] bytes, boolean binary) Store a byte buffer to a strL in the frame.
int	storeNum(int var, long obs, double value) Store a numeric value in the frame.
int	storeNumFast(int var, long obs, double value) Store a numeric value in the frame.
int	storeStr(int var, long obs, String value) Store a string value in the frame.
int	storeStrf(int var, long obs, String value) Store a string value in the frame.
int	storeStrfFast(int var, long obs, String value) Store a string value in the frame.
void	updateModified() Inform Stata that the frame's data has been modified.
int	writeBytes(StrLConnector dsc, byte[] b) Write a byte buffer to a strL in the current Stata dataset; the strL must be allocated using allocateStrL before calling this method.
int	writeBytes(StrLConnector dsc, byte[] b, int off, int len) Write len bytes from the specified byte buffer starting at offset off to a strL in the current Stata dataset; the strL must be allocated using allocateStrL before calling this method.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

addVarByte

@Synchronized
public int addVarByte(String varname)

Add a variable of type byte to the frame.

Parameters:

varname - Name of the variable to be created.

Returns:

Return code from Stata; 0 if successful.

addVarDouble

@Synchronized
public int addVarDouble(String varname)

Add a variable of type double to the frame.

Parameters:

varname - Name of the variable to be created.

Returns:

Return code from Stata; 0 if successful.

addVarFloat

@Synchronized
public int addVarFloat(String varname)

Add a variable of type float to the frame.

Parameters:

varname - Name of the variable to be created.

Returns:

Return code from Stata; 0 if successful.

addVarInt

@Synchronized
public int addVarInt(String varname)

Add a variable of type int to the frame.

Parameters:

varname - Name of the variable to be created.

Returns:

Return code from Stata; 0 if successful.

addVarLong

@Synchronized
public int addVarLong(String varname)

Add a variable of type long to the frame.

Parameters:

varname - Name of the variable to be created.

Returns:

Return code from Stata; 0 if successful.

addVarStr

@Synchronized
public int addVarStr(String varname,
                                   int length)

Add a variable of type str to the frame.

Parameters:

varname - Name of the variable to be created.

length - Initial size of the variable. If the length is greater than Data.getMaxStrLength(), then a variable of type strL will be created.

Returns:

Return code from Stata; 0 if successful.

addVarStrL

@Synchronized
public int addVarStrL(String varname)

Add a variable of type strL to the frame.

Parameters:

varname - Name of the variable to be created.

Returns:

Return code from Stata; 0 if successful.

allocateStrL

@Synchronized
public int allocateStrL(StrLConnector dsc,
                                      long size)
                               throws IOException

Allocate a strL so that a buffer can be stored using writeBytes; the contents of the strL will not be initialized. By default, the data will be marked as binary.

Parameters:

dsc - The StrLConnector representing a strL.

size - The size in bytes.

Returns:

Return code from Stata; 0 if successful.

Throws:

IOException - Throws an IOException if an error occurs.

allocateStrL

@Synchronized
public int allocateStrL(StrLConnector dsc,
                                      long size,
                                      boolean binary)
                               throws IOException

Allocate a strL so that a buffer can be stored using writeBytes; the contents of the strL will not be initialized.

Parameters:

dsc - The StrLConnector representing a strL.

size - The size in bytes.

binary - Mark the data as binary. Note that if the data are not marked as binary, Stata expects that the data be UTF-8 encoded. An alternate approach is to call storeStr, where the encoding is automatically handled.

Returns:

Return code from Stata; 0 if successful.

Throws:

IOException - Throws an IOException if an error occurs.

changeToCWF

@Synchronized
public int changeToCWF()

Set the Frame as the current working frame in Stata. The current working frame in Stata can be accessed using Data if desired.

Returns:

Return code from Stata; 0 if successful.

clone

@Synchronized
public Frame clone(String newName)
                          throws FrameException

Create a new Frame instance by cloning the current Frame and its contents. This results in a new frame in Stata.

Parameters:

newName - The name of the new frame to be created.

Returns:

A Frame that corresponds to the newly cloned frame in Stata.

Throws:

FrameException - If the cloning of the frame fails.

connect

@Synchronized
public static Frame connect(String name)
                                   throws FrameException

Connect to an existing frame in Stata and return a new Frame instance that can be used to access it.

Parameters:

name - Name of an existing Stata frame.

Returns:

A Frame that corresponds to the existing frame in Stata.

Throws:

FrameException - If the frame does not already exist in Stata or if connecting to the frame fails.

create

@Synchronized
public static Frame create(String name)
                                  throws FrameException

Create a new frame in Stata and return a new Frame instance that can be used to access it.

Parameters:

name - Name of the Stata frame to create.

Returns:

A new Frame that corresponds to the new frame in Stata.

Throws:

FrameException - If the creation of the new frame in Stata fails.

drop

@Synchronized
public int drop()

Drop the frame in Stata. You may not drop a frame if it is the current working frame in Stata.

Returns:

Return code from Stata; 0 if successful.

dropVar

@Synchronized
public int dropVar(int var)

Drop the variable at the specified variable index.

Parameters:

var - Variable to drop.

Returns:

Return code from Stata; 0 if successful.

getFormattedValue

@Synchronized
public String getFormattedValue(int var,
                                              long obs,
                                              boolean bValueLabel)

Read a value from the frame, applying its display format.

Parameters:

var - Variable to access.

obs - Observation to access.

bValueLabel - Use the value label when available.

Returns:

The formatted value as a String.

getFrameAt

@Synchronized
public static String getFrameAt(int index)

Utility method for getting the name of a Stata frame at a given index.

Parameters:

index - The index for a frame.

Returns:

The name of the frame for the specified index.

getNum

@ThreadSafe
public double getNum(int var,
                                 long obs)

Read a numeric value from the frame.

Parameters:

var - Variable to access.

obs - Observation to access.

Returns:

The value.

getObsTotal

@ThreadSafe
public long getObsTotal()

Get the number of observations in the frame.

Returns:

The number of observations.

getStr

@Synchronized
public String getStr(int index,
                                   long obs)

Read a string value from the frame. This method can be used to read str or strL data types.

Parameters:

index - Variable to access.

obs - Observation to access.

Returns:

The String. Returns null if an error occurs.

getStrf

@ThreadSafe
public String getStrf(int index,
                                  long obs)

Read a string value from the frame. This method can be used to read str data types.

Parameters:

index - Variable to access.

obs - Observation to access.

Returns:

The String. Returns null if an error occurs.

getStrVarWidth

@ThreadSafe
public int getStrVarWidth(int var)

Get the width of a variable of type str.

Parameters:

var - The index of the variable to test.

Returns:

The width if the variable is of type str.

getType

@ThreadSafe
public int getType(int var)

Get the numeric data type for the specified variable.

Parameters:

var - Variable to access.

Returns:

The value representing the data type; may be TYPE_BYTE, TYPE_INT, TYPE_LONG, TYPE_FLOAT, TYPE_DOUBLE, TYPE_STR, or TYPE_STRL.

getVarCount

@ThreadSafe
public int getVarCount()

Get the number of variables in the frame.

Returns:

The number of variables.

getVarFormat

@ThreadSafe
public String getVarFormat(int var)

Get the format for a variable in the frame.

Parameters:

var - Index of the variable to look up.

Returns:

The variable's format.

getVarIndex

@Synchronized
public int getVarIndex(String varname)

Look up the variable index for the specified variable name in the frame.

Parameters:

varname - Name of the variable.

Returns:

The variable index.

getVarLabel

@ThreadSafe
public String getVarLabel(int var)

Get the label for a variable in the frame.

Parameters:

var - Index of the variable to look up.

Returns:

The variable's label.

getVarName

@ThreadSafe
public String getVarName(int var)

Get the variable name at a given variable index.

Parameters:

var - Index of the variable to look up.

Returns:

The name of the variable.

isVarTypeStr

@ThreadSafe
public boolean isVarTypeStr(int var)

Test if a variable is of type str.

Parameters:

var - The index of the variable to test.

Returns:

True if the variable is of type str.

isVarTypeString

@ThreadSafe
public boolean isVarTypeString(int var)

Test if a variable is string or numeric.

Parameters:

var - The index of the variable to test.

Returns:

True if the variable is a string variable of either type str or type strL.

isVarTypeStrL

@ThreadSafe
public boolean isVarTypeStrL(int var)

Test if a variable is of type strL.

Parameters:

var - The index of the variable to test.

Returns:

True if the variable is of type strL.

readBytes

@Synchronized
public int readBytes(StrLConnector dsc,
                                   byte[] b)
                            throws IOException

Read a sequence of bytes from a strL in the current Stata dataset.

Parameters:

dsc - The StrLConnector representing a strL.

b - The buffer into which the data are read.

Returns:

The total number of bytes read into the buffer, or -1 if there are no more data because the end has been reached. May return a negative Stata return code if an error occurs.

Throws:

IOException - Throws an IOException if an error occurs.

readBytes

@Synchronized
public int readBytes(StrLConnector dsc,
                                   byte[] b,
                                   int off,
                                   int len)
                            throws IOException

Read a sequence of bytes from a strL in the current Stata dataset.

Parameters:

dsc - The StrLConnector representing a strL.

b - The buffer into which the data are read.

off - The start offset in the destination array b.

len - The maximum number of bytes read.

Returns:

The total number of bytes read into the buffer, or -1 if there are no more data because the end has been reached. May return a negative Stata return code if an error occurs.

Throws:

IOException - Throws an IOException if an error occurs.

rename

@Synchronized
public int rename(String newName)

Rename the frame in Stata.

Parameters:

newName - Name of the new frame.

Returns:

Return code from Stata; 0 if successful.

renameVar

@Synchronized
public int renameVar(int var,
                                   String newname)

Rename a variable.

Parameters:

var - Index of the variable to rename.

newname - New variable name.

Returns:

Return code from Stata; 0 if successful.

setObsTotal

@Synchronized
public int setObsTotal(long obs)

Set the number of observations in the frame.

Parameters:

obs - The number of observations to set.

Returns:

Return code from Stata; 0 if successful.

setVarFormat

@Synchronized
public int setVarFormat(int var,
                                      String format)

Set the format for a variable in the frame.

Parameters:

var - Index of the variable to format.

format - New format.

Returns:

Return code from Stata; 0 if successful.

setVarLabel

@Synchronized
public int setVarLabel(int var,
                                     String label)

Set the label for a variable in the frame.

Parameters:

var - Index of the variable to label.

label - New label.

Returns:

Return code from Stata; 0 if successful.

storeBytes

@Synchronized
public int storeBytes(int var,
                                    long obs,
                                    byte[] bytes,
                                    boolean binary)

Store a byte buffer to a strL in the frame. You do not need to call allocateStrL before using this method.

Parameters:

var - Variable to access.

obs - Observation to access.

bytes - Bytes to store.

binary - Mark the data as binary.

Returns:

Return code from Stata; 0 if successful.

storeNum

@Synchronized
public int storeNum(int var,
                                  long obs,
                                  double value)

Store a numeric value in the frame. Variable-type promotion happens automatically if the value you are storing is larger than what the variable can currently store.

Parameters:

var - Variable to access.

obs - Observation to access.

value - Value to store.

Returns:

Return code from Stata; 0 if successful.

storeNumFast

@ThreadSafe
public int storeNumFast(int var,
                                    long obs,
                                    double value)

Store a numeric value in the frame. This method does not perform variable-type promotion and does not update the modified state of the data. To mark the frame as changed, you should make a single call to Frame.updateModified().

Parameters:

var - Variable to access.

obs - Observation to access.

value - Value to store.

Returns:

Return code from Stata; 0 if successful.

storeStr

@Synchronized
public int storeStr(int var,
                                  long obs,
                                  String value)

Store a string value in the frame. This method can be used to store str or strL data types. Variable-type promotion happens automatically if the string you are storing is longer than what the variable can currently store.

Parameters:

var - Variable to access.

obs - Observation to access.

value - Value to store.

Returns:

Return code from Stata; 0 if successful.

storeStrf

@Synchronized
public int storeStrf(int var,
                                   long obs,
                                   String value)

Store a string value in the frame. This method can be used to store str data types. Variable-type promotion happens automatically if the string you are storing is longer than what the variable can currently store. This method will not promote the type to a strL. If the string is longer than the maximum length of a str, then the string will be truncated.

Parameters:

var - Variable to access.

obs - Observation to access.

value - Value to store.

Returns:

Return code from Stata; 0 if successful.

storeStrfFast

@ThreadSafe
public int storeStrfFast(int var,
                                     long obs,
                                     String value)

Store a string value in the frame. This method can be used to store str data types. This method does not perform variable-type promotion and does not update the modified state of the data. To mark the frame as changed, you should make a single call to Frame.updateModified(). If the string is longer than the current storage length, then the string will be truncated.

Parameters:

var - Variable to access.

obs - Observation to access.

value - Value to store.

Returns:

Return code from Stata; 0 if successful.

updateModified

@Synchronized
public void updateModified()

Inform Stata that the frame's data has been modified. Most methods automatically invoke this function as needed. Avoid calling this method from within a loop.

writeBytes

@Synchronized
public int writeBytes(StrLConnector dsc,
                                    byte[] b)

Write a byte buffer to a strL in the current Stata dataset; the strL must be allocated using allocateStrL before calling this method. The buffer size may be smaller than the allocation size for the strL so that calling this method multiple times will write the data in chunks. The current position of each write will be automatically maintained. Writing beyond the allocation size is not permitted.

Parameters:

dsc - The StrLConnector representing a strL.

b - The buffer holding the data to store.

Returns:

Return code from Stata; 0 if successful.

writeBytes

@Synchronized
public int writeBytes(StrLConnector dsc,
                                    byte[] b,
                                    int off,
                                    int len)

Write len bytes from the specified byte buffer starting at offset off to a strL in the current Stata dataset; the strL must be allocated using allocateStrL before calling this method. The buffer size may be smaller than the allocation size for the strL so that calling this method multiple times will write the data in chunks. The current position of each write will be automatically maintained. Writing beyond the allocation size is not permitted.

Parameters:

dsc - The StrLConnector representing a strL.

b - The buffer holding the data to store.

off - The offset into the buffer.

len - The number of bytes to write.

Returns:

Return code from Stata; 0 if successful.

getFrameCount

@Synchronized
public static int getFrameCount()

Utility method for getting the number of frames in Stata.

Returns:

Return the number of frames.