CICS Transaction Gateway for z/OS

https://www.ibm.com/docs/en/cics-tg-zos/10.1.0
Admin
CICS Transaction Gateway for z/OS is an IBM middleware solution that enables communication and...
Tokens:242,322
Snippets:2,605
Trust Score:10
Update:10 months ago
Show doc for...
Tokens:
Raw
### Otel .NET SDK Configuration and Exporter Setup

Source: https://www.ibm.com/docs/en/cics-tg-zos/10.1.0/index_topic=opentelemetry-client-instrumentation-using

This example illustrates how to configure the OpenTelemetry .NET SDK, including setting a service name, configuring resources, and adding a console exporter. This setup is essential for collecting and viewing telemetry data from .NET applications.

```csharp
var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddSource(serviceName)
    .ConfigureResource(resource =>
        resource.AddService(
          serviceName: serviceName,
          serviceVersion: serviceVersion))
    .AddConsoleExporter()
    .Build();
```

--------------------------------

### Manual Instrumentation Example for Java OTel Clients

Source: https://www.ibm.com/docs/en/cics-tg-zos/10.1.0/index_topic=opentelemetry-client-instrumentation-using

This snippet demonstrates manual instrumentation using the OpenTelemetry API for Java clients. It shows how to obtain a tracer and start a new span, which is fundamental for recording specific operations within an application.

```java
Tracer tracer = GlobalOpenTelemetry.getTracer("/"); 
Span span = tracer.spanBuilder("Span 1").startSpan(); 
span.makeCurrent();
```

--------------------------------

### Access ECIIVT Web Page for Installation Verification

Source: https://www.ibm.com/docs/en/cics-tg-zos/10.1.0/index_topic=sc07-testing-ssl-scenario

This URL is used to access the ECI resource adapter installation verification test page. It requires a web browser and is typically accessed locally.

```url
http://localhost:9080/ECIIVTWeb/index.jsp
```

--------------------------------

### Parameter Line Continuation Example

Source: https://www.ibm.com/docs/en/cics-tg-zos/10.1.0/index_topic=assistant-creating-restful-wsbind-file

Demonstrates how to use a backslash (\) to continue a parameter across multiple lines. Ensures that the entire parameter, including spaces before the backslash, is considered part of the parameter. This is crucial for long parameter values.

```JCL
WSBIND=wsbinddir\
/app1
```

--------------------------------

### Java Stack Dump Example (JIT Disabled)

Source: https://www.ibm.com/docs/en/cics-tg-zos/10.1.0/index_topic=problems-failure-handle-java-exception

This snippet shows an example of a Java stack dump produced when the Just-In-Time (JIT) compiler is disabled. This configuration can provide more detailed information, potentially including the specific line of Java source code where an exception occurred.

```java
Exception in thread "main" java.lang.OutOfMemoryError
        at java.lang.Thread.start(Native Method)
        at com.ibm.ctg.server.ThreadManager.createObject
           (ThreadManager.java:345)
        at com.ibm.ctg.server.ThreadManager.<init>(ThreadManager.java:131)
        at com.ibm.ctg.server.ManagedResources.<init>
           (ManagedResources.java:106)
        at  com.ibm.ctg.server.JGate.main(JGate.java:895)

```

--------------------------------

### Client Application Trace Logging Example

Source: https://www.ibm.com/docs/en/cics-tg-zos/10.1.0/index_topic=trackingtoken-tracking-token-in-client-application-trace

This snippet displays an example of a client application trace log showing the generation and usage of a Tracking Token. It highlights the token's format and its inclusion in system messages. No specific dependencies are mentioned, and the output is a textual log.

```text
[8/30/19 14:57:29:852 IST] 000000a5 SystemErr     R   14:57:29:852 WebContainer : 4: 
TokenGenerator:<- [generateTrackingToken()] = 
CTG148910238193OW2HF2ZQC1GLUJJ85P1T8GND6A6283EBE260300
[8/30/19 14:57:29:852 IST] 000000a5 SystemErr     R   14:57:29:852 WebContainer : 4: JavaGateway: 
+ StakeHolderId Z for RequesExit com.ibm.ctg.samples.requestexit.BasicMonitorfield@12e9322f
[8/30/19 14:57:29:852 IST] 000000a5 SystemErr     R   14:57:29:852 WebContainer : 4: ECIRequest:-> 
[settrackingToken] (CTG148910238193OW2HF2ZQC1GLUJJ85P1T8GND6A6283EBE26030011Z)

```

