Initial Configuration of the CICS Runtime

2 Initial Configuration of the CICS Runtime

This chapter contains the following topics:

2.1 CICS Runtime Configuration

Before installing a CICS application, certain technical variables and paths must be defined in order to create the CICS Runtime environment.

These operations must be completed before configuring individual CICS applications for use with CICS Runtime.

CICS Runtime uses the following files:

The UNIX System ~/.profile file to centralize values and paths used by the CICS Runtime for its own needs or for Tuxedo.
The Tuxedo envfile which contains parameters, variables and paths used by Tuxedo.
The Tuxedo ubbconfig file to declare all the required CICS Runtime Tuxedo servers.
The CICS Runtime resource configuration files used by the CICS Runtime Tuxedo servers

The details about configuring the runtime environment are described in the following topics:

Parent topic: Initial Configuration of the CICS Runtime

2.1.1 The UNIX ~/.profile File

For UNIX users, most required variables are defined in the .profile file that centralizes all of the common variables and paths used by a user for commands and applications.

Set up in this file all of the common variables and paths that will be used later in the different configuration files required by CICS Runtime or by the other technical software or middleware invoked by it (Oracle, Tuxedo, MQ Series …).

This file should then be exported.

Set the following variables in the initial settings of ~/.profile file.

Table 2-1 .profile Variables

Variable	Value	Usage	Variable usage
`TUXDIR`	Set up at Installation time	Compulsory. Directory containing the Installed Oracle Tuxedo product.	TUXEDO
`TUXCONFIG`	Set up at Installation time	Compulsory. Full path name of the Tuxedo tuxconfig file	TUXEDO
`KIXDIR`	Set up at Installation time	Compulsory. Absolute path of the directory containing the CICS Runtime product	CICS Runtime
`APPDIR`	`${KIXDIR}/bin`	Compulsory. Directory containing the CICS Runtime Servers Binaries	CICS Runtime
`KIXCONFIG`	Set up at Installation time	Compulsory. Directory where the Resources Configuration Files of the CICS Runtime are located	CICS Runtime
`KIX_TS_DIR`	Set up at Installation time	Compulsory. Directory used for the non-recoverable CICS Queue TS.	CICS Runtime

Listing 2‑1 .profile file Initial Settings Example

export TUXDIR=/product/TUXEDO11GR1 # Directory containing the Installed Tuxedo product

export TUXCONFIG=${HOME}/SIMAPP/config/tux/tuxconfig # Full path name of the Tuxedo tuxconfig file

export KIXDIR=${HOME}/KIXEDO # Absolute path of the CICS Runtime product directory

export APPDIR=${KIXDIR}/bin # Directory containing the CICS Runtime Servers Binaries

export KIXCONFIG=${HOME}/SIMAPP/config/resources # Directory for resources files (*.desc)

export KIX_TS_DIR=${HOME}/SIMAPP/KIXTSDIR # Directory for TS no recovery

Table 2-2 envfile Variables

Variable	Value	Usage
`LC_MESSAGES`	`C`	UNIX formats of informative and diagnostic messages
`OBJECT_MODE`	`64`	UNIX 64 bits architecture
`APPDIR`	`${APPDIR}`	TUXEDO environment.
`TUXCONFIG`	`${TUXCONFIG}`	TUXEDO environment
`USER_TRACE`	`SID`	TUXEDO environment. Trace Type (one per user)
`KIXCONFIG`	`${KIXCONFIG}`	CICS Runtime directory containing its resource files
`PATHTS`	`${KIX_TS_DIR}`	CICS Runtime directory used for the unrecoverable Temporary Storage

Listing 2‑2 envfile Initial Settings Example

# <TUXDIR>
# Refers to the location where you installed TUXEDO. The default
# location is "/usr/tuxedo".
#
# <APPDIR>
# Refers to the fully qualified directory name where your application
# runs (i.e., the location of the libraries, mapdefs, and MIB files).
#
# <TUXCONFIG>
# Refers to the fully qualified binary version of the TUXEDO
# configuration file. (This is usually the "tuxconfig" in the $APPDIR
# directory.)
#
#--------------------------------------------------------------------------
# TUXEDO environment
APPDIR=${KIXDIR}/bin
CONFDIR=${APPHOME}/config/tux
TUXCONFIG=${CONFDIR}/tuxconfig
FLDTBLDIR32=${KIXDIR}/src
FIELDTBLS32=msgflds32
OBJECT_MODE=64
 
