CICS Runtime Server Build Tool

Overview

Definition

CICS Runtime server build tool constructs one or more Oracle ART CICS server(s) load module. All supported servers which can be built by this build tool are listed in Table 13‑1. With a set of prefixes for the server names, Oracle Tuxedo Application Runtime for CICS now allows users to customize server names started with these prefixes. The asterisk (*)character is a wildcard character that can be replaced with zero or more characters. Each prefix stands for one class of servers with special functions as shown on Table 13‑1. For example, you can build a server named “ARTSTRN_UDB”.

 

Table 13‑1 Servers Need to be Built by CICS Server Build Tool

Server Name	Description
ARTSTR1* ARTSTRN*	The task of these servers is to offer application transactions and process the corresponding programs.
ARTTSQ*	The role of these servers is to centralize the management of the TS Queue operations which are requested by applications.
ARTDPL*	ARTDPL servers publish programs that are callable by EXEC CICS LINK as services and manage the execution of these services.
ARTATR1* ARTATRN*	These servers publish transactions callable by EXEC CICS START TRANSID as services named ASYNC_{Transaction_Name} and manage execution of these services.
ARTCTR1* ARTCTRN*	These servers publish transactions callable by EXEC CICS CONVERSE as services named {SysId}_{Transaction_Name} and manage execution of these services.
ARTWTR1* ARTWTRN*	CICS Runtime application server for synchronous (non-conversational) non-3270s clients.

Administration

To make this tool work correctly, several environment variables must be set firstly as shown in Table 13‑2.

 

Table 13‑2 Required Environment Variables

Variable Name	Description
TUXDIR	Mandatory. Install directory of Tuxedo. If it is not set, the tool will stop with a clear error message.
KIXDIR	Mandatory. Install directory of ART CICS Runtime. It’s <ART_INSTALL_DIR>/Cics_RT. If it is not set, the tool will stop with a clear error message. Besides, “$KIXDIR/bin” must be included in “$PATH” to execute buildartcics.
COBDIR | COBOLITDIR	Mandatory. Install directory of COBOL compiler (COBDIR is for Micro Focus COBOL; COBOLITDIR is for COBOL-IT). One and only one can be set in the environment. If neither or both of them exist, the tool will stop with a clear error message.
DB2DIR | ORACLE_HOME	Mandatory in some situations. Optional for others. Install directory of database (DB2DIR is for UDB and is mandatory when “-r UDB_XA*” is specified; ORACLE_HOME is for Oracle and is mandatory when “-r Oracle_XA*” is specified). If either of them does not exist when required, the tool will stop with a clear error message.
MT_DB_LOGIN	Mandatory for ARTTSQ* servers built with UDB database. Optional for others. The connect parameter for DB2 database is used in: db2 connect to […] General Syntax: “db-alias user username using passord”
DB2INSTANCE	Mandatory for ARTTSQ* servers built with UDB database. Optional for others. Specifies current DB instance.
MQM	Optional. Stands for the install dir of WebSphere MQ. If not set, it equals to “/usr/mqm” for AIX platforms and “/opt/mqm” for Linux and Solaris platforms.

Notes:

•	To use COBOL-IT compiler, please make a copy or create a symbol link of “$COBOLITDIR/bin/cobmf” as “$COBOLITDIR/bin/cob”. For example, you can use following command: ln -s $COBOLITDIR/bin/cobmf $COBOLITDIR/bin/cob.

•	For Solaris platform, please make sure that $LD_LIBRARY_PATH includes library path for 64-bit "libc*" libraries, which are located in <SUN_STUDIO_INSTALL_DIR>/lib/v9.

•	To build ARTTSQ with UDB, please make sure the table "TS_Q_CONTENT" already exists in the Database; if not, you can run "<ARTINSTALL_DIR>/Cics_RT/tools/crtstable_UDB" after all required environment variables are set correctly.

buildartcics

All servers can be built by following synopsis of this tool, except for ARTTSQ that does not support multiple RMs. If “-M” is specified when ARTTSQ is built, a warning message will be displayed and only the first “-r” will be taken as the resource manager.

Name

buildartcics – Constructs one or more Oracle ART CICS server(s) load module.

Synopsis

buildartcics [-v] [-n] [-M] [-r rmname] [-f firstfiles] [-l lastfiles] –o svrname

Description

buildartcics is used to construct one or more Oracle ART CICS server(s) load module. This command invokes “buildserver” to build the specified ART CICS server(s).

-v

Specifies that buildartcics should work in verbose mode. In particular, it writes the compilation command to its standard output.

-n

Supports non-XA for Oracle ART CICS server ARTATRN/1 and ARTDPL. When rebuilding ARTATRN/1 or ARTDPL, specify this option if you require non-XA support. Both Oracle and DB2 database support non-XA local transaction optimization. For more information, see ARTKIX_XA_DISABLE.

-M

Specifies multiple resource managers associated with this server. This option is mandatory if you want to associate your service with multiple XA complaint resource managers. If this option is not specified and you try to boot a server with a configuration file, in which this server is specified in a non-multiple resource manager server group, a warning message will be printed in the user log; in addition, the sever will revert to a general server associated with one resource manager if the "-r" option is specified when buildserver command is executed.

-r rmname

Specifies the resource manager associated with this server. Multiple “-r rmname” can be specified if “-M” is used. The value rmname must appear in the resource manager table located in $TUXDIR/udataobj/RM.

-f firstfiles

-f option will be passed to buildserver command. It specifies one or more user files to be included in the compilation and link edit phases of buildserver first, before the Oracle Tuxedo ATMI libraries. If you specify more than one file, use spaces to separate those filenames and enclose the entire list in quotation marks (see Listing 4). You can specify this option multiple times. For more information, see buildserver(1) in Oracle Tuxedo documentation.

-l lastfiles

-l option will be passed to buildserver command. It specifies one or more user files to be included in the compilation and link edit phases of buildserver last, after the Oracle Tuxedo ATMI libraries. If you specify more than one file, use spaces to separate those filenames and enclose the entire list in quotation marks (see Listing 4). You can specify this option multiple times. For more information, see buildserver(1) in Oracle Tuxedo documentation.

-o svrname

Specifies the name of the server to load. This option is mandatory. If “svrname” is a standalone filename without any “/” character, the server will be generated to $KIXDIR/bin by default.

Note:

Currently, supported resource managers include Oracle_XA*, UDB_XA*, BERKELEY-DB*, and MQSeries_XA_RMI*; therefore, the “rmname” must use one of these four strings as a prefix.

Specially, for ARTTSQ* servers, only RMs provided by Oracle or DB2 UDB are supported. If other RMs are specified when ARTTSQ* servers is built, the TSQ data may not be stored correctly. Besides, to build ARTTSQ* servers with "TMS_UDB" RM, please make sure that table "TS_Q_CONTENT" exists in the DB2 Database; if this table doesn't exist, you can create it by running "$KIXDIR/tools/crtstable_UDB".

Example

Listing 3 Example 1

buildartcics - M - r Oracle_XA - r BERKELEY-DB - o ARTSTRN

 

Listing 4 Example 2

buildartcics -r Oracle_XA -o ./ARTSTRN -f "-lkix" -f "-lkixc" -l "-lc -lnsl -ldl -lm"