--------------------------------

### CICS System Log Messages for IPCONN Installation

Source: https://www.ibm.com/docs/en/cics-tg-zos/10.1.0/index_topic=sc08-optional-using-applid-identify-your-cics-tg

These messages from the CICS system log indicate the successful installation of an IPCONN. They show the client's APPLID (e.g., MYQUAL.MYAPPL), the autoinstall user program used, and the template. The second message confirms that a client session from the specified APPLID has been accepted for the IPCONN.

```log
DFHIS3000 .... IPCONN APPL with applid MYQUAL.MYAPPL 
autoinstalled successfully using autoinstall user program DFHISAIP 
and template NONE after a connection request was received on 
tcpipservice SRV50889 from host 1.23.456.789

DFHIS2001 .... Client session from applid MYAPPL accepted for IPCONN 
APPL.
```

--------------------------------

### CICS System Log Messages for IPCONN Installation

Source: https://www.ibm.com/docs/en/cics-tg-zos/10.1.0/index_topic=sc01-optional-using-applid-identify-your-cics-tg

These are example CICS system log messages that appear when an IPCONN is automatically installed after a connection request. They indicate the successful installation of an IPCONN with a specific APPLID and APPLIDQUALIFIER, and the client session acceptance.

```LOG
DFHIS3000 .... IY2GTGA2 IPCONN APPL with applid MYQUAL.MYAPPL 
autoinstalled successfully using autoinstall user program DFHISCIP 
and template SECTEMPL after a connection request was received on 
tcpipservice SRV50889 from host 1.23.456.789

DFHIS2001 .... IY2GTGA2 Client session from applid MYAPPL accepted for IPCONN 
APPL.
```

--------------------------------

### Build SDK Sample on UNIX/Linux

Source: https://www.ibm.com/docs/en/cics-tg-zos/10.1.0/index_topic=samples-c-ctgesib1-sample

Builds the 64-bit ctgesib1 sample program from the SDK directory on UNIX and Linux systems. Requires specifying the target OS with the OS=<platform> argument.

```shell
make -f make64 OS=<platform>
```

--------------------------------

### Set CICSCLI for USS Configuration File

Source: https://www.ibm.com/docs/en/cics-tg-zos/10.1.0/index_topic=configuring-remote-mode-topology

This example demonstrates how to set the CICSCLI environment variable to specify the path to a configuration file (ctg.ini) on the USS file system. This allows for custom locations outside of the default product installation directory.

```shell
CICSCLI=/u/userid/myconfig.ini
```

--------------------------------

### Build C Sample on UNIX/Linux

Source: https://www.ibm.com/docs/en/cics-tg-zos/10.1.0/index_topic=samples-c-ctgesib1-sample

Builds the 64-bit ctgesib1 sample program on UNIX and Linux systems using the standard make command. This command assumes a default compiler setup.

```shell
make -f samp64.mak
```

--------------------------------

### MVS PDS Member Continuation Example

Source: https://www.ibm.com/docs/en/cics-tg-zos/10.1.0/index_topic=assistant-creating-restful-wsbind-file

Illustrates how to continue an MVS PDS member or sequential data set value across lines, specifically for the LS-RESTFUL parameter. It shows how to avoid JCL errors by ensuring '//' does not start in column 1 on continuation lines.

```JCL
LS-RESTFUL=\
//'USERID.PROJECT.COBOL(RESTFUL)'
```

--------------------------------

### Sample Configuration for Transaction Monitoring (MVS Dataset)

Source: https://www.ibm.com/docs/en/cics-tg-zos/10.1.0/index_topic=monitoring-configuring-transaction

Example illustrating the configuration for transaction monitoring to log messages to an MVS dataset. This setup uses CH51LevelThreeMonitor and specifies the MVS dataset name and logging level.

