Server Configuration

CICS Runtime servers references

About generic Tuxedo server configuration

All Tuxedo servers configured in the Tuxedo UBBCONFIG configuration file use standard arguments common to all servers. CICS Runtime servers benefit automatically from this flexibility.

The required arguments are SVRGRP and SVRID.

Other common arguments like MIN, MAX, SEQUENCE, CONV etc. are also available.

For precise information about the use of Tuxedo server configuration, consult the Tuxedo documentation, specifically the SERVERS section of UBBCONFIG(5).

One of the most useful of these optional arguments is the CLOPT (Command Line OPTions) argument.The CLOPT option is a string of command-line options that is passed to Tuxedo servers when they are booted.

This command line option is divided in two parts:

•	A generic part, common to every Tuxedo server, common server options are:

[-e stderr_file] [-o stdout_file]

directing standard output and errors to specific files.

•	A server specific part containing options referenced as uargs in Tuxedo documentation.

For precise information about using CLOPT options see the Tuxedo documentation, more specifically the servopts section.

The description of CICS Runtime specific servers systematically includes the two compulsory server arguments SVRGRP & SVRID, plus only the arguments needed specifically by the server type.

In the CLOPT, the following syntax is used:

CLOPT=”[servopts] –– generic-CICS Runtime-options server-specific-options”

Where:

Servopts

Represent options common to all Tuxedo servers described in servopts.

generic-CICS Runtime-options

Represent options specific to CICS Runtime, but available to all CICS Runtime servers.

server-specific-options

Are replaced by the options specific to the specific server.

Generic CLOPT options of CICS Runtime servers

This section describes the options common to all KIDEDO servers. These options are documented in this section and only in this section.

In the description of each specific server, they are referred to as generic-CICS Runtime-options.

CICS System id argument

This argument defines the name of the CICS system.

Synopsis

-s TEST

Description

Sets the value returned to programs by EXEC CICS ASSIGN SYSID.

Character, 1-256, A-Za-z0-9[/:-].

Exclusion

This option does not apply to ARTTCPL servers and connection servers.

List of Groups argument

This argument defines the list of resources group to be considered by this server(s) when loading resources.

Synopsis

-l group1:group2:…:groupn

Description

Groups in the resources configuration files are defined by 10 character strings. A server will only load in memory resources belonging to one of these groups.

As a facility for tests or generic servers, it is possible to remove the filtering by using –l ‘*’ to allow a server to load all the resources defined in the configuration file that it is reading.

Exclusion

This option does not apply to ARTTCPL servers and connection servers.

Configuration reference of CICS Runtime servers

ARTTCPL/ARTTCPH Configuration

Server Name

ARTTCPL – Terminal Control Program Listener.

Synopsis

ARTTCPL SRVGRP="identifier" SRVID="number" CLOPT="[servopts options] -- -n netaddr -L pnetaddr [-m minh] [-M maxh] [-x session-per-handler] [-p profile-name] [-D] [+H trace-level]”

Description

The terminal control program (ARTTCP) is a group of Tuxedo servers that manage the connections of 3270 terminal emulators to CICS Runtime. When you run programs, the ARTTCP connects terminal emulators to the network ports assigned to ARTTCP. ARTTCP communicates with the emulator using a Telnet protocol.

The ARTTCP server is composed of two types of servers: a single ARTTCP listener (ARTTCPL) process and one or more ARTTCP handler (ARTTCPH) processes. The ARTTCPL process establishes a well-known listening port address to which terminal emulators may connect. The ARTTCPH process listens on this port and accepts incoming connection requests. The ARTTCPH process establishes your user session for the connection and handles all subsequent screen I/O for the terminal emulator. As a performance enhancement, each ARTTCPH process can manage multiple sessions simultaneously. When you disconnect the emulator from the port, the ARTTCPH terminates the session.

Parameters

The following CLOPT run-time parameters are recognized:

-n netaddr

This address specifies where TN3270 terminal emulators connect to ARTTCPL. The address is a string in standard internet URL format. For example:

