com.ibm.as400.access
Class CharacterDataArea

java.lang.Object
  extended bycom.ibm.as400.access.DataArea
      extended bycom.ibm.as400.access.CharacterDataArea
All Implemented Interfaces:
Serializable

public class CharacterDataArea
extends DataArea
implements Serializable

The CharacterDataArea class represents a character data area on the server.

The following example demonstrates the use of CharacterDataArea:

// Prepare to work with the server named "My400".
AS400 system = new AS400("My400");

// Create a CharacterDataArea object.
QSYSObjectPathName path = new QSYSObjectPathName("MYLIB", "MYDATA", "DTAARA");
CharacterDataArea dataArea = new CharacterDataArea(system, path.getPath());

// Create the character data area on the server using default values.
dataArea.create();

// Clear the data area.
dataArea.clear();

// Write to the data area.
dataArea.write("Hello world");

// Read from the data area.
String data = dataArea.read();

// Delete the data area from the server.
dataArea.delete();

See Also:
Serialized Form

Constructor Summary
CharacterDataArea()
          Constructs a CharacterDataArea object.
CharacterDataArea(AS400 system, String path)
          Constructs a CharacterDataArea object.
 
Method Summary
 void clear()
          Resets the data area to contain all blanks.
 void create()
          Creates a character data area on the server.
 void create(int length, String initialValue, String textDescription, String authority)
          Creates a character data area with the specified attributes.
 void delete()
          Removes the data area from the system.
 String getPath()
          Returns the integrated file system path name of the object represented by the data area.
 String read()
          Reads the data from the data area.
 String read(int type)
          Reads the data from the data area.
 String read(int dataAreaOffset, int dataLength)
          Reads the data from the data area.
 String read(int dataAreaOffset, int dataLength, int type)
          Reads the data from the data area.
 void setPath(String path)
          Sets the fully qualified data area name.
 void write(String data)
          Writes the data to the data area.
 void write(String data, int dataAreaOffset)
          Writes the data to the data area.
 void write(String data, int dataAreaOffset, int type)
          Writes the data to the data area.
 
Methods inherited from class com.ibm.as400.access.DataArea
addDataAreaListener, addPropertyChangeListener, addVetoableChangeListener, getLength, getName, getSystem, refreshAttributes, removeDataAreaListener, removePropertyChangeListener, removeVetoableChangeListener, setSystem
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

CharacterDataArea

public CharacterDataArea()
Constructs a CharacterDataArea object. It creates a default CharacterDataArea object. The system and path properties must be set before attempting a connection.


CharacterDataArea

public CharacterDataArea(AS400 system,
                         String path)
Constructs a CharacterDataArea object. It creates a CharacterDataArea instance that represents the data area path on system.

Parameters:
system - The server that contains the data area.
path - The fully qualified integrated file system path name. The integrated file system file extension for a data area is DTAARA. An example of a fully qualified integrated file system path to a data area "MYDATA" in library "MYLIB" is: /QSYS.LIB/MYLIB.LIB/MYDATA.DTAARA
Method Detail

clear

public void clear()
           throws AS400SecurityException,
                  ErrorCompletingRequestException,
                  InterruptedException,
                  IOException,
                  ObjectDoesNotExistException
Resets the data area to contain all blanks.

Throws:
AS400SecurityException - If a security or authority error occurs.
ErrorCompletingRequestException - If an error occurs before the request is completed.
InterruptedException - If this thread is interrupted.
IOException - If an error occurs while communicating with the server.
ObjectDoesNotExistException - If the server object does not exist.

create

public void create()
            throws AS400SecurityException,
                   ErrorCompletingRequestException,
                   InterruptedException,
                   IOException,
                   ObjectAlreadyExistsException,
                   ObjectDoesNotExistException
Creates a character data area on the server. This method uses the following default property values.

Throws:
AS400SecurityException - If a security or authority error occurs.
ErrorCompletingRequestException - If an error occurs before the request is completed.
InterruptedException - If this thread is interrupted.
IOException - If an error occurs while communicating with the server.
ObjectAlreadyExistsException - If the server object already exists.
ObjectDoesNotExistException - If the server object does not exist.