```text
requestexits=com.ibm.ctg.ch51.requestexit.CH51LevelThreeMonitor
ch51@file.parameters = filename=//’XX.YY.ZZ’;level=2;
```

--------------------------------

### Build SDK Sample on Windows

Source: https://www.ibm.com/docs/en/cics-tg-zos/10.1.0/index_topic=samples-c-ctgesib1-sample

Builds the 64-bit ctgesib1 sample program from the SDK directory on Windows systems. This command is a simplified make invocation for the Windows environment.

```shell
make 64
```

--------------------------------

### Build SDK Sample on Linux/POWER with XL C

Source: https://www.ibm.com/docs/en/cics-tg-zos/10.1.0/index_topic=samples-c-ctgesib1-sample

Builds the 64-bit ctgesib1 sample program from the SDK directory on Linux on POWER systems using IBM XL C. The OS=<platform> and COMPILER=XL flags are used.

```shell
make -f make64 OS=<platform> COMPILER=XL
```

--------------------------------

### Example of LESS-DUP-NAMES Override in PL/I

Source: https://www.ibm.com/docs/en/cics-tg-zos/10.1.0/index_topic=assistant-creating-restful-wsbind-file

Demonstrates how the `LESS-DUP-NAMES` option in `MAPPING-OVERRIDES` modifies PL/I language structure field names. The example shows `streetName` being suffixed with `_value` when this option is enabled, facilitating direct field referencing.

```text
09 streetName,
    12 streetName                     CHAR(255) VARYING
   UNALIGNED,
    12 filler                         BIT (7),
    12 attr_nil_streetName_value      BIT (1),

```

```text
09 streetName,
    12 streetName_value               CHAR(255) VARYING
   UNALIGNED,
    12 filler                         BIT (7),
    12 attr_nil_streetName_value      BIT (1),

```

--------------------------------

### Build C Sample on Windows

Source: https://www.ibm.com/docs/en/cics-tg-zos/10.1.0/index_topic=samples-c-ctgesib1-sample

Builds the 64-bit ctgesib1 sample program on Windows systems using a provided batch script. The '64' argument specifies the 64-bit version.

```batch
ctgesib1mak.cmd 64
```

--------------------------------

### List and Verify Java Keystore Contents using keytool

Source: https://www.ibm.com/docs/en/cics-tg-zos/10.1.0/index_topic=sc14-preparing-java-client-ssl

This command lists the contents of a Java keystore with verbose output, allowing verification of certificate details. It requires the keystore file name. The `-v` option provides detailed information about the certificates within the keystore.

```shell
keytool -list -keystore clientKey.jks -v
```

--------------------------------

### Example JSON Response Data for EC03 Transaction

Source: https://www.ibm.com/docs/en/cics-tg-zos/10.1.0/index_topic=sc11-producing-client-application-from-json-schema

This example demonstrates the expected format of the JSON response payload from the EC03 CICS transaction. It adheres to the structure defined by the ec03resp.json schema.

```json
{
   "EC03OperationResponse":
   {
      "CICSDATETIME": "18/03/2014 13:13:35",
      "OUTPUTMESSAGE": "Input data was: testing data",
      "INPUTDATALENGTH":
      {
          "inputlength": 12
      }
   }
}
```

--------------------------------

### Java EciB2 Sample Usage and Execution

Source: https://www.ibm.com/docs/en/cics-tg-zos/10.1.0/index_topic=samples-java-ecib2-sample

Demonstrates the command-line syntax for the Java EciB2 sample, showing how to specify various parameters like gateway URL, security settings, CICS server details, user credentials, program names, and COMMAREA options. It also includes a full execution example with output.

```shell
java com.ibm.ctg.samples.eci.EciB2  [jgate=gateway_URL]
                                      [jgateport=gateway_port]
                                      [clientsecurity=client_security_class]
                                      [serversecurity=server_security_class]
                                      [server=cics_server_name or IPIC_url]
                                      [userid=cics_userid]
                                      [password=cics_password]
                                      [prog<0..9>=prog_name]
                                      [commarea=comm_area]
                                      [commarealength=comm_area_length]
                                      [status]
                                      [trace]
                                      [ascii | ebcdic | asis]
```

