com.ibm.cics.server

Class Channel

    • Field Detail

      • SYSTEM_PROPERTY_NAME_CONTAINER_EXISTENCE_CHECKING_ENABLED_DEFAULT

        public static final 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. 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.
        See Also:
        Constant Field Values
        Since CICS TS version:
        6.1
        Since package version:
        2.0.0
    • Method Detail

      • createContainer

        public Container createContainer(java.lang.String containerName)
                                  throws ContainerErrorException,
                                         ChannelErrorException
        Create a Container in this Channel. The Container created by this method is actually a proxy object, as opposed to a real container within CICS. The actual container in CICS is not created (if it doesn't already exist) until data is written to it using a method such as Container.put(byte[]).
        Parameters:
        containerName - the name of the new Container
        Returns:
        The newly created Container
        Throws:
        ContainerErrorException - CONTAINERERR
        ChannelErrorException - CHANNELERR
        Since CICS TS version:
        3.1
        Since package version:
        1.0.0
      • getContainer

        public Container getContainer(java.lang.String containerName)
                               throws ContainerErrorException
        Get a Java 'proxy' object which represents a Container with the specified name in this Channel.

        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.

        Parameters:
        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 ".

        Returns:
        The java 'proxy' object to represent the CICS Container with the name requested, or null if it does not exist and the ContainerExistenceCheckingEnabled property is true. See the description above for more detail.
        Throws:
        ContainerErrorException - RESP(CONTAINERERR) The containerName provided is longer than the allowable number of characters. See Container.MAX_CONTAINER_NAME_LENGTH
        Since CICS TS version:
        3.1
        Since package version:
        1.0.0
      • getContainer

        public Container getContainer(java.lang.String containerName,
                                      boolean isExistenceChecked)
                               throws ContainerErrorException
        Get a Java 'proxy' object which represents a Container with the specified name in this Channel.

        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.

        Parameters:
        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.
        Returns:
        The java 'proxy' object to represent the CICS Container with the name requested, or null if it does not exist and the ContainerExistenceCheckingEnabled property is true. See the description above for more detail.
        Throws:
        ContainerErrorException - RESP(CONTAINERERR) The containerName provided is longer than the allowable number of characters. See Container.MAX_CONTAINER_NAME_LENGTH
        Since CICS TS version:
        6.1
        Since package version:
        2.0.0
      • getName

        public java.lang.String getName()
        Get the name of the Channel as known to CICS
        Returns:
        The name of the Channel
        Since CICS TS version:
        3.1
        Since package version:
        1.0.0
      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object
        Since CICS TS version:
        6.1
        Since package version:
        2.0.0
      • containerIterator

        @Deprecated
        public 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).
        Create a ContainerIterator for the Channel
        Returns:
        The ContainerIterator for this Channel
        Since CICS TS version:
        3.1
        Since package version:
        1.0.0
      • getContainerCount

        public int getContainerCount()
                              throws ChannelErrorException
        Get the container count for this Channel
        Returns:
        int the number of containers in the channel
        Throws:
        ChannelErrorException - CHANNELERR
        Since CICS TS version:
        5.3
        Since package version:
        1.600.0
      • getContainerNames

        public java.util.List<java.lang.String> getContainerNames()
                                                           throws ContainerErrorException,
                                                                  ChannelErrorException
        Gets the list of names of all the containers currently existing on this channel.

        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.

        Returns:
        An immutable list of names of CICS containers which currently exist in this channel.
        Throws:
        ContainerErrorException - CONTAINERERR
        ChannelErrorException - CHANNELERR
        Since CICS TS version:
        6.1
        Since package version:
        2.0.0
      • setContainerExistenceCheckingEnabled

        public void setContainerExistenceCheckingEnabled(boolean isCheckingEnabled)
        Sets a property on the channel which controls the behaviour of future calls to 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.

        See isContainerExistenceCheckingEnabled() on how to get the current value of the property for this channel.
        Parameters:
        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.
        Since CICS TS version:
        6.1
        Since package version:
        2.0.0
      • isContainerExistenceCheckingEnabled

        public boolean isContainerExistenceCheckingEnabled()
        get a property on the channel which controls the behaviour of future calls to getContainer(java.lang.String)
        Returns:
        true if checking for the existence of the underlying CICS container will occur on future calls to getContainer(java.lang.String), false if no checking will be performed.
        Since CICS TS version:
        6.1
        Since package version:
        2.0.0