create

public void create(int length,
                   String initialValue,
                   String textDescription,
                   String authority)
            throws AS400SecurityException,
                   ErrorCompletingRequestException,
                   InterruptedException,
                   IOException,
                   ObjectAlreadyExistsException,
                   ObjectDoesNotExistException
Creates a character data area with the specified attributes.

Parameters:
length - The maximum number of characters in the data area. Valid values are 1 through 2000.
initialValue - The initial value for the data area.
textDescription - The text description for the data area. The maximum length is 50 characters.
authority - The public authority level for the data area. Valid values are *ALL, *CHANGE, *EXCLUDE, *LIBCRTAUT, *USE, or the name of an authorization list. The maximum length is 10 characters.
Throws:
AS400SecurityException - If a security or authority error occurs.
ErrorCompletingRequestException - If an error occurs before the request is completed.
InterruptedException - If this thread is interrupted.
IOException - If an error occurs while communicating with the server.
ObjectAlreadyExistsException - If the server object already exists.
ObjectDoesNotExistException - If the server object does not exist.

delete

public void delete()
            throws AS400SecurityException,
                   ErrorCompletingRequestException,
                   InterruptedException,
                   IOException,
                   ObjectDoesNotExistException
Removes the data area from the system.

Throws:
AS400SecurityException - If a security or authority error occurs.
ErrorCompletingRequestException - If an error occurs before the request is completed.
InterruptedException - If this thread is interrupted.
IOException - If an error occurs while communicating with the server.
ObjectDoesNotExistException - If the object does not exist.

getPath

public String getPath()
Returns the integrated file system path name of the object represented by the data area.

Returns:
The integrated file system path name of the object represented by the data area.

read

public String read()
            throws AS400SecurityException,
                   ErrorCompletingRequestException,
                   IllegalObjectTypeException,
                   InterruptedException,
                   IOException,
                   ObjectDoesNotExistException
Reads the data from the data area. It retrieves the entire contents of the data area. Note that if the data does not completely fill the data area, this method will return data containing trailing blanks up to the length of the data area.

Returns:
The data read from the data area.
Throws:
AS400SecurityException - If a security or authority error occurs.
ErrorCompletingRequestException - If an error occurs before the request is completed.
IllegalObjectTypeException - If the server object is not the required type.
InterruptedException - If this thread is interrupted.
IOException - If an error occurs while communicating with the server.
ObjectDoesNotExistException - If the server object does not exist.

read

public String read(int type)
            throws AS400SecurityException,
                   ErrorCompletingRequestException,
                   IllegalObjectTypeException,
                   InterruptedException,
                   IOException,
                   ObjectDoesNotExistException
Reads the data from the data area. It retrieves the entire contents of the data area. Note that if the data does not completely fill the data area, this method will return data containing trailing blanks up to the length of the data area.

Parameters:
type - The Data Area bidi string type, as defined by the CDRA (Character Data Representataion Architecture). See BidiStringType for more information and valid values.
Returns:
The data read from the data area.
Throws:
AS400SecurityException - If a security or authority error occurs.
ErrorCompletingRequestException - If an error occurs before the request is completed.
IllegalObjectTypeException - If the server object is not the required type.
InterruptedException - If this thread is interrupted.
IOException - If an error occurs while communicating with the server.
ObjectDoesNotExistException - If the server object does not exist.

read

public String read(int dataAreaOffset,
                   int dataLength)
            throws AS400SecurityException,
                   ErrorCompletingRequestException,
                   IllegalObjectTypeException,
                   InterruptedException,
                   IOException,
                   ObjectDoesNotExistException
Reads the data from the data area. It retrieves dataLength characters beginning at dataAreaOffset in the data area. The first character in the data area is at offset 0.

Parameters:
dataAreaOffset - The offset in the data area at which to start reading.
dataLength - The number of characters to read. Valid values are from 1 through (data area size - dataAreaOffset).
Returns:
The data read from the data area.
Throws:
AS400SecurityException - If a security or authority error occurs.
ErrorCompletingRequestException - If an error occurs before the request is completed.
IllegalObjectTypeException - If the server object is not the required type.
InterruptedException - If this thread is interrupted.
IOException - If an error occurs while communicating with the server.
ObjectDoesNotExistException - If the server object does not exist.