#resource files directory
KIXCONFIG=${APPHOME}/config/resources
 
# Command executable paths
HAB_TRAN=none
 
# Other environment
LC_MESSAGES=C
 
# End

Parent topic: CICS Runtime Configuration

2.1.2 The Tuxedo System Files

This section contains the following topics:

Parent topic: CICS Runtime Configuration

2.1.2.1 The Tuxedo Envfile File

This envfile contains variables and paths used by Tuxedo and CICS Runtime. These parameters should be set in addition to those set by the Tuxedo Administrator.

Set the following variables in the initial settings of the envfile file:

Table 2-3 envfile Variables

Variable	Value	Usage
`LC_MESSAGES`	`C`	UNIX formats of informative and diagnostic messages
`OBJECT_MODE`	`64`	UNIX 64 bits architecture
`APPDIR`	`${APPDIR}`	TUXEDO environment.
`TUXCONFIG`	`${APPDIR}`	TUXEDO environment
`USER_TRACE`	`SID`	TUXEDO environment. Trace Type (one per user)
`KIXCONFIG`	`${KIXCONFIG}`	CICS Runtime directory containing its resource files
`PATHTS`	`${KIX_TS_DIR}`	CICS Runtime directory used for the unrecoverable Temporary Storage

Listing 2‑2 envfile Initial Settings Example

# <TUXDIR>
# Refers to the location where you installed TUXEDO. The default
# location is "/usr/tuxedo".
#
# <APPDIR>
# Refers to the fully qualified directory name where your application
# runs (i.e., the location of the libraries, mapdefs, and MIB files).
#
# <TUXCONFIG>
# Refers to the fully qualified binary version of the TUXEDO
# configuration file. (This is usually the "tuxconfig" in the $APPDIR
# directory.)
#
#--------------------------------------------------------------------------
# TUXEDO environment
APPDIR=${KIXDIR}/bin
CONFDIR=${APPHOME}/config/tux
TUXCONFIG=${CONFDIR}/tuxconfig
FLDTBLDIR32=${KIXDIR}/src
FIELDTBLS32=msgflds32
OBJECT_MODE=64
 
#resource files directory
KIXCONFIG=${APPHOME}/config/resources
 
# Command executable paths
HAB_TRAN=none
 
# Other environment
LC_MESSAGES=C
 
# End

Parent topic: The Tuxedo System Files

2.1.2.2 The Tuxedo ubbconfig File

The following initial configuration of CICS Runtime is configured for typical user scenario using 3270s clients oriented transactions. Some CICS Runtime Tuxedo servers are absolutely needed while others can be optionally started and are not absolutely necessary at this time.

Parent topic: The Tuxedo System Files

2.1.2.2.1 The Mandatory Servers

These servers must be started to run CICS Runtime and verify that the initial settings are correct by being able to display the CICS Runtime Good Morning screen (Host Connection Welcome Screen).

The Terminal Control Program Listener (ARTTCPL server) is needed because it establishes communication between end-users and CICS Runtime applications thru maps displayed on 3270 terminals or emulators.
The Connection Server (ARTCNX server) is also required because it offers technical connections services during the user connection and disconnection phases. It is also used to display the CICS system transactions CICS Runtime Good Morning screen thru the System Transaction CSGM.
The Administration Server (ARTADM server) is needed to replicate resources files for all other servers.

Parent topic: The Tuxedo ubbconfig File

2.1.2.2.2 The Optional Servers

These servers do not need to be launched because they are only used by CICS applications not yet installed.

To not start these servers, comment-out the corresponding line in your ubbconfig file before recompiling.

The Synchronous Transaction Servers (ARTSTRN and ARTSTR1) that manage synchronous transaction CICS applications
The Asynchronous Transaction Servers (ARTATRN and ARTATR1) that manage asynchronous transaction CICS applications.
The Temporary Storage Server (ARTTSQ server) that manage TS QUEUES used in COBOL CICS programs.
The Tuxedo /Q TMQUEUE and TMQFORWARD servers that are only used for delayed CICS Transactions.

