com.ibm.as400.access.DecimalDataArea Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of jt400 Show documentation
The Open Source version of the IBM Toolbox for Java
The newest version!
///////////////////////////////////////////////////////////////////////////////
//
// JTOpen (IBM Toolbox for Java - OSS version)
//
// Filename:  DecimalDataArea.java
//
// The source code contained herein is licensed under the IBM Public License
// Version 1.0, which has been approved by the Open Source Initiative.
// Copyright (C) 1997-2004 International Business Machines Corporation and
// others.  All rights reserved.
//
///////////////////////////////////////////////////////////////////////////////

package com.ibm.as400.access;

import java.io.Serializable;
import java.io.IOException;
import java.math.BigDecimal;
import java.beans.PropertyVetoException;
import java.net.UnknownHostException;

/**
The DecimalDataArea class represents a decimal data area on the system.

The following example demonstrates the use of DecimalDataArea:
// Prepare to work with the system named "My400".
AS400 system = new AS400("My400");

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

// Create the decimal data area on the system using default values.
dataArea.create();

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

// Write to the data area.
dataArea.write(new BigDecimal("1.2"));

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

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

**/

// Note: (length, decimalPositions) for a DDA corresponds to
//       (precision, scale) for a decimal number.

// Note: If the value you write to the 400 has a greater scale (number
// of decimal positions) than the DDA will hold, the number will be
// truncated.

// Note: The largest precision (currently) for a DDA on the 400 is
// 24 digits which includes a scale of 9 digits. This means that the
// base part of the number (i.e. to the left of the decimal point) can
// only have a maximum of 15 digits, irrespective of the fact that the
// DDA may have been created with a greater precision.
//   For example, a DDA created with a precision of 20 and a scale of 3
//   means that the length of the DDA is 20, which includes the 3 digits
//   of scale. This means that there are theoretically 17 digits left to
//   use for the base part of the number. However, the DDA will still
//   only accept a maximum base of 15 digits.


public class DecimalDataArea extends DataArea implements Serializable
{
  private static final String copyright = "Copyright (C) 1997-2000 International Business Machines Corporation and others.";

 

    static final long serialVersionUID = 4L;

   /**
    Constants
   **/

   static final int DEFAULT_LENGTH = 15;

   /**
    Variables
   ***/

   private BigDecimal initialValue_ = new BigDecimal("0.0"); // The initial value written to the data area upon creation.

  //@B0 It was decided that the number of decimal positions should NOT be a bean property
  //    because the property getter getDecimalPositions() needs to go the system. Bean property
  //    constructors, getters, and setters should not make connections to the system
  //    because of the way a visual builder environment manipulates bean objects.
   private int decimalPositions_ = 5;  // The default number of decimal positions.


   /**
    Constructs a DecimalDataArea object.
    It creates a default DecimalDataArea object.  The system and path
    properties must be set before attempting a connection.
   **/
   public DecimalDataArea()
   {
     super();
     length_ = DEFAULT_LENGTH;
     dataAreaType_ = DECIMAL_DATA_AREA;
   }


   /**
   Constructs a DecimalDataArea object.
   It creates a DecimalDataArea instance that represents the data area path
   on system.
      @param system The system that contains the data area.
      @param 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
   **/
   public DecimalDataArea(AS400 system, String path)
   {
     super(system, path);
     length_ = DEFAULT_LENGTH;
     dataAreaType_ = DECIMAL_DATA_AREA;
   }


   /**
   Resets the data area to contain 0.0.
     @exception AS400SecurityException          If a security or authority error occurs.
     @exception ErrorCompletingRequestException If an error occurs before the request is completed.
     @exception InterruptedException            If this thread is interrupted.
     @exception IOException                     If an error occurs while communicating with the system.
     @exception ObjectDoesNotExistException     If the system object does not exist.
   **/
   public void clear()
       throws AS400SecurityException,
              ErrorCompletingRequestException,
              InterruptedException,
              IOException,
              ObjectDoesNotExistException
   {
     if (impl_ == null)
       chooseImpl();

     impl_.clear();

     // Fire the CLEARED event.
     fireCleared();
   }