read

public String read(int dataAreaOffset,
                   int dataLength,
                   int type)
            throws AS400SecurityException,
                   ErrorCompletingRequestException,
                   IllegalObjectTypeException,
                   InterruptedException,
                   IOException,
                   ObjectDoesNotExistException
Reads the data from the data area. It retrieves dataLength characters beginning at dataAreaOffset in the data area. The first character in the data area is at offset 0.

Parameters:
dataAreaOffset - The offset in the data area at which to start reading.
dataLength - The number of characters to read. Valid values are from 1 through (data area size - dataAreaOffset).
type - The Data Area bidi string type, as defined by the CDRA (Character Data Representataion Architecture). See BidiStringType for more information and valid values.
Returns:
The data read from the data area.
Throws:
AS400SecurityException - If a security or authority error occurs.
ErrorCompletingRequestException - If an error occurs before the request is completed.
IllegalObjectTypeException - If the server object is not the required type.
InterruptedException - If this thread is interrupted.
IOException - If an error occurs while communicating with the server.
ObjectDoesNotExistException - If the server object does not exist.

setPath

public void setPath(String path)
             throws PropertyVetoException
Sets the fully qualified data area name. The following example demonstrates the use of setPath:
   // Create a CharacterDataArea object.
   CharacterDataArea dataArea = new CharacterDataArea();

   // Set its path to be the data area "MYDATA" in the library "MYLIB".
   dataArea.setPath("/QSYS.LIB/MYLIB.LIB/MYDATA.DTAARA");
   

Parameters:
path - The fully qualified integrated file system path name of the data area.
Throws:
PropertyVetoException - If the change is vetoed.

write

public void write(String data)
           throws AS400SecurityException,
                  ErrorCompletingRequestException,
                  InterruptedException,
                  IOException,
                  ObjectDoesNotExistException
Writes the data to the data area. It writes data to the beginning of the data area. The remaining characters in the data area are blank padded.

Parameters:
data - The data to be written.
Throws:
AS400SecurityException - If a security or authority error occurs.
ErrorCompletingRequestException - If an error occurs before the request is completed.
InterruptedException - If this thread is interrupted.
IOException - If an error occurs while communicating with the server.
ObjectDoesNotExistException - If the server object does not exist.

write

public void write(String data,
                  int dataAreaOffset)
           throws AS400SecurityException,
                  ErrorCompletingRequestException,
                  InterruptedException,
                  IOException,
                  ObjectDoesNotExistException
Writes the data to the data area. It writes data.length() characters from data to the data area beginning at dataAreaOffset. The first character in the data area is at offset 0.

Parameters:
data - The data to be written.
dataAreaOffset - The offset in the data area at which to start writing.
Throws:
AS400SecurityException - If a security or authority error occurs.
ErrorCompletingRequestException - If an error occurs before the request is completed.
InterruptedException - If this thread is interrupted.
IOException - If an error occurs while communicating with the server.
ObjectDoesNotExistException - If the server object does not exist.

write

public void write(String data,
                  int dataAreaOffset,
                  int type)
           throws AS400SecurityException,
                  ErrorCompletingRequestException,
                  InterruptedException,
                  IOException,
                  ObjectDoesNotExistException
Writes the data to the data area. It writes data.length() characters from data to the data area beginning at dataAreaOffset. The first character in the data area is at offset 0.

Parameters:
data - The data to be written.
dataAreaOffset - The offset in the data area at which to start writing.
type - The Data Area bidi string type, as defined by the CDRA (Character Data Representataion Architecture). See BidiStringType for more information and valid values.
Returns:
The data read from the data area.
Throws:
AS400SecurityException - If a security or authority error occurs.
ErrorCompletingRequestException - If an error occurs before the request is completed.
InterruptedException - If this thread is interrupted.
IOException - If an error occurs while communicating with the server.
ObjectDoesNotExistException - If the server object does not exist.