```shell
C:\>java com.ibm.ctg.samples.eci.EciB2 jgate=localhost jgateport=2006 prog0=EC04
 server=CICSIPIC commarealength=122 ebcdic

CICS Transaction Gateway Basic ECI Sample 2

 Test Parameters
CICS TG address : localhost:2006
Client security : null
Server security : null
CICS Server     : CICSIPIC
UserId          : null
Password        : null
Data Conversion : IBM037

COMMAREA        : null
COMMAREA length : 122

Number of programs given : 1
  [0] : EC04

Connect to Gateway

Successfully created JavaGateway

Call Programs

About to call : EC04
  COMMAREA    :
  extend_mode : 0
  LUW_token   : 0
  Commarea    : date=05/05/15,time=10:21:45,applid=myapplid,version=CICS TS  5.3
,userid=CICSUSER,mirror=CPMI,transid=CPMI,protocol=IPIC
Return code   : ECI_NO_ERROR(0)
Abend code    : null
Successfully closed JavaGateway

C:\>
```

--------------------------------

### Install TCPIPSERVICE Definition in CICS

Source: https://www.ibm.com/docs/en/cics-tg-zos/10.1.0/index_topic=ipic-configuring-cics-transaction-server-zos

Installs a previously defined TCPIPSERVICE resource into the CICS system using the CEDA command. This makes the listener active and ready to accept connections.

```CICS CL
CEDA INS TCPIPSERVICE(service-name) GROUP(group-name)
```

--------------------------------

### HTTP-METHODS Parameter

Source: https://www.ibm.com/docs/en/cics-tg-zos/10.1.0/index_topic=assistant-creating-restful-wsbind-file

Configures the accepted HTTP methods for JSON web services. Defaults to GET, POST, PUT, DELETE. Explicitly specifying methods restricts accepted operations. Supports any combination of GET, POST, PUT, DELETE, HEAD.

```APIDOC
## HTTP-METHODS Parameter

### Description
This is an optional parameter. The default value is for GET, POST, PUT, and DELETE to be set, which tells JSON web services assistant that the application supports the four main RESTful operations. If a value is provided, JSON web services assistant builds a WSBind file in which only the explicitly specified HTTP methods are accepted.

### Method
Not Applicable (Configuration Parameter)

### Endpoint
Not Applicable (Configuration Parameter)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```
HTTP-METHODS={GET|POST|PUT|DELETE|HEAD},{GET|POST|PUT|DELETE|HEAD},*
```

### Response
#### Success Response (200)
Not Applicable (Configuration Parameter)

#### Response Example
Not Applicable (Configuration Parameter)
```

--------------------------------

### Import Certificate to Java Keystore using keytool

Source: https://www.ibm.com/docs/en/cics-tg-zos/10.1.0/index_topic=sc14-preparing-java-client-ssl

This command imports a personal certificate into a Java keystore. It requires the keystore file name and the certificate file name. The user will be prompted to trust the certificate and set a password.

```shell
keytool -import -keystore clientKey.jks -file CTGUSER.ICSF.PERSONAL
```

--------------------------------

### RESOLVER_CONFIG JCL Example (HFS File)

Source: https://www.ibm.com/docs/en/cics-tg-zos/10.1.0/index_topic=variables-environment-remote-mode

Shows how to set the RESOLVER_CONFIG environment variable in CTGJOB JCL to specify a z/OS UNIX file for TCPIP.DATA information. This example uses the path /etc/resolv.conf_new.

```JCL
//CTG      EXEC PGM=CTGBATCH,
//         PARM=('ENVAR("RESOLVER_CONFIG=/etc/resolv.conf_new")',
//         '&LEOPTS.&CTGHOME./bin/ctgstart -noinput ')
//STEPLIB  DD DSN=&CTGHLQ..SCTGLOAD,DISP=SHR
//STDOUT   DD SYSOUT=*
//STDERR   DD SYSOUT=*
//STDENV   DD DSN=&CTGUSR.,DISP=SHR
//* Define CTGDBG DD DUMMY to enable CTGBATCH debug mode    
//CTGDBG   DD DUMMY
```

