public class Channel extends API
This is the Java implementation of CICS Channels
com.ibm.cics.server.API
for general restrictions on using the JCICS API.
Modifier and Type | Field and Description |
---|---|
static java.lang.String |
SYSTEM_PROPERTY_NAME_CONTAINER_EXISTENCE_CHECKING_ENABLED_DEFAULT
The name of a system property which can be set for this JVM server
such that if it has a value of false, it turns of checking for
the existence of containers on the
getContainer(java.lang.String)
method. |
Modifier and Type | Method and Description |
---|---|
ContainerIterator |
containerIterator()
Deprecated.
Deprecated in CICS TS version 6.1.
Use the
getContainerNames() method instead, followed by
getContainer(java.lang.String,boolean) (with the existence
checking flag having a value of false ). |
Container |
createContainer(java.lang.String containerName)
Create a Container in this Channel.
|
void |
delete()
Delete the Channel and all of its Containers
|
void |
deleteContainer(java.lang.String containerName)
Delete a Container from this Channel
|
Container |
getContainer(java.lang.String containerName)
Get a Java 'proxy' object which represents a Container with the specified
name in this Channel.
|
Container |
getContainer(java.lang.String containerName,
boolean isExistenceChecked)
Get a Java 'proxy' object which represents a Container with the specified
name in this Channel.
|
int |
getContainerCount()
Get the container count for this Channel
|
java.util.List<java.lang.String> |
getContainerNames()
Gets the list of names of all the containers currently existing on
this channel.
|
java.lang.String |
getName()
Get the name of the Channel as known to CICS
|
boolean |
isContainerExistenceCheckingEnabled()
get a property on the channel which controls the behaviour of future
calls to
getContainer(java.lang.String) |
void |
setContainerExistenceCheckingEnabled(boolean isCheckingEnabled)
Sets a property on the channel which controls the behaviour of future
calls to
getContainer(java.lang.String) |
java.lang.String |
toString() |
getCICSServerApiVersion
public static final java.lang.String SYSTEM_PROPERTY_NAME_CONTAINER_EXISTENCE_CHECKING_ENABLED_DEFAULT
getContainer(java.lang.String)
method. See the method documentation for more detail.
If not used, this system property is defaulted to true
.
The value of the property can be over-ridden using the
setContainerExistenceCheckingEnabled(boolean)
method.public Container createContainer(java.lang.String containerName) throws ContainerErrorException, ChannelErrorException
Container.put(byte[])
.containerName
- the name of the new ContainerContainerErrorException
- CONTAINERERRChannelErrorException
- CHANNELERRpublic Container getContainer(java.lang.String containerName) throws ContainerErrorException
The behaviour of this call depends on whether the ContainerExistenceCheckingEnabled property on this channel has been set to true or false.
The ContainerExistenceCheckingEnabled property can be set or cleared
either using the setContainerExistenceCheckingEnabled(boolean)
method, or
by using the JVM server system property with the name defined by
SYSTEM_PROPERTY_NAME_CONTAINER_EXISTENCE_CHECKING_ENABLED_DEFAULT
to true
or false
.
Specifying the property value using the
setContainerExistenceCheckingEnabled(boolean)
method
overrides any system property setting.
If checking is enabled, then the method checks for the existence of
a container of that name in the underlying CICS channel, and returns
the java 'proxy' container object (if the underlying container exists),
or null (if the underlying container does not exist).
If null
is returned, use the
createContainer(java.lang.String)
method to obtain a
Container
object.
If checking is disabled, then the method does not check the channel for the existence of the named underlying CICS container. A java 'proxy' object to represent the current or future CICS container with that name is returned.
When existence checking is not performed, the call will perform slightly better than when existence checking is performed.
containerName
- the name of the Container which the caller wishes
to manipulate in the future.
Before the supplied name is used to compare against names of containers
in this channel, it may be padded to match the length as all CICS containers.
If supplied name is shorter than (Container.MAX_CONTAINER_NAME_LENGTH
)
characters it will first be padded to that length by appending spaces
characters on the right of the name. For example a name of "MyContainer"
will match a container which has a name of
"MyContainer "
.
ContainerErrorException
- RESP(CONTAINERERR) The containerName provided
is longer than the allowable number of characters. See
Container.MAX_CONTAINER_NAME_LENGTH
public Container getContainer(java.lang.String containerName, boolean isExistenceChecked) throws ContainerErrorException
The behaviour of this call depends on whether the
Container existence checking logic has been enabled or disabled for this
call, controlled by the isExistenceChecked
parameter.
If checking is enabled, then the method checks for the existence of
a container of that name in the underlying CICS channel, and returns
the java 'proxy' container object (if the underlying container exists),
or null (if the underlying container does not exist).
If null
is returned, use the
createContainer(java.lang.String)
method to obtain a
Container
object.
If checking is disabled, then the method does not check the channel for the existence of the named underlying CICS container. A java 'proxy' object to represent the current or future CICS container with that name is returned.
When existence checking is not performed, the call will perform slightly better than when existence checking is performed.
containerName
- the name of the Container which the caller wishes
to manipulate in the future.
Before the supplied name is used to compare against names of containers
in this channel, it may be padded to match the length as all CICS containers.
If supplied name is shorter than (Container.MAX_CONTAINER_NAME_LENGTH
)
characters it will first be padded to that length by appending spaces
characters on the right of the name. For example a name of "MyContainer"
will match a container which has a name of
"MyContainer "
.
isExistenceChecked
- controls whether the existence of the underlying
CICS container is checked for or not.ContainerErrorException
- RESP(CONTAINERERR) The containerName provided
is longer than the allowable number of characters. See
Container.MAX_CONTAINER_NAME_LENGTH
public void deleteContainer(java.lang.String containerName) throws ContainerErrorException, ChannelErrorException, CCSIDErrorException, CodePageErrorException, InvalidRequestException
containerName
- the name of the Container to be deletedContainerErrorException
- CONTAINERERRChannelErrorException
- CHANNELERRInvalidRequestException
- INVREQCodePageErrorException
- CODEPAGEERRCCSIDErrorException
- CCSIDERRpublic java.lang.String getName()
public java.lang.String toString()
toString
in class java.lang.Object
@Deprecated public ContainerIterator containerIterator()
getContainerNames()
method instead, followed by
getContainer(java.lang.String,boolean)
(with the existence
checking flag having a value of false
).public void delete() throws ChannelErrorException
ChannelErrorException
- CHANNELERRpublic int getContainerCount() throws ChannelErrorException
ChannelErrorException
- CHANNELERRpublic java.util.List<java.lang.String> getContainerNames() throws ContainerErrorException, ChannelErrorException
Using this call is faster than using a ContainerIterator
Once you have a container name, the container object can be obtained
with the getContainer(java.lang.String,boolean)
method, where no further
checking for existence is required (so use 'false' for the boolean parameter).
The list of names is a snapshot of what exists at this point in time. Future additional containers may be subsequently created. Containers named in this list could be subsequently deleted.
The names in the list are padded to match the exact name in the
underlying CICS TS system. For example: Each name is left-justified, and padded with
spaces on the right, up to the limit of
Container.MAX_CONTAINER_NAME_LENGTH
characters.
ContainerErrorException
- CONTAINERERRChannelErrorException
- CHANNELERRpublic void setContainerExistenceCheckingEnabled(boolean isCheckingEnabled)
getContainer(java.lang.String)
Controls whether the getContainer(java.lang.String)
call
checks for the existence of containers or not, when the java 'proxy'
object is obtained.
If never set, the ContainerExistenceCheckingEnabled property on
this channel will be true
by default, or it will have a
value specified by the
SYSTEM_PROPERTY_NAME_CONTAINER_EXISTENCE_CHECKING_ENABLED_DEFAULT
JVM server system property.
Note: This value is held in the local java object and effects only
getContainer(java.lang.String)
calls which use the same java object.
It is not permanently stored in the underlying CICS channel,
and is not conveyed through the channel data to any other linked task,
or task which launched the current task.
isContainerExistenceCheckingEnabled()
on how to get the
current value of the property for this channel.isCheckingEnabled
- true if you wish existence checking to be enabled.
false if you do not wish to implicitly check for the existence of
underlying CICS containers.public boolean isContainerExistenceCheckingEnabled()
getContainer(java.lang.String)
getContainer(java.lang.String)
,
false if no checking will be performed.