Note:

TMQUEUE must be started before ARTCNX to support the followings:

INQUIRE NETNANE TERMINAL() ACQSTATUS()
INQUIRE TERMINAL NETNAME() ACQSTATUS()
SET TERMINAL RELEASED/ACQUIRED/CREATE
Static LUNAME from 3270 terminal

Listing 2‑3 ubbconfig Initial Server Configuration Example

*SERVERS
ARTTCPL SRVGRP=TCP00
SRVID=101
CLOPT="-o /home2/work9/demo/Logs/TUX/sysout/stdout_tcp -e /home2/work9/demo/Logs/TUX/sysout/stderr_tcp -- -M 4 -m 1 -L //deimos:2994 -n //deimos:2992"
 
ARTADM SRVGRP=ADM00
SRVID=3000
SEQUENCE=1
MIN=1 MAX=1
CLOPT="-o /home2/work9/trf/Logs/TUX/sysout/stdout_adm -e /home2/work9/trf/Logs/TUX/sysout/stderr_adm -r --"
 
ARTCNX SRVGRP=GRP01
SRVID=15
CONV=Y
MIN=1 MAX=1 RQADDR=QCNX015 REPLYQ=Y
CLOPT="-o /home2/work9/demo/Logs/TUX/sysout/stdout_cnx -e /home2/work9/demo/Logs/TUX/sysout/stderr_cnx -r --"

Where:

*SERVERS

Is the Tuxedo ubbconfig keyword indicating server definitions.

For the ARTTCPL server:

SRVGRP

Is the Tuxedo Group Name to which ARTTCPL belongs.

SRVID

Is the identifier of a ARTTCPL Tuxedo Server.

CLOPT

Is a quoted text string passed to the server containing its parameters.

-o

Indicates the file is used for the standard output messages of the server.

-e

Indicates the file is used for the error output messages of the server.

-M 4

Indicates the maximum number of TCPL handler processes is 4.

-m 1

Indicates that the minimum number of TCPL handler processes is 1.

-L //deimos:2994

Indicates the internal URL address used by TCPL and TCPH for their own communication.

-n //deimos:2992

Indicates the URL address where the TN3270 terminals connect to TCPL.

For the ARTADM server:

SRVGRP

Is the Oracle Tuxedo group name to which ARTADM belongs.

SRVID

Is the identifier of a Tuxedo Server of ARTADM.

SEQUENCE=1

This line is mandatory. It indicates this server must be started first.

MIN=1 and MAX=1

Indicates that only one instance of this server must be run.

CLOPT

Is a quoted text string passed to the server containing its parameters.

-o

Indicates the file is used for standard output messages of the server.

-e

Indicates the file is used for error output messages of the server.

-r

Is a Tuxedo parameter used to produce statistical reports.

For the ARTCNX server:

SRVGRP

Is the Tuxedo Group Name to which ARTCNX belongs.

SRVID

Is the identifier of a Tuxedo Server of ARTCNX.

CONV=Y

Indicates that this server operates in a conversational mode.

MIN=1 and MAX=1

Indicates that only one instance of this server must be run.

REPLYQ=Y

Indicates that this server will respond.

RQADDR=QCNX015

Name of the Tuxedo queue used for the responses.

CLOPT

Is a quoted text string passed to the server containing its parameters.

-o

Indicates the file is used for the standard output messages of the server.

-e

Indicates the file is used for the error output messages of the server.

-r

Is a Tuxedo parameter used to produce statistical reports.

Parent topic: The Tuxedo ubbconfig File

2.1.2.2.3 The Mandatory Server Groups

To be started, a Tuxedo Server must be defined in a Tuxedo Server Group previously defined in the ubbconfig file. As the ARTTCPL and ARTCNX servers are mandatory, verify that their groups are defined, present and not commented-out, in the ubbconfig file.

In our example, ARTTCPL belongs to the Tuxedo Server Group TCP00 (SRVGRP=TCP00) and ARTCNX belongs to the Server Group (SRVGRP=GRP01); therefore the ubbconfig file contains these two Server Group definitions in the following example:

Listing 2‑4 Server Group Definitions

*GROUPS
DEFAULT: LMID=KIXR
# Applicative groups
TCP00 LMID=KIXR
GRPNO=1
TMSCOUNT=2
 
