Configuration Tool Online Help

[ Bottom of Page | Previous Page | Next Page | Table of Contents | Index ]


Gateway daemon settings

Partial Table-of-Contents

  • APPLID
  • APPLID qualifier
  • Initial number of Connection Manager threads
  • Maximum number of Connection Manager threads
  • Initial number of Worker threads
  • Maximum number of Worker threads
  • Enable reading input from console
  • Let Java Clients obtain generic ECI replies
  • Validate Units of Work
  • Validate message qualifiers
  • Timeout for in-progress requests to complete (ms)
  • Worker thread available timeout (ms)
  • Port for local administration
  • Display TCP/IP host names
  • Log Client connections and disconnections
  • Error and warning log destination
  • Error log file name
  • Error log maximum size (KB)
  • Maximum number of error log files
  • Use the same settings for error and information logs
  • Information log destination
  • Information log file name
  • Information log maximum size (KB)
  • Maximum number of information log files
  • Statistics Interval (HHMMSS)
  • Statistics End of Day time (HHMMSS)
  • Use these request monitors
  • This panel contains Gateway daemon settings that are common to all protocol handlers. The panel has these tabs:


    APPLID

    The APPLID is used to identify the instance of the CICS Transaction Gateway on server connections, in messages and data output, and tasks in a CICSplex.

    Enter up to 8 characters, or leave this field blank. There is no restriction on the characters that can be used in APPLID, but to ensure that the APPLID is valid for use in all scenarios, it is advisable to restrict the characters used to be in the range A through Z, and 0 through 9. The character strings entered are converted to uppercase for SNA and TCP/IP connections.

    The name must be unique within the CICS server system. The value of blank automatically generates a name that is guaranteed to be unique.


    APPLID qualifier

    The APPLID qualifier is used as a high-level qualifier for the APPLID.

    Enter up to 8 characters, or leave this field blank. There is no restriction on the characters that can be used in APPLID qualifier, but to ensure that the APPLID qualifier is valid for use in all scenarios, it is advisable to restrict the characters used to be in the range A through Z, and 0 through 9.

    In combination with the APPLID, the fully-qualified APPLID identifies the CICS Transaction Gateway to the CICS system that it connects to.

    If the configuration file, ctg.ini, contains an APPLID but not an APPLID qualifier, the system uses the default value 9UNKNOWN for APPLID qualifier. This value matches the initial default in CICS Transaction Server. If the default is kept, the value is included in messages generated in the Gateway daemon and in CICS, and in statistics. Having a default provides a reference value that makes problem diagnosis simpler. The default can be used in either a local mode or a remote mode topology.

    Initial number of Connection Manager threads

    Enter a number in the range 1 through 1,000,000 to specify the initial number of connection manager threads.

    Set this number to the usual number of JavaGateway objects opened by all connected Java™ clients. The default is 1. You might need to set this number to less than the supported maximum value because of constraints on memory or other system resources. If you enter a value outside the permitted range, the Configuration Tool warns you. If the value entered is too low, it substitutes the minimum. If the value entered is too high, it substitutes the maximum. If a non-numeric value is present in the configuration file, it substitutes the minimum value.

    On UNIX and Linux: You can override this setting with the ctgstart -initconnect=number command.
    On Windows: You can override this setting with the ctgservice -R -A -initconnect=number command.


    Maximum number of Connection Manager threads

    Enter a number in the range 1 through 1,000,000 to specify the maximum number of connection manager threads.

    The default is 100. You might need to set this number to less than the supported maximum value because of constraints on memory or other system resources. If you enter a value outside the permitted range, the Configuration Tool warns you. If the value entered is too low, it substitutes the minimum. If the value entered is too high, it substitutes the maximum. If a non-numeric value is present in the configuration file, it substitutes the minimum value.

    This value limits the maximum number of JavaGateway objects opened by all connected Java Client applications. Set it to the maximum number of JavaGateway objects that could be open at any one time from all the remotely connected Java Client applications.

    If you select the Unrestricted check box, no limits are applied to the number of connection manager threads. This option is not available on CICS Transaction Gateway Desktop Edition.

    On UNIX and Linux: You can override this setting with the ctgstart -maxconnect=number command.
    On Windows: You can override this setting with the ctgservice -R -A -maxconnect=number command.

    For information on threading limits, refer to your Administration book.

    CICS Transaction Gateway Desktop Edition: The maximum value for this parameter is 5.


    Initial number of Worker threads

    Enter a number in the range 1 through 1,000,000 to specify the initial number of worker threads. The default is 1.

    You might need to set this number to less than the supported maximum value because of constraints on memory or other system resources. If you enter a value outside the permitted range, the Configuration Tool warns you. If the value entered is too low, it substitutes the minimum. If the value entered is too high, it substitutes the maximum. If a non-numeric value is present in the configuration file, it substitutes the minimum value.

    Set the value to the usual number of concurrent requests expected to be processed concurrently by the Gateway daemon.

    On UNIX and Linux: You can override this setting with the ctgstart -initworker=number command.
    On Windows: You can override this setting with the ctgservice -R -A -initworker=number command.


    Maximum number of Worker threads

    Enter a number in the range 1 through 1,000,000 to specify the maximum number of worker threads.

    The default is 100. You might need to set this number to less than the supported maximum value because of constraints on memory or other system resources. If you enter a value outside the permitted range, the Configuration Tool warns you. If the value entered is too low, it substitutes the minimum. If the value entered is too high, it substitutes the maximum. If a non-numeric value is present in the configuration file, it substitutes the minimum value.

    This value limits the maximum number of JavaGateway objects opened by all connected Client applications. Set it to the maximum number of JavaGateway objects that could be open at any one time from all the remotely connected Client applications.

    If you select the Unrestricted check box, no limits are applied to the number of worker threads. This option is not available on CICS Transaction Gateway Desktop Edition.

    On UNIX and Linux: You can override this setting with the ctgstart -maxworker=number command.
    On Windows: You can override this setting with the ctgservice -R -A -maxworker=number command.

    For information on threading limits, refer to the information center.

    CICS Transaction Gateway Desktop Edition: The maximum value for this parameter is 5.


    Enable reading input from console

    On UNIX and Linux: Select this check box to enable the reading of input from the console. The field is enabled by default.

    See also the -quiet command line option in the CICS Transaction Gateway Administration book for your platform.

    On Windows: Any selection in this field is ignored.


    ECI generic replies

    Enabling generic replies is not supported; the default is that generic replies are not enabled.

    Java client applications can obtain generic ECI replies by using the call type ECI_GET_REPLY or ECI_GET_REPLY_WAIT.

    Select this check box if you want Java Client applications to be able to obtain generic ECI replies.

    Use the call type ECI_GET_SPECIFIC_REPLY or ECI_GET_SPECIFIC_REPLY_WAIT to obtain specific replies.


    Validate Units of Work

    Disabling LUW validation is not supported; the default is that LUW validation is enabled.

    Select this check box if you want CICS Transaction Gateway to validate logical units of work (LUWs).

    This ensures that a LUW ID can be used only on the JavaGateway connection to which it was allocated. If you clear this check box, you disable validation:


    Validate message qualifiers

    Disabling message qualifier validation is not supported; the default is that message qualifier validation is enabled;

    Select this check box if you want CICS Transaction Gateway to validate message qualifiers.

    This ensures that a message qualifier ID can be used only on the JavaGateway connection to which it was allocated. A message qualifier that has been assigned on an asynchronous call cannot be used by any connection using the same remote Gateway until the reply has been received.

    If you clear this check box, you disable validation:


    Timeout for in-progress requests to complete (ms)

    Enter a number in the range 0 through 1,000,000 to specify the value in milliseconds.

    The default timeout is 10,000 milliseconds. If you enter a value outside the permitted range, the Configuration Tool warns you. If the value entered is too low, it substitutes the minimum. If the value entered is too high, it substitutes the maximum. If a non-numeric value is present in the configuration file, it substitutes the minimum value.

    When a Java Client application disconnects from the CICS Transaction Gateway, the Gateway might still be processing requests on behalf of that program.

    1. The connection manager thread that was managing requests on behalf of the Java Client application waits for outstanding requests to complete for up to the timeout period. If this field is set to zero, the connection manager thread moves immediately to step 2.
    2. After the timeout has expired, the connection manager thread closes the protocol handler and returns any worker threads without in-progress requests to the pool.
    3. When all in-progress requests have completed, the connection manager thread returns itself to the pool for reuse.

    Worker thread available timeout (ms)

    Enter a number in the range 0 through 1,000,000 to specify the value in milliseconds.

    If you enter a value outside the permitted range, the Configuration Tool warns you. If the value entered is too low, it substitutes the minimum. If the value entered is too high, it substitutes the maximum. If a non-numeric value is present in the configuration file, it substitutes the minimum value.

    When a connection manager thread accepts a request, it must allocate a worker thread to execute that request. If a worker thread does not become available within the timeout period, an error message is sent rejecting that request and the request is not executed. The default timeout is set to 10 000 milliseconds, but you can enter a value to override that default.

    If you set this value to zero, the request is rejected unless a worker thread is immediately available.


    Port for local administration

    Enter a value in the range 1 through 65,535, to specify the port number on which to listen for administration requests. The default is 2810. If you enter a value outside the permitted range, the Configuration Tool warns you. If the value entered is too low, it substitutes the minimum. If the value entered is too high, it substitutes the maximum. If a non-numeric value is present in the configuration file, it substitutes the minimum value.

    On UNIX and Linux: You can override this setting with the ctgstart -adminport=number command.
    On Windows: You can override this setting with the ctgservice -R -A -adminport=number command.


    Display TCP/IP host names

    Select this check box to enable the display of TCP/IP host names in messages.

    This option allows you to choose how TCP/IP addresses are displayed in messages. By default, CICS Transaction Gateway displays TCP/IP addresses in messages in numeric form. If you enable this option, CICS Transaction Gateway uses the Domain Name System (DNS) to convert numeric TCP/IP addresses to symbolic TCP/IP host names in messages. This conversion makes the messages easier to read.

    Selecting this option might cause severe performance reduction on some systems.


    Log Client connections and disconnections

    Select this check box if you want CICS Transaction Gateway to write a message to the log each time that a Client application connects to, or disconnects from, the Gateway daemon. The default is for these messages not to be written.


    Error and warning log destination

    Select the destination for error and warning messages displayed by the Gateway daemon.

    UNIX and Linux: The Console option sends output to stderr.
    Windows: The File destination must be used.


    Error log file name

    Enter the name of the log file to be used for error and warning messages. The file name must not contain the % (percent) character. Use either a forward slash (/) character or double backslash (\\) characters as a separator in the path name on all platforms.

    For example, on the Windows® operating system:

    C:\\logfiles\\ctg.log
    On UNIX® and Linux® operating systems:
    /var/logs/ctg.log   


    When the filename parameter is defined without a directory the log file is created in the:
    On Windows: "IBM\CICS Transaction Gateway" subdirectory, that exists in the Windows common application data directory.
    On UNIX:
    /opt/IBM/cicstg/bin directory.
    On Linux:
    /opt/ibm/cicstg/bin directory.


    Error log maximum size (KB)

    Specify the maximum size of the log file in kilobytes.

    Enter a value in the range 0 through 2,097,151 to specify the maximum size in kilobytes of the log file. A value of 0 means that no limit is placed on the file size. A value greater than 0 means that the Maximum number of error log files field must be set. The default value is 0. If you enter a value outside the permitted range, the Configuration Tool warns you. If the value entered is too low, it substitutes the minimum. If the value entered is too high, it substitutes the maximum. If a non-numeric value is present in the configuration file, it substitutes the minimum value.


    Maximum number of error log files

    Enter a value in the range 2 through 9999 to specify the maximum number of log files that are maintained. Enter a value of 1 if no maximum size for the error log is specified.

    The default value is 1. If you enter a value outside the permitted range, the Configuration Tool warns you. If the value entered is too low, it substitutes the minimum. If the value entered is too high, it substitutes the maximum. If a non-numeric value is present in the configuration file, it substitutes the minimum value. Any entry in this field is ignored if the Error log maximum size (KB) field has a value of 0, otherwise it must have a minimum value of 2. A value greater than 1 means that the log files will be rotated when the currently active log file reaches or exceeds the file size limit. The file name of the currently active log file is suffixed by '.0' and the rotation process closes this file. The log file with the file name that has a suffix of '.maxfiles-1', is then erased, if it exists, and all the other log files are renamed by adding one to the suffix. Finally, a new log file with suffix '.0' is opened as the new active log file. For example, if you set Error log file name to ctg.log, and the Maximum number of information log files field to 4, at most the following files will be created:

    ctg.log.3  This is the oldest log file. 
    ctg.log.2
    ctg.log.1
    ctg.log.0  This is the log file currently being written to.

    When ctg.log.0 becomes full it is closed. ctg.log.3 is erased. ctg.log.0 becomes ctg.log.1, ctg.log.1 becomes ctg.log.2, ctg.log.2 becomes ctg.log.3, and a new log file ctg.log.0 is opened as the currently active log file. In other words, the smaller the file name suffix the newer the log file.


    Use the same settings for error and information logs

    Select this check box if you want the information log to be sent to the same destination as the error and warning log.


    Information log destination

    Select the destination for information messages output by the Gateway daemon.

    On UNIX and Linux: The Console option sends output to stdout.
    On Windows: The File destination must be used.


    Information log file name

    Enter the name of the log file to be used for information messages. The file name cannot contain the % (percent) character. Use either a forward slash (/) character, or double backslash (\\) characters, as a separator in the path name on all platforms.

    For example, on the Windows® operating system:

    C:\\logfiles\\ctg_info.log

    On UNIX® and Linux® operating systems:

    /var/logs/ctg_info.log       


    When the filename parameter is defined without a directory the log file is created in the:
    On Windows: "IBM\CICS Transaction Gateway" subdirectory, that exists in the Windows common application data directory.
    On UNIX:
    /opt/IBM/cicstg/bin directory.
    On Linux:
    /opt/ibm/cicstg/bin directory.


    Information log maximum size (KB)

    Enter a value in the range 0 through 2,097,151 to specify the maximum size in kilobytes of the log file.

    A value of 0 means that no limit is placed on the file size. A value greater than 0 means that the Maximum number of information log files field must be set. The default value is 0. If you enter a value outside the permitted range, the Configuration Tool warns you. If the value entered is too low, it substitutes the minimum. If the value entered is too high, it substitutes the maximum. If a non-numeric value is present in the configuration file, it substitutes the minimum value.


    Maximum number of information log files

    Enter a value in the range 2 through 9999 to specify the maximum number of log files that are maintained. Enter a value of 1 if no maximum size for the information log is specified.

    The default value is 1. If you enter a value outside the permitted range, the Configuration Tool warns you. If the value entered is too low, it substitutes the minimum. If the value entered is too high, it substitutes the maximum. If a non-numeric value is present in the configuration file, it substitutes the minimum value. Any entry in this field is ignored if the Information log maximum size (KB) field has a value of 0, otherwise it must have a minimum value of 2. A value greater than 1 results in the file name of the log file being suffixed by sequence numbers until the number of files specified in maxfiles have been created. For example, if you set Information log file name to ctg.log, and the Maximum number of information log files field to 4, at most the following files will be created:

    ctg.log.3  This is the oldest log file. 
    ctg.log.2
    ctg.log.1
    ctg.log.0  This is the log file currently being written to.

    In other words, the smaller the filename suffix the newer the log file.


    Statistics Interval (HHMMSS)


    This value determines how often statistics monitoring data is sent to the statistics API.

    Enter a number between 1 minute and 24 hours, including seconds granularity. The field requires the interval to be specified in the format HHMMSS, and will only accept interval times within the specified range. If a value is loaded or entered that is in error, or outside of this range then an error message will be displayed. If the value entered is parsable then the value is changed to the minimum (when value too low) or maximum (when value too high). If the value is not parsable it is set to the default which is 3 hours (030000), and will also be used if the field is left blank.


    Statistics End of Day time (HHMMSS)

    Enter a number between 000000 and 235959 to define the CICS Transaction Gateway End of Day time, in local time.

    Values can range between midnight (000000) and 1 second before midnight (235959). The field requires the interval to be specified in the format HHMMSS, and will accept interval time only within the specified range. If a value is loaded or entered that is in error, or outside of this range then an error message will be displayed . If the value entered is parsable then the value is changed to the minimum (when value too low) or maximum (when value too high). If the value is not parsable it is set to the default which is midnight (000000), and will be also used if the field is left blank.

    The End of Day time is used as a point of reference for the clock. Intervals are aligned to this rather than to the CICS Transaction Gateway startup time. This also determines the point at which statistics will be reset and potentially recorded, and occurs at least once every 24 hours.


    Use these request monitors

    Enter a valid class name for a request monitor class.

    The value must be for a class that implements the com.ibm.ctg.monitoring.RequestExit interface and must be on the class path of the Gateway daemon. Select Add to add the request monitor class name to the list, below the entry field. Select Remove to remove all selected entries in the list.


    [ Top of Page | Previous Page | Next Page | Table of Contents | Index ]

    (C)Copyright IBM Corporation, 1999, 2010. All rights reserved. Legal