Initial Configuration of the CICS Runtime

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 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 3‑1 .profile variables

Variable	Value	Usage	Variable usage
TUXDIR	Set up at Installation time	Compulsory. Directory containing the Installed Tuxedo product. The default location is /usr/tuxedo	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 3‑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

 

The Tuxedo System files

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:

 

Table 3‑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 3‑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.)

#

# Copyright �1998, BEA Systems, Inc., all rights reserved.

#--------------------------------------------------------------------------

# 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

PATHTS=${KIX_TS_DIR}

LC_MESSAGES=C

 

# End

 

The Tuxedo ubbconfig file

Some CICS Runtime Tuxedo servers are absolutely needed while others can be optionally started but are not absolutely necessary at this time.

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 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

Listing 3‑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"

 

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 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.

The mandatory servers 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 3‑4 Server Group definitions

*GROUPS

DEFAULT: LMID=KIXR

# Applicative groups

TCP00 LMID=KIXR

GRPNO=1

TMSCOUNT=2

 

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 where CSGM is running.

GRPNO=

Tuxedo Group.

TMSCOUNT=

Number of Tuxedo Transaction Manager Servers.

ENVFILE

Path of the Tuxedo envfile.

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.

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.

The mandatory populated files

1.	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 3‑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.

2.	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 3‑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 the result will be:

Listing 3‑7 mapsets.desc example with ${TUXDIR} substitution

[mapset]

name=ABANNER

filename=/product/art11gR1/Cics_RT/sysmap/abanner.mpdef

 

The optional initially populated files

All the following files can be initially left empty:

1.	The transclasses.desc Configuration File

2.	The transactions.desc Configuration file

3.	The programs.desc Configuration File

4.	The tsqmodel.desc Configuration File

5.	The mapsets.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.

Verifying the Initial Setting Configuration

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 you have started only the mandatory servers ARTTCPL and ARTCNX, the following messages are displayed:

Listing 3‑8 tmadmin psr command example

# tmadmin

tmadmin - Copyright (c) 2007-2010 Oracle.

Portions * Copyright 1986-1997 RSA Data Security, Inc.

All Rights Reserved.

Distributed under license by Oracle.

Tuxedo is a registered trademark.

 

> 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.

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 3‑9 tmadmin psc command example

# tmadmin

tmadmin - Copyright (c) 2007-2010 Oracle.

Portions * Copyright 1986-1997 RSA Data Security, Inc.

All Rights Reserved.

Distributed under license by Oracle.

Tuxedo is a registered trademark.

 

> 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

 

> 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.

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 for your UNIX 3270 emulator set up by your Tuxedo Administrator at installation time in the ubbconfig file.

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

Figure 3‑1  

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