Package 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
    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.
    static String
    getCWF()
    Utility method for getting the name of the current working frame in Stata.
    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.
    static String[]
    getFrames()
    Utility method for getting the names of all frames in Stata.
    String
    getName()
    Get the name of the frame.
    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
    isAlias(int var)
    Determine if a variable is an alias for a variable in another frame.
    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.
    int
    readBytes(StrLConnector dsc, byte[] b, int off, int len)
    Read a sequence of bytes from a strL.
    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 have been modified.
    int
    writeBytes(StrLConnector dsc, byte[] b)
    Write a byte buffer to a strL; 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; the strL must be allocated using allocateStrL before calling this method.

    Methods inherited from class java.lang.Object

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

  • Method Details

    • 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.

    • getCWF

      @Synchronized public static String getCWF()
      Utility method for getting the name of the current working frame in Stata.
      Returns:
      The name of the current working frame.

    • 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.

    • getFrameCount

      @Synchronized public static int getFrameCount()
      Utility method for getting the number of frames in Stata.
      Returns:
      The number of frames.

    • getFrames

      @Synchronized public static String[] getFrames()
      Utility method for getting the names of all frames in Stata.
      Returns:
      The names of all frames.

    • 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.

    • 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.

    • getName

      @ThreadSafe public String getName()
      Get the name of the frame.
      Returns:
      The name of the frame.

    • 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, TYPE_STRL, or TYPE_UNKNOWN.

    • 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.

    • isAlias

      @ThreadSafe public boolean isAlias(int var)
      Determine if a variable is an alias for a variable in another frame.
      Parameters:
      var - Variable to access.
      Returns:
      True for alias variables.

    • 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.
      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.
      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 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 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 have 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; 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; 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.