   /**
   Creates a decimal data area on the system.
   This method uses the following default property values.
   
   length - 15 digits.
   
decimalPositions - 5 digits.
   
initialValue - A value of 0.0.
   
textDescription - A blank string.
   
authority - A value of *LIBCRTAUT.
   
     @exception AS400SecurityException          If a security or authority error occurs.
     @exception ErrorCompletingRequestException If an error occurs before the request is completed.
     @exception InterruptedException            If this thread is interrupted.
     @exception IOException                     If an error occurs while communicating with the system.
     @exception ObjectAlreadyExistsException    If the system object already exists.
     @exception ObjectDoesNotExistException     If the system object does not exist.
   **/
   public void create()
       throws AS400SecurityException,
              ErrorCompletingRequestException,
              InterruptedException,
              IOException,
              ObjectAlreadyExistsException,
              ObjectDoesNotExistException
   {
     if (impl_ == null)
       chooseImpl();

     impl_.create(length_, decimalPositions_, initialValue_, textDescription_, authority_);

     // Fire the CREATED event.
     fireCreated();
   }


   /**
   Creates a decimal data area with the specified attributes.
     @param length The maximum number of digits in the data area. Valid
            values are 1 through 24.
     @param decimalPositions The number of digits to the right of the decimal
            point. Valid values are 0 through 9.
     @param initialValue The initial value for the data area.
     @param textDescription The text description for the data area. The maximum length is 50 characters.
     @param 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.
     @exception AS400SecurityException          If a security or authority error occurs.
     @exception ErrorCompletingRequestException If an error occurs before the request is completed.
     @exception InterruptedException            If this thread is interrupted.
     @exception IOException                     If an error occurs while communicating with the system.
     @exception ObjectAlreadyExistsException    If the system object already exists.
     @exception ObjectDoesNotExistException     If the system object does not exist.
   **/
   public void create(int length, int decimalPositions,
                      BigDecimal initialValue, String textDescription,
                      String authority)
       throws AS400SecurityException,
              ErrorCompletingRequestException,
              InterruptedException,
              IOException,
              ObjectAlreadyExistsException,
              ObjectDoesNotExistException
   {
     // Validate the length parameter.
     if (length < 1 || length > 24)
       throw new ExtendedIllegalArgumentException("length",
         ExtendedIllegalArgumentException.RANGE_NOT_VALID);
     // Validate the number of decimal positions.
     if (decimalPositions < 0 || decimalPositions > 9)
       throw new ExtendedIllegalArgumentException("decimalPositions",
         ExtendedIllegalArgumentException.RANGE_NOT_VALID);
     // Validate the number of decimal positions in relation to the length.
     if (decimalPositions > length)
       throw new ExtendedIllegalArgumentException("decimalPositions",
         ExtendedIllegalArgumentException.PARAMETER_VALUE_NOT_VALID);

     // Validate the initialValue parameter.
     if (initialValue == null)
       throw new NullPointerException("initialValue");
     // Validate the text description parameter
     if (textDescription == null)
       throw new NullPointerException("textDescription");
     if (textDescription.length() > 50)
       throw new ExtendedIllegalArgumentException("textDescription",
         ExtendedIllegalArgumentException.LENGTH_NOT_VALID);
     // Validate the authority parameter.
     if (authority == null)
       throw new NullPointerException("authority");
     if (authority.length() == 0 || authority.length() > 10)
       throw new ExtendedIllegalArgumentException("authority",
         ExtendedIllegalArgumentException.LENGTH_NOT_VALID);

     length_ = length;
     decimalPositions_ = decimalPositions;
     initialValue_ = initialValue;
     textDescription_ = textDescription;
     authority_ = authority;

     create();
   }