--------------------------------

### Set CLASSPATH for Sample Programs (Shell)

Source: https://www.ibm.com/docs/en/cics-tg-zos/10.1.0/index_topic=samples-running-sample-programs

This snippet shows how to set the CLASSPATH environment variable to include the necessary JAR files for running sample programs. It is essential for both local and server modes, with ctgserver.jar being specific to local mode. Ensure `<install_path>` is replaced with your actual installation directory.

```shell
CLASSPATH=<install_path>/classes/ctgsamples.jar \
:<install_path>/classes/ctgclient.jar \
:<install_path>/classes/ctgserver.jar
```

--------------------------------

### RESOLVER_CONFIG JCL Example (MVS Dataset)

Source: https://www.ibm.com/docs/en/cics-tg-zos/10.1.0/index_topic=variables-environment-remote-mode

Demonstrates setting the RESOLVER_CONFIG environment variable in CTGJOB JCL to specify an MVS data set for TCPIP.DATA information. This example points to SYS1.TCPPARMS(TCPIP1LB).

```JCL
//CTG      EXEC PGM=CTGBATCH,
//         PARM=('ENVAR("RESOLVER_CONFIG=//'SYS1.TCPPARMS(TCPIP1LB)'")',
//         '&LEOPTS.&CTGHOME./bin/ctgstart -noinput ')
//STEPLIB  DD DSN=&CTGHLQ..SCTGLOAD,DISP=SHR
//STDOUT   DD SYSOUT=*
//STDERR   DD SYSOUT=*
//STDENV   DD DSN=&CTGUSR.,DISP=SHR
//* Define CTGDBG DD DUMMY to enable CTGBATCH debug mode    
//CTGDBG   DD DUMMY
```

--------------------------------

### Example Command: Run CTGStat1 for SSL Statistics

Source: https://www.ibm.com/docs/en/cics-tg-zos/10.1.0/index_topic=samples-java-ctgstat1-statistics-api-sample

This command executes the precompiled Ctgstat1 Java sample to connect to the SSL statistics API port of a Gateway daemon. It specifies the host, port, SSL keyring file, and password for secure connection.

```shell
java com.ibm.ctg.samples.stats.Ctgstat1 ssl://localhost.com 2090 clientKeyring.jks password
```

--------------------------------

### Build C Sample on Linux/POWER with XL C

Source: https://www.ibm.com/docs/en/cics-tg-zos/10.1.0/index_topic=samples-c-ctgesib1-sample

Builds the 64-bit ctgesib1 sample program on Linux on POWER systems specifically using the IBM XL C compiler. The COMPILER=XL flag directs the build process.

```shell
make -f samp64.mak COMPILER=XL
```

--------------------------------

### TZ Time Zone Configuration Example

Source: https://www.ibm.com/docs/en/cics-tg-zos/10.1.0/index_topic=variables-environment-remote-mode

Specifies the local time zone and daylight saving time. The format is similar to the TZ setting in /etc/profile. Examples are provided for the United Kingdom and United States Eastern Standard Time.

```shell
TZ=standardHH[:MM[:SS]] [daylight[HH[:MM[:SS:]]]
[,startdate[/starttime],enddate[/endtime]]]
```

```shell
TZ=GMT0BST,M3.5.0,M10.4.0
```

```shell
TZ=EST5EDT
```

--------------------------------

### Example: Run Application with Multiple Monitor Exits

Source: https://www.ibm.com/docs/en/cics-tg-zos/10.1.0/index_topic=statistics-configuring-request-monitoring-gateway-classes

An example of executing a Java application with two request monitoring exits, 'BasicMonitor' and 'ThreadedMonitor'. The JVM property 'requestExits' is set to include both classes, separated by a comma, enabling chained monitoring.

```shell
java -DrequestExits=com.ibm.ctg.samples.requestexit.BasicMonitor,com.ibm.ctg.samples.requestexit.ThreadedMonitor com.ibm.ctg.samples.eci.EciB1
```
Tokens:
Raw