//computer:4000 designates port 4000 on machine computer.

Character, 1-256, A-Za-z0-9[/:-]. Mandatory option.

-L pnetaddr

This address is used by the system internally between ARTTCPL and ARTTCPH. The address is a string in standard internet URL format. For example:

//computer1:4001 designates port 4000 on machine computer.

Character, 1-256, A-Za-z0-9[/:-]. Mandatory option.

[-m minh]

The minimum number of handler processes that will be started by ARTTCPL. The actual number of handler processes will always be between the minh and maxh based on system load.

Numeric, 1-4096. Default value is 1.

[-M maxh]

The maximum number of handler processes that will be started by ARTTCPL. The actual number of handler processes will always be between the minh and maxh based on system load.

Numeric, 1-4096. Default value is 4096.

[-x session-per-handler]

The number of sessions a ARTTCPH can maintain concurrently.

Numeric, 1-255. Default value is 32.

[-p profile-name]

The default security profile file name. Please refer to Security configuration for details.

String. The default value is ~/.tuxAppProfile.

[-D ]

Enable Debug.

[+H trace-level]

Specify the trace level:

-1: trace off.

0: trace for all ARTTCPH.

n (n>0): trace the first n ARTTCPH.

Examples

*SERVERS ARTTCPL SRVGRP="TCPGRP" SRVID=1000 RESTART=Y GRACE=0

CLOPT="-- -n //hostname:4000 -L //hostname:4002 -m1 -M10 "

ARTSTRN Configuration

Server Name

ARTSTRN – CICS Runtime main server for synchronous terminal oriented transactions with MAXACTIVE > 1.

Synopsis

ARTSTRN SRVGRP="identifier" SRVID="number" CONV=Y MIN=minn MAX=maxn RQADDR=queueaddr REPLYQ=Y CLOPT="[servopts] -- -s TEST-l grp1:group2"

Description

ARTSTRN servers present application transactions as Tuxedo services and, when receiving a transaction request, execute the corresponding programs.

These servers are conversational in order to manage true conversational CICS transactions.

1.	When starting, an ARTSTRN server publishes one service per transaction it offers.

2.	When a user transmits a transaction request, the ARTTCPH managing the user performs a tpconnect to the corresponding transaction (service).

3.	One ARTSTRN server offering this service receives the request with the associated commarea and screen and then processes the transaction.

4.	After processing the transaction, the ARTSTRN server:

•	In the case of a Normal Pseudo-Conversational CICS transaction: On the RETURN {TRANSID} a reply is sent to the client, finishing the conversation by a tpreturn() returning the new 3270 screen, and the commarea.

•	In the case of a Conversational CICS transaction with loop of SEND & RECEIVE:

•	On the RECEIVE the ARTSTRN server transmits the prepared 3270 stream via tpsend(), then waits for a tpreceive, for the next user input to complete the RECEIVE

•	On the RETURN {TRANSID} the ARTSTRN server replies to the client, finishing the conversation by a tpreturn() returning the new 3270 screen, and the commarea.

Only transactions belonging to no tranclass, or to a tranclass with maxactive >1 are advertised by these servers.

Parameters

CONV

The generic parameter CONV is compulsory for this server type, and must be defined as CONV=Y, because ARTSTRN is conversational.

minn and maxn

Specify respectively the initial and maximum number of servers with this configuration to start. For more information see the UBBCONFIG section of the Tuxedo documentation.

CLOPT options

The following CLOPT run-time parameters are recognized:

-s SystemID

Mandatory option, see CICS System id argument.

-l GroupList

Mandatory option, see List of Groups argument.

Environment variables used

•

KIXCONFIG

•	KIX_CWA_IPCKEY

•	KIX_TRACE_LEVEL

•	KIX_MAP_PATH

•	KIX_TECH_DIR

Examples

*SERVERS

ARTSTRN SRVGRP="TCPGRP" SRVID=1000 RESTART=Y GRACE=0

CONV=Y MIN=2 MAX=3 RQADDR=QKIX1000 REPLYQ=Y