ADM00 GRPNO=5
GRP01
GRPNO=11
ENVFILE="/home2/work9/demo/config/tux/envfile"

Where:

*GROUPS

Tuxedo ubbconfig Keyword indicating definitions of Servers Groups.

LMID=

Name of the CICS.

GRPNO=

Tuxedo Group.

TMSCOUNT=

Number of Tuxedo Transaction Manager Servers.

ENVFILE

Path of the Tuxedo envfile.

Parent topic: The Tuxedo ubbconfig File

2.1.2.2.4 The Optional Server Groups

These groups are used to contain the optional servers. The first group is used by the Tuxedo Server Servers Groups: ARTSTRN, ARTSTR1, ARTATRN, ARTATR1, ARTTSQ used by CICS Applications. The second one is used only for TS QUEUE management.

Parent topic: The Tuxedo ubbconfig File

2.1.3 The CICS Runtime Resource Configuration Files

All of the following files must exist in the ${KIXCONFIG} path, even when empty, for CICS Runtime to be operational.

Parent topic: CICS Runtime Configuration

2.1.3.1 The Mandatory Populated Files

The typeterms.desc Configuration File
This file used by the TCP servers, describes the different kinds of terminals used with a 3270 terminal or emulator.

Listing 2‑5 typeterm Description Example
```
[typeterm]
name=IBM-3279-5E
color=YES
defscreencolumn=80
defscreenrow=24
description="IBM 327x family terminal"
hilight=YES
logonmsg=YES
outline=NO
swastatus=ENABLED
uctran=NO
userarealen=0
```
Where

[typeterm]

Keyword to define a terminal type.
name=
Type of terminal.

color=YES

Indicates whether the terminal uses extended color attributes.

defscreencolumn= 80

Number of columns of the terminal.

defscreenrow=24

Number of rows of the terminal

description="…"

Comment about the terminal.

hilight=YES

Indicates that this terminal supports the highlight feature.

logonmsg=YES

Indicates that "Good Morning" (CSGM) transaction is automatically started on the terminal at logon time.

outline=NO
Indicates that this terminal does not support field outlining.
swastatus=ENABLED

Indicates that this terminal type is available for use by the system.

uctran=NO

Indicates that the lowercase alphabetic characters are not to be translated to uppercase

userarealen=0

The terminal control table user area (TCTUA) area size for the terminal.
The mapsets.desc Configuration File
This file must contain at least the following definition to start the CSGM transaction and see the Good Morning screen.

Listing 2‑6 mapsets.desc Example

[mapset]
name=ABANNER
filename=<KIXDIR>/sysmap/abanner.mpdef

Where:

name=

Is the logical mapset name used inside the programs in the EXEC CICS SEND/RECEIVE MAP(map name) MAPSET(mapset name) … END-EXEC statements.

filename=

Is the physical path containing the binary file resulting from the compilation of a mapset file source coded in a CICS z/OS BMS format.

Note:

For the particular case of the ABANNER system mapset, the filename is located under the ${KIXDIR} directory. The bracketed text <KIXDIR> must be replaced by the value of the ${KIXDIR} variable of your UNIX ~/.profile system file.

In our example following is the result:

Listing 2‑7 mapsets.desc Example with ${TUXDIR} Substitution

[mapset]
name=ABANNER
filename=/product/art11gR1/Cics_RT/sysmap/abanner.mpdef

Parent topic: The CICS Runtime Resource Configuration Files

2.1.3.2 The Optional Initially Populated Files

All the following files can be initially left empty:

The transclasses.desc Configuration File
The transactions.desc Configuration File
The programs.desc Configuration File
The tsqmodel.desc Configuration File
The mapsets.desc Configuration File
The connections.desc Configuration File
The program_list_table.desc Configuration File

The contents and use of these files is described later.

Note:

If these files are left empty, when Tuxedo launches the CICS Runtime servers, some error messages "CMDTUX_CAT:1685: ERROR: Application initialization failure" could be displayed after the boot message of the ARTSTRN,ARTSTR1, ARTATRN and ARTATR1 servers indicating that the CICS Runtime considers this to be an anomaly.

