ctgservice command reference

You can use the ctgservice command on Windows to set Gateway daemon override parameters and to grant or deny start and stop authority on the IBM® CICS® Transaction Gateway service.

Setting Gateway daemon override parameters or defining start and stop authority requires that the ctgservice command is run by an administrator. Using ctgservice from a command prompt does not start the IBM CICS Transaction Gateway service.

The IBM CICS Transaction Gateway service is created with a default security descriptor. The access rights of the default security descriptor are defined by the Windows service control manager, for more information refer to your Windows documentation. You can use the ctgservice command to modify the default access rights to give users or groups the authority to start and stop the IBM CICS Transaction Gateway service.

The ctgservice command sets the Gateway daemon override parameters to be used when the IBM CICS Transaction Gateway service is started. These override parameters override the Gateway daemon parameter values specified in the configuration file. The override parameters are validated when the service is started and not when they are set by the ctgservice command. The ctgservice command uses the JVM specified by the ctgjava command. For more information, refer to Specifying the JVM.

The syntax of the ctgservice command is:
ctgservice -?|-T|-G Name|-D Name|-R [-ACTGParam1 [-ACTGParam2] [-A-jArgument]...]
where:
-?
Displays the command syntax and the list of options that can be used with ctgservice.
-T
Displays the registered parameter overrides and the users and groups that can start and stop the service.
-G <Name>
Grants a user or group the authority to start and stop the IBM CICS Transaction Gateway service, by allowing access rights: SERVICE_QUERY_CONFIG, SERVICE_QUERY_STATUS, SERVICE_START and SERVICE_STOP. If the name includes spaces, then it must be enclosed in quotes.
-D <Name>
Denies a user or group the authority to start and stop the IBM CICS Transaction Gateway service, by denying access rights: SERVICE_START and SERVICE_STOP. If the name includes spaces, then it must be enclosed in quotes.
-R
Registers the override parameters to be used when starting the Gateway daemon. The -R option resets the registered override parameters. If you use ctgservice -R with no following options, all override parameters are removed. To define override parameters for the Gateway daemon the -A<override> option must be used with the -R option.
-A<override>
Specifies a startup override parameter for the Gateway daemon or an argument for the Gateway daemon JVM. The -A<override> option must be used with the -R option.
Note: The -G and -D parameters can only be specified by a user with administrator authority. These parameters update the Access Control List (ACL) for the CICS TG service. A user or group is granted or denied permission to start and stop the CICS TG service. The -T parameter has been updated to list the access control list entries that are associated with the CICS TG service.

For example:
  • To grant "Power Users" the authority to start and stop the IBM CICS Transaction Gateway service:
    ctgservice -G "Power Users"
  • To deny the "Guests" group from starting and stopping the IBM CICS Transaction Gateway service.
    ctgservice -D Guests
  • To set override parameters for the Gateway daemon.
    ctgservice -R -A-x -A-tfile=C:\temp\ctgtrace.txt -A-j-Dgateway.T.setJNITFile=C:\temp\ctgJNItrace.txt

The following Gateway daemon overrides are available to be set using the -R option

Override parameter Description
-port=number Specifies the TCP/IP port number on which the Gateway daemon will listen.
-httpport=port number Specifies the TCP/IP port on which the Gateway daemon listens for HTTP requests.
-httpsport=port number Specifies the TCP/IP port on which the Gateway daemon listens for HTTPS requests.
-sslport=number Specifies the TCP/IP port number on which the Gateway daemon will listen for SSL requests.
-keyring=file Specifies the SSL key ring path and file name.
-keyringpw=password Specifies the SSL key ring password. An error message is generated if the keyringpw parameter is used on its own without the corresponding keyring parameter in the ctgstart command on Unix, or the ctgservice- command line.
-adminport=number Specifies the port used to communicate with the Gateway daemon when controlling the Gateway daemon through the ctgadmin command on Unix or the ctgservice command on Windows.
-statsport=number Specifies the TCP/IP port number on which the Gateway daemon will listen for statistics API requests.
-initconnect=number Specifies an initial number of connection manager threads. See Tuning the Gateway for performance information.
-maxconnect=number Specifies a maximum number of connection manager threads. If you set this value to -1, no limits are applied to the number of connection manager threads. See Tuning the Gateway for performance information.
-initworker=number Specifies an initial number of worker threads. See Tuning the Gateway for performance information.
-maxworker=number Specifies a maximum number of worker threads. If you set this value to -1, no limits are applied to the number of connection manager threads. See Tuning the Gateway for performance information.
-trace Enables standard tracing (see Tracing). By default, the trace output shows only the first 128 bytes of any data blocks (for example the COMMAREA, or network flows). Other useful information, including the value of the CLASSPATH variable, and the code page, is shown at the top of the trace output.

Trace output is written to stderr, unless you use the -tfile option, or have used the Configuration Tool to define a default trace destination. No trace is written if the Gateway daemon does not have permission to write to the specified file. Each time the Gateway daemon is started with trace enabled, the trace file is overwritten with the new trace.

-quiet Disables the reading of input from the console and disables writing to stdout.
-dnsnames Enables the display of symbolic TCP/IP host names in messages. See Display TCP/IP host names for more information.
-tfile=pathname If tracing is enabled, trace output is written to the file specified in pathname. This option overrides the default destination for trace output (see the -trace option).
-x Enables full debug tracing (see Tracing). By default, the trace output shows the whole of any data blocks (for example the COMMAREA, or network flows). It also displays more information about the internal Gateway daemon processing than the standard trace. See the -trace and -tfile options for information on the destination for trace output.

Debug tracing significantly decreases performance.

-tfilesize=number Specifies the maximum size, in kilobytes, of the trace output file.
-truncationsize=number The value number specifies the maximum size of any data blocks that are shown in the trace. You can use this option with either the -trace or -x options to override the default size. Any positive integer is valid. If you specify a value of 0, no data blocks are shown in the trace.
-dumpoffset=number The value number specifies the offset from which displays of any data blocks start. If the offset is greater than the total length of data to be displayed, an offset of 0 is used.
-stack Enables Java™ exception stack tracing (see Tracing). Java exceptions are traced, including those expected during typical operation. Expected exceptions include:
  • An IOException resulting from a Java Client application ending or disconnecting from a network protocol.
  • An InterruptedException resulting from a CICS Transaction Gateway protocol handler timeout such as the idle timeout, or a ping timeout.
No other trace output is created. See the -trace and -tfile options for information on the destination for trace output.
-j Passes an argument to the JVM. For example, -j-D<name>=<value> sets a JVM system property. See the JVM command line interpreter help for guidance in using this option. On Windows, this option replaces the -X option used in earlier versions of the CICS Transaction Gateway. You can pass multiple arguments to the JVM. Specify the -j option multiple times to pass multiple arguments to the JVM.
-classpath=class path Specifies additional entries to append to JVM class path that are used when launching the JVM. For example, the location of a jar file containing request exits.
-requestExits=exits List of classes to be used for request exit monitoring.