CLOPT=" -- -s PROW -l group1:group2"

ARTSTR1 Configuration

Server Name

ARTSTR1 – CICS Runtime main server for synchronous terminal oriented transactions with MAXACTIVE = 1.

Synopsis

ARTSTR1 SRVGRP="identifier" SRVID="number" CONV=Y MIN=1 MAX=1 CLOPT="[servopts] -- -s TEST -l group1:group2,…"

Description

Theses servers are a specialized version of ARTSTRN servers presenting only transactions with MAXACTIVE = 1; While ARTSTRN servers present only transactions with MAXACTIVE > 1.

It is critical and verified by STR1 servers at boot time that MIN and MAX number of servers are set to 1. The goal of these servers being to guarantee the parallel processing of only one transaction in a group (with MAXACTIVE =1), to start or let Tuxedo start a few servers offering the same transactions will be self-defeating for STR1 Servers.

Since MIN and MAX are set to 1 the Tuxedo argument RQADDR, become unnecessary, and should be avoided for simplicity.

The rest of the configuration and behavior of STR1 servers are exactly the same a STRN servers.

Examples

*SERVERS

ARTSTR1 SRVGRP="TCPGRP" SRVID=1000 RESTART=Y GRACE=0

CONV=Y MIN=1 MAX=1

CLOPT=" -- -s PROW -l group1:group2"

ARTTSQ Configuration

Server Name

ARTTSQ – CICS Runtime Temporary Storage Queue Server

Synopsis

ARTTSQ SRVGRP="identifier" SRVID="number" MIN=1 MAX=1

CLOPT"[servopts] -- -l grp1:group2"

Description

ARTTSQr manages temporary storage queues, it serves the functionalities required by EXEC CICS: WRITEQ TS, READQ TS and DELETEQ TS.

ARTTSQ publishes two main kinds of services:

•	TSQUEUE: This service is published only once when the first ARTTSQ starts. TSQUEUE processes TSQ requests for queues matching no TSMODEL.

•	{TSMODEL}_TSQUEUE: One of those services is published for each TSMODEL.

The server publishing this service will accomplish all the operations needed on the queues matching this TSMODEL.

One server will publish the TSMODELs belonging to the resource groups assigned to this server thru the -l option.

A group of resources must be assigned to a single tsq serverto avoid trying to publish the same service twice. This is checked at boot time and will generate error messages during the boot phase when not respected, but no action will be taken.

It is critical, and verified by TSQ servers at boot time, that MIN and MAX number of servers are set to 1.

It is critical that the same server which created one queue (first write) also serves all other read/write delete requests to this queue. This is the reason why each service, either generic or corresponding to a specific model, must be advertised by a single server.

This unicity is verified when services are published.

Parameters

ARTTSQ

The following CLOPT run-time parameters are recognized:

[-l Group]

Mandatory option, see List of Groups argument for more information.

DBMS Constraints

SRVGRP must be a Tuxedo group with an Oracle Resource Manager configured with TMSNAME and OPENINFO.

The DBMS user indicated in the OPENINFO of the group containing the server, must have access to the TS_QCONTENT table; either directly (objects created in this schema) or thru a DBLINK.

On this pre-existing table it must have select, insert, update, delete permissions.

The script to create the table for Oracle is listed below:

Listing 6‑1 TS_QCONTENT Creation

 

drop table TS_Q_CONTENT purge;

create table TS_Q_CONTENT

( TS_QUEUE char(16) NOT NULL,

TS_ITEM number(8) NOT NULL,

TS_LENGTH number(8),

TS_RAW LONG RAW,

primary key (TS_QUEUE, TS_ITEM)

);

 

Environment variables used

•

KIXCONFIG

•	KIX_TS_DIR

•	KIX_TRACE_LEVEL

•	KIX_MAP_PATH

•	KIX_TECH_DIR

Examples

*SERVERS

ARTTSQ SRVGRP="GRP02" SRVID=30 RESTART=Y GRACE=0

MIN=1 MAX=1 CLOPT=" -- -s PROW -l group1:group2"

