com.ibm.as400.access
Class EnvironmentVariable

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

public class EnvironmentVariable
extends Object
implements Serializable

The EnvironmentVariable class represents a server system-level environment variable. An environment variable is uniquely identified by the system and the environment variable name. Environment variable names are case sensitive and cannot contain spaces or equals signs (=).

This class can only access system-level environment variables. You must have *JOBCTL special authority to add, change, or delete system-level environment variables.

Every environment variable has a CCSID associated with it which describes the CCSID in which its contents are stored. The default CCSID is that of the current job.

Note that environment variables are different than system values, although they are often used for the same purpose. See SystemValue for more information on how to access system values.

The environment variable value and CCSID are cached after being read once. Call refreshValue() to force the value and CCSID to be refreshed.

The following example creates two EnvironmentVariables and sets and gets their values.

    AS400 system = new AS400("mysystem");
    EnvironmentVariable fg = new EnvironmentVariable(system, "FOREGROUND");
    fg.setValue("RED");

    EnvironmentVariable bg = new EnvironmentVariable(system, "BACKGROUND");
    String background = bg.getValue();
 

See Also:
EnvironmentVariableList, Serialized Form

Constructor Summary
EnvironmentVariable()
          Constructs an EnvironmentVariable object.
EnvironmentVariable(AS400 system)
          Constructs an EnvironmentVariable object.
EnvironmentVariable(AS400 system, String name)
          Constructs an EnvironmentVariable object.
 
Method Summary
 void addPropertyChangeListener(PropertyChangeListener listener)
          Adds a PropertyChangeListener.
 void delete()
          Deletes the environment variable.
 int getCCSID()
          Returns the environment variable CCSID.
 String getName()
          Returns the environment variable name.
 String getName(int stringType)
          Returns the environment variable name.
 AS400 getSystem()
          Returns the server on which the environment variable exists.
 String getValue()
          Returns the value of the environment variable.
 String getValue(int stringType)
          Returns the value of the environment variable.
 void refreshValue()
          Refreshes the environment variable value and CCSID.
 void removePropertyChangeListener(PropertyChangeListener listener)
          Removes the PropertyChangeListener.
 void setName(String name)
          Sets the environment variable name.
 void setName(String name, int stringType)
          Sets the environment variable name.
 void setSystem(AS400 system)
          Sets the server for the environment variable.
 void setValue(String value)
          Sets the value of the environment variable.
 void setValue(String value, int ccsid)
          Sets the value of the environment variable.
 void setValue(String value, int ccsid, int stringType)
          Sets the value of the environment variable.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

EnvironmentVariable

public EnvironmentVariable()
Constructs an EnvironmentVariable object.


EnvironmentVariable

public EnvironmentVariable(AS400 system)
Constructs an EnvironmentVariable object.

Parameters:
system - The server on which the environment variable exists.

EnvironmentVariable

public EnvironmentVariable(AS400 system,
                           String name)
Constructs an EnvironmentVariable object.

Environment variable names are case sensitive and cannot contain spaces or equals signs (=).

Parameters:
system - The server on which the environment variable exists.
name - The environment variable name.
Method Detail

addPropertyChangeListener

public void addPropertyChangeListener(PropertyChangeListener listener)
Adds a PropertyChangeListener. The specified PropertyChangeListener's propertyChange() method will be called each time the value of any bound property is changed.

Parameters:
listener - The listener object.

delete

public void delete()
            throws AS400SecurityException,
                   ErrorCompletingRequestException,
                   InterruptedException,
                   IOException,
                   ObjectDoesNotExistException
Deletes the environment variable. You must have *JOBCTL special authority to delete system-level environment variables.

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 on the server.

getCCSID

public int getCCSID()
             throws AS400SecurityException,
                    ErrorCompletingRequestException,
                    InterruptedException,
                    IOException,
                    ObjectDoesNotExistException
Returns the environment variable CCSID.

Returns:
The environment variable CCSID.
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 on the server.

getName

public String getName()
Returns the environment variable name.

