Package com.stata.sfi

Class 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

      All Methods Static Methods Instance Methods Concrete Methods 
      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.
      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.
      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.

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

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

      • getFrameCount

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