ARTDPL Configuration

Server Name

ARTDPL – CICS Runtime server for distributed program link execution.

Synopsis

ARTDPL SRVGRP="identifier" SRVID="number" MIN=minn MAX=maxn

CLOPT="[servopts] -- -s TEST -l grp1:group2"

Description

Theses servers present application programs restricted to DPL subsets as tuxedo services and when receiving a DPL service request execute the corresponding program.

Theses servers do not need to (cannot) address the principal facility (the user terminal) and so do not need to be conversational. They are pure RPC mode servers.

When starting, a ARTDPL publishes one service per program it offers.

When a program requests a LINK, if the requested program is configured as DPL then the link is not resolved as usual by a call, but by a tpcall, which will be served by one of the DPL servers offering this service (this DPL program).

Only programs with the attribute REMOTESYSTEM(sysid) positioned to DPL, will be advertised by DPL servers, and only by servers with this sysid as system indicated thru the -s option

The service advertised by ARTDPL for each of these programs, will be SYSID_ProgramName.

Conversely, these programs will not be available directly from str or atr servers.

Parameters

minn and maxn

Specify respectively the initial and maximum number of servers to start. For more information see the UBBCONFIG section of the Tuxedo documentation.

CLOPT options

The following CLOPT run-time parameters are recognized:

-s SystemID]

Mandatory option, see CICS System id argument.

-l GroupList]

Mandatory option, see List of Groups argument.

Environment variables used

•

KIXCONFIG

•	KIX_CWA_SIZE

•	KIX_CWA_IPCKEY

•	KIX_TRACE_LEVEL

•	KIX_TECH_DIR

Examples

*SERVERS

ARTDPL SRVGRP="TCPGRP" SRVID=1000 RESTART=Y GRACE=0

CONV=Y MIN=2 MAX=3 RQADDR=QKIX1000 REPLYQ=Y

CLOPT=" -- -s PROW -l group1:group2"

ARTATRN Configuration

Server Name

ARTATRN – CICS Runtime server for asynchronous oriented transactions with MAXACTIVE > 1.

Synopsis

ARTATRN SRVGRP="identifier" SRVID="number" CONV=N MIN=minn MAX=maxn RQADDR=QKIXATR REPLYQ=Y CLOPT="[servopts] -- [-s TEST] [-l group1:group2:…]"

Description

ARTATRN servers present application transactions as Tuxedo services and when receiving a transaction request, execute the corresponding programs.

These programs are screenless programs which cannot interact directly with the terminal user.

In contrast to ARTSTRN servers, these servers are transactional in order to manage true CICS transactions. They are only called from other servers (START TRANSID) and never directly from terminals or clients.

When starting, an ARTATRN server publishes one service per transaction it offers. These transactions are named "ASYNC_{transaction_name} (.

This server also publishes a technical transaction called ASYNC_QUEUE.

1.	When a user program calls a transaction, the KIX__START_TRANSID function makes a tpacall to the corresponding transaction (service).

2.	One ARTATRN offering this service receives the request with the associated message, then processes the transaction.

3.	The transactions ends without returning a message to the caller.

Only transactions belonging to no tranclasses, or to a tranclass with maxactive >1 are advertised by these servers.

Parameters

CONV

The generic parameter CONV is optional for this server type, if you use it, it must be defined as CONV=N, because the ARTATRN is transactional.

minn and maxn

Specify the initial and maximum number of servers to be used to start with this configuration. For more information, see the UBBCONFIG section of the Tuxedo documentation.

CLOPT

A string of command-line options that is passed to the ARTATRN when it is booted. The following run-time parameters are recognized:

[-s SystemID]

Mandatory option, seeCICS System id argument for more information.

[-l GroupList]

Mandatory option, see List of Groups argument for more information.

Environment variables used

KIXCONFIG

KIX_CWA_SIZE

KIX_CWA_IPCKEY

KIX_QSPACE_IPCKEY

KIX_TRACE_LEVEL

KIX_TECH_DIR

Examples

