com.ibm.as400.access
Class Subsystem

java.lang.Object
  |
  +--com.ibm.as400.access.Subsystem

public class Subsystem

extends Object

Represents a subsystem on the server. Most of the getter methods simply return the cached attribute value obtained by the most recent refresh(). Other than getObjectDescription(), none of the getters will themselves go to the system to get the current attribute value. Prior to the first refresh(), many of the getters will return null or zero.
Example:

 Subsystem sbs = new Subsystem(system, library, name);

 if (!sbs.exists()) {

   System.out.println("No such subsystem: "+sbs.getPath());

 }

 else {

   sbs.refresh();

   System.out.println("Status: " + sbs.getStatus());

   System.out.println("Number of jobs: " + sbs.getCurrentActiveJobs());

   System.out.println("Maximum jobs: " + sbs.getMaximumActiveJobs());

   SystemPool[] pools = sbs.getPools();

   System.out.print("Pools: ");

   if (pools == null) System.out.println("null");

   else for (int i=0; i<pools.length ;="" {="" system.out.print="" ="" +="" (pools[i="=" ?="" null="" :="" pools[i].getname="" }="" system.out.println="" all="" subsystems="" on="" +system.getsystemname="" subsystem="" list="Subsystem.listAllSubsystems(system);" for="" (int="" i=""><list.length ;="" i="" {="" system.out.println(list[i].getlibrary="" +list[i].getname="" }=""></list.length></pools.length>

NO_MAX

public static final int NO_MAX

Value for the maximumActiveJobs property, indicating "no maximum".

See Also:

Constant Field Values

NO_TIME_LIMIT

public static final int NO_TIME_LIMIT

Value for the timeLimit parameter of the end() methods, indicating "no time limit".

See Also:

Constant Field Values

Subsystem

public Subsystem(AS400 system,
                 String library,
                 String name)

Constructs a Subsystem object.
Note: Does not create a subsystem on the server.

Parameters:

system - The system.

library - The name of the library where the subsystem resides.

name - The simple name of the subsystem.

See Also:

create()

Subsystem

public Subsystem(AS400 system,
                 String path)

Constructs a Subsystem object.
Note: Does not create a subsystem on the server.

Parameters:

system - The system.

path - The qualified path. For example, "/QSYS.LIB/MYSUBSYS.SBSD".

See Also:

create()

assignPool

public void assignPool(int sequenceNumber,
                       String poolName)
                throws AS400Exception,
                       AS400SecurityException,
                       ErrorCompletingRequestException,
                       InterruptedException,
                       IOException,
                       ObjectDoesNotExistException

Adds a shared system pool to the list of storage pools defined for the subsystem. Current pool definitions, other than the one specified, remain unchanged.

Parameters:

sequenceNumber - The number of the pool, within the pool list for the subsystem. Valid values are 1-10.

poolName - The name of a shared system storage pool. Valid values include: *BASE, *NOSTG, *INTERACT, *SPOOL, and *SHRPOOLnn, where nn is an integer from 1 to 60.

Throws:

AS400Exception - If the server returns an error message.

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.

assignPool

public void assignPool(int sequenceNumber,
                       int size,
                       int activityLevel)
                throws AS400Exception,
                       AS400SecurityException,
                       ErrorCompletingRequestException,
                       InterruptedException,
                       IOException,
                       ObjectDoesNotExistException

Defines a private storage pool and adds it to the list of storage pools defined for the subsystem. Current pool definitions, other than the one specified, remain unchanged.

Parameters:

sequenceNumber - The number of the pool, within the pool list for the subsystem. Valid values are 1-10.

size - The size of the storage pool, in kilobytes. Must be at least 256 (meaning 256 kilobytes).

activityLevel - The activity level of the pool.

Throws:

AS400Exception - If the server returns an error message.

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.

changeDescriptionText

public void changeDescriptionText(String text)
                           throws AS400Exception,
                                  AS400SecurityException,
                                  ErrorCompletingRequestException,
                                  InterruptedException,
                                  IOException,
                                  ObjectDoesNotExistException

Sets the subsystem description text. The default is "".

Parameters:

text - The subsystem description text. To clear the description, specify "".

Throws:

AS400Exception - If the server returns an error message.

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.

changeDisplayFilePath

public void changeDisplayFilePath(String path)
                           throws AS400Exception,
                                  AS400SecurityException,
                                  ErrorCompletingRequestException,
                                  InterruptedException,
                                  IOException,
                                  ObjectDoesNotExistException

Specifies the signon display file that is used when showing signon displays at work stations allocated to the subsystem. By default, QSYS/QDSIGNON (path /QSYS.LIB/QDSIGNON.FILE) is used.

Parameters:

path - The fully qualified pathname of the signon display file. See QSYSObjectPathName.toString()

Throws:

AS400Exception - If the server returns an error message.

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.

changeLanguageLibrary

public void changeLanguageLibrary(String library)
                           throws AS400Exception,
                                  AS400SecurityException,
                                  ErrorCompletingRequestException,
                                  InterruptedException,
                                  IOException,
                                  ObjectDoesNotExistException

Specifies a library to enter ahead of other libraries in the system portion of the library list. This method allows you to use a secondary language library.

Parameters:

library - The name of the library. Specify "" or "*NONE" to remove the current secondary language library from the system library list.

Throws:

AS400Exception - If the server returns an error message.

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.

changeMaximumActiveJobs

public void changeMaximumActiveJobs(int maxJobs)
                             throws AS400Exception,
                                    AS400SecurityException,
                                    ErrorCompletingRequestException,
                                    InterruptedException,
                                    IOException,
                                    ObjectDoesNotExistException

Sets the maximum number of active jobs that can run or use resources within the subsystem at one time.

Parameters:

maxJobs - The maximum number of active jobs. Valid values are 0-1000. Special value NO_MAX is the default, and indicates no maximum.

Throws:

AS400Exception - If the server returns an error message.

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.

create

public void create()
            throws AS400Exception,
                   AS400SecurityException,
                   ErrorCompletingRequestException,
                   InterruptedException,
                   IOException,
                   ObjectDoesNotExistException,
                   ObjectAlreadyExistsException

Creates the subsystem on the server.
More precisely, this method creates a subsystem description on the server.

Throws:

AS400Exception - If the server returns an error message.

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.

ObjectAlreadyExistsException - If the object already exists on the server.

create

public void create(String authority)
            throws AS400Exception,
                   AS400SecurityException,
                   ErrorCompletingRequestException,
                   InterruptedException,
                   IOException,
                   ObjectDoesNotExistException,
                   ObjectAlreadyExistsException

Creates the subsystem on the server.
More precisely, this method creates a subsystem description on the server.

Parameters:

authority - The authority to give to users who do not have specific authority for the object, who are not on an authorization list, and whose group profile or supplemental group profiles do not have specific authority for the object. The default is *LIBCRTAUT. The "base system pool" (*BASE) is used.

Throws:

AS400Exception - If the server returns an error message.

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.

ObjectAlreadyExistsException - If the object already exists on the server.

delete

public void delete()
            throws AS400Exception,
                   AS400SecurityException,
                   ErrorCompletingRequestException,
                   InterruptedException,
                   IOException

Deletes the subsystem from the server.
More precisely, this method deletes a subsystem description on the server.

Throws:

AS400Exception - If the server returns an error message.

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.

end

public void end(int timeLimit)
         throws AS400Exception,
                AS400SecurityException,
                ErrorCompletingRequestException,
                InterruptedException,
                IOException,
                ObjectDoesNotExistException

Ends the subsystem on the server, in a controlled manner. This allows the programs that are running in the subsystem, to perform cleanup (end of job processing). When a job being ended has a signal handling procedure for the asynchronous signal SIGTERM, the SIGTERM signal is generated for that job. The application has timeLimit seconds to complete cleanup before the job is ended.

Parameters:

timeLimit - The amount of time (in seconds) that is allowed to complete the controlled subsystem end operation. If this amount of time is exceeded and the end operation is not complete, any jobs still being processed in the subsystem are ended immediately. Special value NO_TIME_LIMIT indicates no time limit.

Throws:

AS400Exception - If the server returns an error message.

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.

endAllSubsystems

public static void endAllSubsystems(AS400 system,
                                    int timeLimit)
                             throws AS400Exception,
                                    AS400SecurityException,
                                    ErrorCompletingRequestException,
                                    InterruptedException,
                                    IOException

Ends all active subsystems on the server, in a controlled manner.

Parameters:

system - The system.

timeLimit - The amount of time (in seconds) that is allowed to complete the controlled subsystem end operation. If this amount of time is exceeded and the end operation is not complete, any jobs still being processed in the subsystem are ended immediately. Special value NO_TIME_LIMIT indicates no time limit.

Throws:

AS400Exception - If the server returns an error message.

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.

endAllSubsystemsImmediately

public static void endAllSubsystemsImmediately(AS400 system)
                                        throws AS400Exception,
                                               AS400SecurityException,
                                               ErrorCompletingRequestException,
                                               InterruptedException,
                                               IOException

Ends all active subsystems on the server, immediately.

Parameters:

system - The system.

Throws:

AS400Exception - If the server returns an error message.

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.

endImmediately

public void endImmediately()
                    throws AS400Exception,
                           AS400SecurityException,
                           ErrorCompletingRequestException,
                           InterruptedException,
                           IOException,
                           ObjectDoesNotExistException

Ends the subsystem on the server, immediately.

Throws:

AS400Exception - If the server returns an error message.

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.

equals

public boolean equals(Object obj)

Determines whether this Subsystem object is equal to another object.

Overrides:

equals in class Object

Returns:

true if the two instances are equal

exists

public boolean exists()
               throws AS400Exception,
                      AS400SecurityException,
                      ErrorCompletingRequestException,
                      InterruptedException,
                      IOException,
                      ObjectDoesNotExistException

Determines if the subsystem currently exists on the system.
More precisely, this method reports if the subsystem description exists on the server.

Returns:

true if the subsystem exists; false if the subsystem does not exist.

Throws:

AS400Exception - If the program call returns error messages.

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 API (that queries subsystem description information) is missing.

getCurrentActiveJobs

public int getCurrentActiveJobs()

Returns the number of jobs currently active in the subsystem.

Returns:

The number of currently active jobs. 0 if refresh() has not been called, or if the subsystem status is *INACTIVE.

getDescriptionText

public String getDescriptionText()

Returns the subsystem description text.

Returns:

The subsystem description text. null if refresh() has not been called. "" if description is blank.

getDisplayFilePath

public String getDisplayFilePath()

Returns the path of the signon display file that is used when showing signon displays at work stations allocated to the subsystem. By default, QSYS/QDSIGNON (path /QSYS.LIB/QDSIGNON.FILE) is used.

Returns:

The path of the signon display file. null if refresh() has not been called.

getLanguageLibrary

public String getLanguageLibrary()
                          throws AS400Exception,
                                 AS400SecurityException,
                                 ErrorCompletingRequestException,
                                 InterruptedException,
                                 IOException,
                                 ObjectDoesNotExistException

Returns the library that is entered ahead of other libraries in the system portion of the library list. This library typically specifies a secondary language library.

Returns:

The name of the secondary language library. null if refresh() has not been called. "*NONE" if no secondary language library is set.

Throws:

AS400Exception - If the server returns an error message.

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.

getLibrary

public String getLibrary()

Returns the name of the library where the subsystem resides on the server.

Returns:

The name of the library.

getMaximumActiveJobs

public int getMaximumActiveJobs()

Returns the maximum number of active jobs that can run or use resources within the subsystem at one time.

Returns:

The maximum number of active jobs. 0 if refresh() has not been called. NO_MAX if no maximum.

getMonitorJob

public Job getMonitorJob()

Returns the subsystem monitor job.

Returns:

The subsystem monitor job. null if refresh() has not been called, or if subsystem status is *INACTIVE.

getName

public String getName()

Returns the subsystem name.

Returns:

The subsystem name.

getObjectDescription

public ObjectDescription getObjectDescription()

Returns an ObjectDescription instance representing the subsystem.

Returns:

An ObjectDescription for the subsystem.

getPath

public String getPath()

Returns the fully-qualifed IFS pathname of the subsystem. For example: "/QSYS.LIB/MYSUBSYS.SBSD".

Returns:

The path of the subsystem.

getPool

public SystemPool getPool(int sequenceNumber)

Returns the storage pool defined at the specified position for the subsystem.

Parameters:

sequenceNumber - The number of the pool, within the pool list for the subsystem. Valid values are 1-10.

Returns:

The pool used by the subsystem, at the specified sequence position. null if refresh() has not been called, or if no pool has been assigned at that position.

getPools

public SystemPool[] getPools()

Returns the list of storage pools that are defined for the subsystem. That is, the list of storage pool definitions that are in the subsystem description. The element at offset 0 represents subsystem pool #1, element at offset 1 represents pool #2, and so on. In positions where no pool assignment has been made, the array element will be null.

Returns:

The pools that are used by the subsystem. null if refresh() has not been called. Otherwise, a 10-element array is returned.

getStatus

public String getStatus()

Returns the extended status of the subsystem. Possible values are: *ACTIVE, *ENDING, *INACTIVE, *RESTRICTED, and *STARTING.

Returns:

The subsystem status. null if refresh() has not been called.

getSystem

public AS400 getSystem()

Returns the system where the subsystem resides.

Returns:

The system.

listAllSubsystems

public static Subsystem[] listAllSubsystems(AS400 system)
                                     throws AS400Exception,
                                            AS400SecurityException,
                                            ErrorCompletingRequestException,
                                            InterruptedException,
                                            IOException,
                                            ObjectDoesNotExistException,
                                            RequestNotSupportedException

Lists all subsystems on the system.

Returns:

A list of all defined subsystems, both active and inactive.

Throws:

AS400Exception - If the server returns an error message.

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.

RequestNotSupportedException - If the requested function is not supported because the server is not at the correct level.

refresh

public void refresh()
             throws AS400Exception,
                    AS400SecurityException,
                    ErrorCompletingRequestException,
                    InterruptedException,
                    IOException,
                    ObjectDoesNotExistException

Refreshes the attributes of this Subsystem object, to reflect the current state of the subsystem on the server.

Throws:

AS400Exception - If the server returns an error message.

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.

removePool

public void removePool(int sequenceNumber)
                throws AS400Exception,
                       AS400SecurityException,
                       ErrorCompletingRequestException,
                       InterruptedException,
                       IOException,
                       ObjectDoesNotExistException

Removes a storage pool from the list of pools defined for the subsystem. You should first end the subsystem before removing a pool.

Parameters:

sequenceNumber - The number of the pool, within the pool list for the subsystem. Valid values are 1-10.

Throws:

AS400Exception - If the server returns an error message.

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.

start

public void start()
           throws AS400Exception,
                  AS400SecurityException,
                  ErrorCompletingRequestException,
                  InterruptedException,
                  IOException,
                  ObjectDoesNotExistException

Starts the subsystem on the server.

Throws:

AS400Exception - If the server returns an error message.

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.