The real number and type of servers displaying these messages depends on the servers initially launched by your ubbconfig file.

In this case, the servers concerned will not be mounted.

For the moment, ignore these error messages, they do not impact the Initial Setting.

The system.desc Configuration File
The terminals.desc Configuration File

For more information, see Oracle Tuxedo Application Runtime for CICS Reference Guide

Parent topic: The CICS Runtime Resource Configuration Files

2.2 Verifying the Initial Setting Configuration

The topics listed below describe how to verify your initial setting configuration of the resource files:

Parent topic: Initial Configuration of the CICS Runtime

2.2.1 Using the Tuxedo tmadmin psr Commands

Once all the files have been modified (and compiled for the ubbconfig), stop and restart Tuxedo to take their modifications into account.

The first control is to check that they are individually correctly accepted by Tuxedo and Oracle by a visual control of the boot messages of the Tuxedo CICS Runtime Tuxedo servers.

Once this first check is made, you can enter the Tuxedo tmadmin psr command to check that all the CICS Runtime servers are running and that their messages conform to the Tuxedo documentation and this document.

When the mandatory servers ARTADM, ARTTCPL, and ARTCNX only are started, the following messages are displayed:

Listing 2‑8 tmadmin psr Command Example

# tmadmin
...
 
> psr
Prog Name Queue Name Grp Name ID RqDone Load Done Current Service
--------- ---------- -------- -- ------ --------- ---------------
BBL 200933 KIXR 0 1 50 ( IDLE )
ARTTCPL 00001.00101 TCP00 101 0 0 ( IDLE )
ARTCNX QCNX015 GRP01 15 3 150 ( IDLE )
 
> quit
#

Note:

The BBL Server is a Tuxedo System Server which can be compared to a CICS server on z/OS.

Parent topic: Verifying the Initial Setting Configuration

2.2.2 Using the Tuxedo tmadmin psc Commands

You can also check that the required Tuxedo services are running using the tmadmin psc command.

These services should include the System Transactions managed by CICS Runtime:

CSGM: The Good Morning Screen
CESN: Sign On transaction
CESF: Sign Off transaction

Listing 2‑9 tmadmin psc Command Example

# tmadmin
...
 
> psc
Service Name Routine Name Prog Name Grp Name ID Machine # Done Status
------------ ------------ --------- -------- -- ------- ------ ------
authfail cnxsvc ARTCNX GRP01 15 KIXR 0 AVAIL
CESF cnxsvc ARTCNX GRP01 15 KIXR 0 AVAIL
CESN cnxsvc ARTCNX GRP01 15 KIXR 0 AVAIL
CSGM cnxsvc ARTCNX GRP01 15 KIXR 2 AVAIL
disconnect cnxsvc ARTCNX GRP01 15 KIXR 0 AVAIL
connect cnxsvc ARTCNX GRP01 15 KIXR 1 AVAIL
delsess cnxsvc ARTCNX GRP01 15 KIXR 0 AVAIL
gensess cnxsvc ARTCNX GRP01 15 KIXR 1 AVAIL
update cnxsvc ARTCNX GRP01 15 KIXR 0 AVAIL
inquire cnxsvc ARTCNX GRP01 15 KIXR 0 AVAIL
 
> quit
#

Note:

From a certain point of view, this Tuxedo command is equivalent to the z/OS CICS system transaction CEMT I TRAN(…) which allows you to display the available transactions in a given z/OS CICS environment.

Parent topic: Verifying the Initial Setting Configuration

2.2.3 Using the CSGM CICS Good Morning Transaction

Once this first audit is made, you can access CICS Runtime with a 3270 Terminal or Emulator using the following URL address${HOSTNAME}:${TCPNETADDR}.

Where:

${HOSTNAME}

Is the System UNIX variable containing the name of the UNIX machine on which you are running CICS Runtime.

${TCPNETADDR}

Is the port number specified by the -n parameter of the ARTTCP server in the Oracle Tuxedo UBBCONFIG file.

The following screen is displayed on a UNIX X11 Window after running the command # x3270 deimos:2992:

Figure 2-1 Screen After Running the Command #3270 deimos:2992

Successfully displaying this screen signifies you can continue implementing CICS applications using CICS Runtime.

Parent topic: Verifying the Initial Setting Configuration