Returns:
The environment variable name.

getName

public String getName(int stringType)
Returns the environment variable name.

Parameters:
stringType - The environment variable bidi string type, as defined by the CDRA (Character Data Representataion Architecture). See BidiStringType for more information and valid values.
Returns:
The environment variable name.

getSystem

public AS400 getSystem()
Returns the server on which the environment variable exists.

Returns:
The server on which the environment variable exists. If the server has not been set, null is returned.

getValue

public String getValue()
                throws AS400SecurityException,
                       ErrorCompletingRequestException,
                       InterruptedException,
                       IOException,
                       ObjectDoesNotExistException
Returns the value of the environment variable.

Returns:
The value.
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 on the server.

getValue

public String getValue(int stringType)
                throws AS400SecurityException,
                       ErrorCompletingRequestException,
                       InterruptedException,
                       IOException,
                       ObjectDoesNotExistException
Returns the value of the environment variable.

Parameters:
stringType - The environment variable bidi string type, as defined by the CDRA (Character Data Representataion Architecture). See BidiStringType for more information and valid values.
Returns:
The value.
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 on the server.

refreshValue

public void refreshValue()
                  throws AS400SecurityException,
                         ErrorCompletingRequestException,
                         InterruptedException,
                         IOException,
                         ObjectDoesNotExistException
Refreshes the environment variable value and CCSID.

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 on the server.

removePropertyChangeListener

public void removePropertyChangeListener(PropertyChangeListener listener)
Removes the PropertyChangeListener.

Parameters:
listener - The listener object.

setName

public void setName(String name)
Sets the environment variable name. This does not change the environment variable name on the server. Instead, it changes the environment variable to which this EnvironmentVariable object references.

Environment variable names are case sensitive and cannot contain spaces or equals signs (=).

Parameters:
name - The environment variable name.

setName

public void setName(String name,
                    int stringType)
Sets the environment variable name. This does not change the environment variable name on the server. Instead, it changes the environment variable to which this EnvironmentVariable object references.

Environment variable names are case sensitive and cannot contain spaces or equals signs (=).

Parameters:
name - The environment variable name.
stringType - The environment variable bidi string type, as defined by the CDRA (Character Data Representataion Architecture). See BidiStringType for more information and valid values.

setSystem

public void setSystem(AS400 system)
Sets the server for the environment variable. The server cannot be changed once a connection is made to the server.

Parameters:
system - The server on which the environment variable exists.

setValue

public void setValue(String value)
              throws AS400SecurityException,
                     ErrorCompletingRequestException,
                     InterruptedException,
                     IOException,
                     ObjectDoesNotExistException
Sets the value of the environment variable. The CCSID will be set to the job CCSID. You must have *JOBCTL special authority to add or change system-level environment variables.

Parameters:
value - The value.
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 on the server.

setValue

public void setValue(String value,
                     int ccsid)
              throws AS400SecurityException,
                     ErrorCompletingRequestException,
                     InterruptedException,
                     IOException,
                     ObjectDoesNotExistException
Sets the value of the environment variable. You must have *JOBCTL special authority to add or change system-level environment variables.

Parameters:
value - The value.
ccsid - The CCSID. Possible values are:
  • 0 - Use the job CCSID.
  • 65535 - Do not translate.
  • Any valid CCSID
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 on the server.

setValue

public void setValue(String value,
                     int ccsid,
                     int stringType)
              throws AS400SecurityException,
                     ErrorCompletingRequestException,
                     InterruptedException,
                     IOException,
                     ObjectDoesNotExistException
Sets the value of the environment variable. You must have *JOBCTL special authority to add or change system-level environment variables.

Parameters:
value - The value.
ccsid - The CCSID. Possible values are:
  • 0 - Use the job CCSID.
  • 65535 - Do not translate.
  • Any valid CCSID
stringType - The environment variable bidi string type, as defined by the CDRA (Character Data Representataion Architecture). See BidiStringType for more information and valid 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.
ObjectDoesNotExistException - If the object does not exist on the server.