*SERVERS

ARTATRN SRVGRP="TCPGRP" SRVID=2000 RESTART=Y GRACE=0

CONV=N MIN=2 MAX=3 RQADDR=QKIXATR REPLYQ=Y

CLOPT=" -- -s PROW -l group1:group2"

ARTATR1 Configuration

Server Name

ARTATR1 - CICS Runtime main server for asynchronous oriented transactions with MAXACTIVE = 1.

Synopsis

ARTATR1 SRVGRP="identifier" SRVID="number" CONV=N MIN=1 MAX=1 CLOPT="[servopts] -- [-s TEST] [-l group1:group2,…]"

Description

ARTATR1 servers are a specialized version of ARTATRN servers presenting only transactions with MAXACTIVE = 1, whereas ARTATRN servers present transactions with MAXACTIVE > 1.

It is critical, and verified by ATR1 servers at boot time, that MIN and MAX number of servers are set to 1. The goal of these servers is to guarantee the parallel processing of only one transaction in a group (with MAXACTIVE =1). To permit Tuxedo to start several servers offering the same transactions would be self-defeating for ATR1 Servers.

Since MIN and MAX are set to 1, the Tuxedo argument RQADDR, becomes unnecessary, and should be avoided for simplicity.

The rest of the configuration and behavior of ATR1 servers are exactly the same as ATRN servers.

Examples

*SERVERS

ARTATR1 SRVGRP="TCPGRP" SRVID=2000 RESTART=Y GRACE=0

CONV=N MIN=1 MAX=1

CLOPT=" -- -s PROW -l group1:group2"

ARTCTRN Configuration

Server Name

ARTCTRN – CICS Runtime server for conversation oriented transactions with MAXACTIVE > 1.

Synopsis

ARTCTRN SRVGRP="identifier" SRVID="number" CONV=N MIN=minn MAX=maxn RQADDR=QKIXCTR REPLYQ=Y CLOPT="[servopts] -- [-s TEST] [-l group1:group2:…]"

Description

ARTCTRN servers present application transactions as Tuxedo services and when receiving a transaction request, execute the corresponding programs.

These programs are screenless programs which cannot interact directly with the terminal user.

In contrast to ARTSTRN servers, these servers are transactional in order to manage true CICS transactions. They are only called from other servers (CNVERSE) and never directly from terminals or clients.

When starting, a ARTCTRN server publishes one service per transaction it offers. These transactions are named {SysId}_{transaction_name}.

The {SysId} is the name of this region defined in the -s parameter.

1.	When a user program calls a transaction, the KIX__CONVERSE function makes a tpacall to the corresponding transaction (service).

2.	One ARTCTRN offering this service receives the request with the associated message, then processes the transaction.

3.	The transactions ends and the server returns a message to the caller.

Only transactions belonging to no tranclasses, or to a tranclass with maxactive >1 are advertised by these servers.

Parameters

CONV

The generic parameter CONV is optional for this server type; if you use it, it must be defined as CONV=N, because the ARTATRN is transactional.

minn and maxn

Specify the initial and maximum number of servers to be used to start with this configuration. For more information, see the UBBCONFIG section of the Tuxedo documentation.

CLOPT

A string of command-line options that is passed to the ARTCTRN when it is booted. The following run-time parameters are recognized:

[-s SystemID]

Mandatory option, seeCICS System id argument for more information.

[-l GroupList]

Mandatory option, see List of Groups argument for more information.

Environment variables used

KIXCONFIG

KIX_CWA_SIZE

KIX_CWA_IPCKEY

KIX_QSPACE_IPCKEY

KIX_TRACE_LEVEL

KIX_TECH_DIR

Examples

*SERVERS

ARTCTRN SRVGRP="TCPGRP" SRVID=2500 RESTART=Y GRACE=0

CONV=N MIN=2 MAX=3 RQADDR=QKIXATR REPLYQ=Y

CLOPT=" -- -s PROW -l group1:group2"

ARTCTR1 Configuration

Server Name