   /**
   Removes the data area from the system.
     @exception AS400SecurityException          If a security or authority error occurs.
     @exception ErrorCompletingRequestException If an error occurs before the request is completed.
     @exception InterruptedException            If this thread is interrupted.
     @exception IOException                     If an error occurs while communicating with the system.
     @exception ObjectDoesNotExistException     If the object does not exist.
   **/
   public void delete()
       throws AS400SecurityException,
              ErrorCompletingRequestException,
              InterruptedException,
              IOException,
              ObjectDoesNotExistException
   {
     super.delete0();
   }


   /**
   Returns the number of digits to the right of the decimal point in this data area.
     @return The number of decimal positions.
     @exception AS400SecurityException          If a security or authority error occurs.
     @exception ErrorCompletingRequestException If an error occurs before the request is completed.
     @exception IllegalObjectTypeException      If the system object is not the required type.
     @exception InterruptedException            If this thread is interrupted.
     @exception IOException                     If an error occurs while communicating with the system.
     @exception ObjectDoesNotExistException     If the system object does not exist.
   **/
   public int getDecimalPositions()
        throws AS400SecurityException,
               ErrorCompletingRequestException,
               IllegalObjectTypeException,
               InterruptedException,
               IOException,
               ObjectDoesNotExistException
   {
  //@B0 It was decided that the number of decimal positions should NOT be a bean property
  //    because the property getter getDecimalPositions() needs to go the system. Bean property
  //    constructors, getters, and setters should not make connections to the system
  //    because of the way a visual builder environment manipulates bean objects.
     if (impl_ == null)
       chooseImpl();

     return impl_.getDecimalPositions();
   }


   /**
   Returns the integrated file system path name of the object represented by the data area.
      @return The integrated file system path name of the object represented by the data area.
   **/
   public String getPath()
   {
     return super.getPath();
   }


   /**
   Returns the data read from the data area.
     @return The decimal data read from the data area.
     @exception AS400SecurityException          If a security or authority error occurs.
     @exception ErrorCompletingRequestException If an error occurs before the request is completed.
     @exception IllegalObjectTypeException      If the system object is not the required type.
     @exception InterruptedException            If this thread is interrupted.
     @exception IOException                     If an error occurs while communicating with the system.
     @exception ObjectDoesNotExistException     If the system object does not exist.
   **/
   public BigDecimal read()
        throws AS400SecurityException,
               ErrorCompletingRequestException,
               IllegalObjectTypeException,
               InterruptedException,
               IOException,
               ObjectDoesNotExistException
   {
     if (impl_ == null)
       chooseImpl();

     BigDecimal val = impl_.readBigDecimal();

     fireRead(); // Fire the READ event.

     return val;
   }


   /**
   Sets the fully qualified data area name.
   The following example demonstrates the use of setPath:
      // Create a DecimalDataArea object.
   DecimalDataArea dataArea = new DecimalDataArea();

   // Set its path to be the data area "MYDATA" in the library "MYLIB".
   dataArea.setPath("/QSYS.LIB/MYLIB.LIB/MYDATA.DTAARA");
   
     @param path The fully qualified integrated file system path name of the data area.
     @exception PropertyVetoException If the change is vetoed.
   **/
   public void setPath(String path) throws PropertyVetoException
   {
     super.setPath(path);
   }


   /**
   Writes data to the data area.
     @param data The decimal data to be written.
     @exception AS400SecurityException          If a security or authority error occurs.
     @exception ErrorCompletingRequestException If an error occurs before the request is completed.
     @exception InterruptedException            If this thread is interrupted.
     @exception IOException                     If an error occurs while communicating with the system.
     @exception ObjectDoesNotExistException     If the system object does not exist.
   **/
   public void write(BigDecimal data)
       throws AS400SecurityException,
              ErrorCompletingRequestException,
              InterruptedException,
              IOException,
              ObjectDoesNotExistException
   {
     // Validate the data parameter.
     if (data == null)
       throw new NullPointerException("data");

     // Do the write
     if (impl_ == null)
       chooseImpl();

     impl_.write(data);

     // Fire the WRITTEN event.
     fireWritten();
   }
}