ARTCTR1 – CICS Runtime main server for conversation oriented transactions with MAXACTIVE = 1.

Synopsis

ARTCTR1 SRVGRP="identifier" SRVID="number" CONV=N MIN=1 MAX=1

CLOPT="[servopts] -- [-s TEST] [-l group1:group2,…]"

Description

ARTCTR1 servers are a specialized version of ARTCTRN servers presenting only transactions with MAXACTIVE = 1, whereas ARTCTRN servers present transactions with MAXACTIVE > 1.

It is critical, and verified by ARTCTR1 servers at boot time, that MIN and MAX number of servers are set to 1. The goal of these servers is to guarantee the parallel processing of only one transaction in a group (with MAXACTIVE =1). To permit Tuxedo to start several servers offering the same transactions would be self-defeating for ARTCTR1 servers.

Since MIN and MAX are set to 1, the Tuxedo argument RQADDR, becomes unnecessary, and should be avoided for simplicity.

The rest of the configuration and behavior of ARTCTR1 servers are exactly the same as ARTCTRN servers.

Examples

*SERVERS

ARTCTR1 SRVGRP="TCPGRP" SRVID=2000 RESTART=Y GRACE=0

CONV=N MIN=1 MAX=1

CLOPT=" -- -s PROW -l group1:group2"

ARTCNX Configuration

Server Name

ARTCNX — CICS Runtime connection server for user connection management.

Synopsis

ARTCNX SRVGRP="identifier" SRVID="number" CONV=Y MIN=1 MAX=1 RQADDR=QKIX110 REPLYQ=Y CLOPT="[servopts]"

Description

This server offers technical services needed by terminal handlers during user connection and disconnection phases.

It offers internal message oriented services such as connect and disconnect:

•	connect is in charge of various initialization tasks such as attributing the user Session ID and Terminal_ID.

•	disconnect manages the disconnection final tasks.

It also offers a few classical CICS transactions:

•	CESN: the Sign oN transaction

•	CESF: the Sign ofF transaction

•	CSGM: the Good Morning transaction (default Good Morning transaction)

It also publishes a technical transaction, authfail used by the handler in case of authentication error.

Theses servers are conversational in order to manage CICS transactions CESN, CESF.

This server must be unique in a CICS Runtime system.

Parameters

CONV

The generic parameter CONV is mandatory for this server type, and must be defined as CONV=Y, because ARTSTRN is conversational.

minn and maxn

Must be set to 1. This will still be true in the next release, where each server will be allocated a range of terminal identifiers

CLOPT

No specific CLOPT run-time parameters are recognized.

Environment variables used

KIX_TRACE_LEVEL

Examples

*SERVERS

ARTCNX SRVGRP="TCPGRP" SRVID=1000 CONV=Y MIN=1 MAX=1

ARTADM Configuration

Server Name

ARTADM — Administration Server

Synopsis

ARTADM SRVGRP="identifier" SRVID="number"

Description

This server is responsible for the administration of CICS Runtime.

In a distributed target environment, this server can be configured on each node to achieve the configuration propagation. With these servers, the configuration files only need to be configured on the master node, and the administration servers propagate the configuration files to each slave node.

1.	When starting up, the administration server running on the master node reads in all the configuration files located in directory ${KIXCONFIG}.

2.	When each administration server running on a slave node starts up, it communicates with the administration server on the master node and fetches the contents of the configuration files.

3.	The administration server on the slave node then writes to the corresponding configuration files in directory ${KIXCONFIG} on the slave node. New configuration files are created if none exist.

This server is optional. When configuration propagation is required, an administration server should be configured on every Tuxedo node.

•	The ARTADM server on the master node must be started as the first server in the target application.

•	The ARTADM server on the slave node must be started as the first server on the node.

The ARTADM server on the master node offers a service for the internal communications with the ARTADM servers running on the slave nodes.

•	‘getConfig' is used by the slave ARTADM server to get configuration information from the master ARTADM server.

Examples

*SERVERS

ARTADM SRVGRP="ADMGRP" SRVID=1000 RESTART=Y