This application was initially developed on a z/OS platform implementing COBOL programs used in batch and CICS contexts with VSAM and QSAM files and DB2 tables.

Data was unloaded from z/OS and converted and reloaded on a UNIX platform using Oracle Tuxedo Application Rehosting Workbench.

The language components were converted or translated from z/OS to UNIX by Oracle Tuxedo Application Rehosting Workbench.

These components use two major Oracle Tuxedo Application components, Batch Runtime and CICS Runtime, to emulate the technical centralized features of their original z/OS environment. Here, we will focus on the particular case of the CICS Runtime implementing COBOL Programs using CICS statements and DB2 statements.

This Simple Application manages the customers of a company through a set of classical functions like creation, modification and deletion.

All of the CICS components are declared with the same name, in the z/OS CICS CSD File. All of the resource declarations are made inside a z/OS CICS GROUP named PJ01TERM. This group is declared in the z/OS CICS LIST PJ01LIST used by CICS at start up to be automatically installed.

• Mapsets
  
• Programs
  
• Transactions Codes
  
• VSAM File
  

The first example uses the CICS Simple File-to-Oracle application which uses only a z/OS VSAM File converted into a UNIX Oracle Table.

In our example, all of the UNIX components resulting from platform migration are stored in the trf directory.

The COBOL programs and BMS mapsets should be compiled and available as executable modules in the respective directories ${HOME}/trf/cobexe and ${HOME}/trf/MAP_TCP.

• CICS Simple File-to-Oracle Application UNIX Components
  

For a standard application, in addition to the initial settings, the following CICS resources in the same Group must be implemented:

• Basic CICS transactions (synchronous and simultaneous).
• COBOL Programs without SQL statements, CICS TS queues.
• Mapsets.
• VSAM file (logical name and associated data accessors).

To configure these resources:

1. Declare these resources in their respective CICS Runtime Resource Configuration File.
2. Configure the CICS Runtime Tuxedo Servers Groups and Servers to manage these resources. See Reference for a full description of which configuration files are used with each server.

The following topics describe in detail the configuration process:

• Declaring CICS Resources to the CICS Runtime
  
• Declaring CICS Transactions Codes
  
• Declaring a CICS COBOL Program
  
• Declaring CICS Mapsets
  
• Declaring ISAM Files Resulting From a z/OS VSAM File Conversion
  
• Modifying the CICS Runtime Tuxedo Servers
  
• Modifying the CICS Runtime Tuxedo Servers Groups
  

Enter the Tuxedo tmadmin psr command to check that all of the CICS Runtime required servers (ARTTCPL, ARTCNX, and ARTSTRN) are running and that their messages conform to the Tuxedo documentation and this document.

Listing 4‑7 tmadmin psr Simple Application Installation Check

# tmadmin
...
 
> psr
Prog Name Queue Name Grp Name ID RqDone Load Done Current Service
--------- ---------- -------- -- ------ --------- ---------------
BBL 200933 KIXR 0 2 100 ( IDLE )
ARTTCPL 00001.00101 TCP00 101 0 0 ( IDLE )
ARTCNX QCNX015 GRP01 15 2 100 ( IDLE )
ARTSTRN QKIX110 GRP02 20 6 300 ( IDLE )
 
> quit
#

Another possible check can be made by entering the Tuxedo tmadmin psc command to display all the different Tuxedo Services running.

In addition to the CICS Runtime System transactions/services (CSGM, CESN, CESF …), you can now see the transaction codes of your CICS Runtime application SA00, SA01, SA02 and SA03

Listing 4‑8 tmadmin psc Simple Application Installation Check

# 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 1 AVAIL
disconnect cnxsvc ARTCNX GRP01 15 KIXR 0 AVAIL
connect cnxsvc ARTCNX GRP01 15 KIXR 1 AVAIL
SA03 kixsvc ARTSTRN GRP02 20 KIXR 3 AVAIL
SA02 kixsvc ARTSTRN GRP02 20 KIXR 0 AVAIL
SA01 kixsvc ARTSTRN GRP02 20 KIXR 0 AVAIL
SA00 kixsvc ARTSTRN GRP02 20 KIXR 3 AVAIL
 
> quit
#

Before using the CICS application, you have to populate the ISAM files accessed by your application. Then, access CICS Runtime with a 3270 Terminal or Emulator, with a UNIX x3270 command. It should be:

# x3270 ${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.

1. You will receive the Good Morning Message.
2. Clear it by pressing the Clear key of your 3270 emulator keypad.
3. Type the main transaction code SA00 (of your CICS Runtime application) in the top left corner:

   Figure 4-1 Simple Application Transaction Code Entry

   
   

   

   
   
4. The main menu of the application is displayed:

   Figure 4-2 Simple Application Main Menu

   
   

   

   
   
5. Navigate through the screens of the application to check that they are displayed without errors.

Add the MRM parameter in the group entry of *GROUPS and *RMS section in Tuxedo ubbconfig file. See the following example:

Listing 4‑9 Adding MRM Parameter in ubbconfig File Example

*GROUPS
GRP02
GRPNO=12
MRM=Y
*RMS
MRMG_RM1
SRVGRP=GRP02
RMID=15
TMSNAME="TMS_BDB"
OPENINFO="BERKELEY-DB:/home2/work10/data"

Where:

*GROUPS

Tuxedo ubbconfig keyword indicating the definitions of Servers Groups.

GRPNO

Indicates the Tuxedo Group.

MRM= Y

Indicates that this server group can support multiple resource managers.

*RMS

Tuxedo ubbconfig keyword indicating the definitions of resource managers.

MRMG_RM1

Indicates the logical name of RMS entry.

SRVGRP

Indicates the name of the group associated with this RM.

RMID

Indicates the unique ID number of this RM in the group. ID number must be between 1 and 31.

TMSNAME

Indicates the name of the transaction manager server associated with the group specified by SRVGRP.

OPENINFO

Indicates the resource manager dependent information needed when opening resource manager for the associated group.

To build the BDB TMS server, add the following lines to

$TUXDIR/udataobj/RM::

BDB_HOME=/opt/cobol-it-64-bdb

BERKELEY-DB:db_xa_switch:-L/opt/cobol-it-64-bdb/lib -ldb-18.1

After updating the RM file, execute the following command to build TMS server for BDB:

buildtms -v -r BERKELEY-DB -o $APPDIR/TMS_BDB

Export the following variables explicitly before booting up the ART servers:

• DD_VSAMFILE

  export DD_RBDB02=${DATA}/MTWART.ES.SFI.RCIBDB02.BDB0122

  RBDB02 is the logical file name.

• COB_ENABLE_XA

  export COB_ENABLE_XA=1

The MAXACTIVE=1 is really an exception in this management because it indicates that no concurrent transaction belonging to these kind of transaction classes can be run simultaneously.

To manage this very particular case of sequential transactions, a Tuxedo CICS Runtime feature must be configured.

All of the transactions linked to transactions classes with a MAXACTIVE superior or equal to 2 are managed by the CICS Runtime Tuxedo Server ARTSTRN and do not required modifying anything else. For the transactions with a MAXACTIVE parameter set to 1, an CICS Runtime Tuxedo Server named ARTSTR1 is dedicated to their specific management.

To activate this server, modify the ubbconfig file to add this server in the *SERVERS section:

Listing 4‑10 Adding a ARTSTR1 Server to ubbconfig

*SERVERS
…
ARTSTR1 SRVGRP=GRP02
SRVID=200
CONV=Y
MIN=1 MAX=1
CLOPT="-o /home2/work9/demo/Logs/TUX/sysout/stdout_str1 -e /home2/work9/demo/Logs/TUX/sysout/stderr_str1 -r -- -s KIXR -l SIMPAPP"
…

Where:

*SERVERS

Tuxedo ubbconfig Keyword indicating a Server Section definition.

SRVGRP

Is the Tuxedo Group Name to which ARTSTR1 belongs.

SRVID

Is the identifier of a ARTSTR1 Tuxedo Server.

CONV=Y

Indicates that this server operates in a conversational mode.

MIN=1 and MAX=1

Are mandatory and indicate that only one instance of this server must run.

CLOPT

Is a quoted text string passed to the server containing the parameters:

-o

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

-e

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

-r

Is a Tuxedo parameter used to produce statistical reports.

-s

KIXR indicates the CICS Runtime name where the KIXR transaction is run.

-l SIMAPP

• Modifying the tranclasses.desc File
  
• Modifying the transactions.desc File
  

The following topics describe how to verify ARTSTR1 configuration:

• Using the Tuxedo tmadmin psr Commands
  
• Using the Tuxedo tmadmin psc Commands
  

The file is modified in the same manner as for the ARTSTRN and the ARTSTR1 servers, except the "s" (synchronous) character used to prefix the name of these servers should be replaced by the "a" (asynchronous) character.

To use parallel asynchronous transactions, with a MAXACTIVE parameter strictly superior to one, the dedicated server is the ARTATRN. Please refer to the section describing the installation of the ARTSTRN server to install the atrn_server.

To check your settings you can use also the tmadmin psr and psc commands.

For the Simple Application example we can see that:

• The psr command shows that a new server is running ARTATRN.
• The psc command shows that five new services are running, one is dedicated to the asynchronous transaction while each synchronous transaction (SA00 to SA03) is duplicated (ASYNC_SA00 to ASYNC_SA03) to allow them to run in an asynchronous mode.

Listing 4‑14 tmadmin Commands Showing Parallel Asynchronous Transactions

# tmadmin
...
 
> psr
Prog Name Queue Name Grp Name ID RqDone Load Done Current Service
--------- ---------- -------- -- ------ --------- --------------
ARTSTR1 00012.00200 GRP02 200 0 0 ( IDLE )
BBL           200933 KIXR 0 4 200 ( IDLE )
ARTTCPL       00001.00101 TCP00 101 0 0 ( IDLE )
ARTCNX QCNX015 GRP01 15 0 0 ( IDLE )
ARTSTRN QKIX110 GRP02 20 0 0 ( IDLE )
ARTATRN QKIXATR GRP02 30 0 0 ( IDLE )
 
> 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 0 AVAIL
disconnect cnxsvc ARTCNX GRP01 15 KIXR 0 AVAIL
connect cnxsvc ARTCNX GRP01 15 KIXR 0 AVAIL
SA03 kixsvc ARTSTRN GRP02 20 KIXR 0 AVAIL
SA02 kixsvc ARTSTRN GRP02 20 KIXR 0 AVAIL
SA01 kixsvc ARTSTRN GRP02 20 KIXR 0 AVAIL
SA00 kixsvc ARTSTRN GRP02 20 KIXR 0 AVAIL
ASYNC_QUEUE ASYNC_QUEUE ARTATRN GRP02 30 KIXR 0 AVAIL
ASYNC_SA03 atrsvc ARTATRN GRP02 30 KIXR 0 AVAIL
ASYNC_SA02 atrsvc ARTATRN GRP02 30 KIXR 0 AVAIL
ASYNC_SA01 atrsvc ARTATRN GRP02 30 KIXR 0 AVAIL
ASYNC_SA00 atrsvc ARTATRN GRP02 30 KIXR 0 AVAIL
 
> quit
{deimos:work9}-/home2/work9/demo/config/tux#{deimos:work9}-/home2/work9/demo/config/tux#

To use non-parallel asynchronous transactions, with a MAXACTIVE parameter exactly equal to one, the dedicated server is ARTATR1.

Please refer to the section describing the reasons and the installation of the ARTSTR1 server to install the ARTSTR1 server.

To check your setting, you can use also the Tuxedo tmadmin psr and psc commands

For the Simple Application example we can see that:

• The psr command shows that a new server is running ARTATR1.
• The psc command shows that no new services are running.

Listing 4‑15 tmadmin Commands Showing non-parallel Asynchronous Transactions

# tmadmin
...
 
> psr
Prog Name Queue Name Grp Name ID RqDone Load Done Current Service
--------- ---------- -------- -- ------ --------- --------------
ARTATR1 00012.00300 GRP02 300 0 0 ( IDLE )
ARTSTR1 00012.00200 GRP02 200 0 0 ( IDLE )
BBL 200933 KIXR 0 4 200 ( IDLE )
ARTTCPL 00001.00101 TCP00 101 0 0 ( IDLE )
ARTCNX QCNX015 GRP01 15 0 0 ( IDLE )
ARTSTRN QKIX110 GRP02 20 0 0 ( IDLE )
 
> 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 0 AVAIL
disconnect cnxsvc ARTCNX GRP01 15 KIXR 0 AVAIL
connect cnxsvc ARTCNX GRP01 15 KIXR 0 AVAIL
SA03 kixsvc ARTSTRN GRP02 20 KIXR 0 AVAIL
SA02 kixsvc ARTSTRN GRP02 20 KIXR 0 AVAIL
SA01 kixsvc ARTSTRN GRP02 20 KIXR 0 AVAIL
SA00 kixsvc ARTSTRN GRP02 20 KIXR 0 AVAIL
 
> quit
#

On z/OS, there are some time-related CICS START API options can be used to start a transaction at a specified time or after a specified interval, such as AT, TIME, AFTER, and INTERVAL. ART CICS Runtime provides a server, ARTSRM, for implementing these options. For more information, refer to ARTSRM Configuration in Oracle Tuxedo Application Runtime for CICS Reference Guide.

To activate this server, configure ARTSRM in the *SERVERS section in the UBBCONFIG file. You can configure a set of ARTSRM servers only if they are in the same group for each CICS region. Following is an example.

Listing 4‑16 Example of Configuring ARTSRM in UBBCONFIG

*SERVERS
…
ARTSRM
SRVGRP=ARTGRP
SRVID=500
RESTART=Y
MAXGEN=5
GRACE=3600
CLOPT="-o /home2/work9/demo/Logs/TUX/sysout/stdout_srm -e /home2/work9/demo/Logs/TUX/sysout/stderr_strn -r -- -s KIXR -l SIMPAPP"

Asynchronous transactions are launched when ASYNC_QSPACE for EXEC START is set with option INTERVAL or PROTECT.

In this case, the transaction request is deposited into a Oracle Tuxedo /Q Queue, and when the time is ready, the transaction will be automatically invoked.

For this feature to be available, these components must be configured:

1. An Oracle Tuxedo /Q Queue Space named ASYNC_QSPACE
2. An Oracle Tuxedo /Q Queue named ASYNC_QUEUE in ASYNC_QSPACE
3. The TMQUEUE and TMQFORWARD servers dedicated to these asynchronous transactions.

• Creating the Tuxedo /Q
  
• Modifying the Tuxedo ubbconfig File to Manage the Tuxedo /Q Queue
  

For unrecoverable TS Queues, no integrity is guaranteed by CICS Runtime concerning their content. For example, if an abend occurs at any point during a CICS transaction, work done on this TS is not rolled-back to the last consistency point.

TS Queues are stored in a sequential file in a dedicated directory defined in the KIX_TS_DIR UNIX environment variable. This variable is defined and then exported from the ~/.profile UNIX System File:

KIX_TS_DIR=${HOME}/trf/KIXTSDIR

Modify the Tuxedo ubbconfig file to activate the new ARTTSQ server dedicated to their management.

For these TS Queues, CICS Runtime guarantees the integrity of their content. For example, if an abend occurs at any point during a CICS transaction, they are rolled-back to the last consistency point, if all is in order, their content is committed to become a new consistency point. These TS Queues are stored in Oracle Tables to benefit from the RDBMS integrity management.

Concerning the TS Queue, there is an enhanced behavior for reading a recoverable TS Queue.

On source CICS z/OS, CICS enqueuing is not invoked for READQ TS commands, thereby making it possible for one task to read a temporary storage queue record while another is updating the same record. To avoid this, use explicit enqueuing on the temporary storage queues so that concurrent executing tasks can read and change queues with the same temporary storage identifier

This behavior also allows one transaction to see or read a record freshly written in a recoverable TS Queue, even before it is committed, and after its rollback.

On target we don't have this limitation, but in particular:

• A reading transaction is not able to see a record that is just added and not yet committed.
• A reading transaction is not able to see a modification to the record that is not yet committed.

The following topic describes how to use Recoverable TS Queues:

• To Use Recoverable TS Queues
  

This section contains the following topics:

• Transient Data Control
  
• Intra-partition Transient Data Queues
  

For intrapartition queues, CICS provides the option of automatic transaction initiation (ATI).

A basis for ATI is established by the system programmer by specifying a non-zero trigger level for a particular intrapartition destination. When the number of entries (created by WRITEQ TD commands issued by one or more programs) in the queue reaches the specified trigger level, a transaction specified in the definition of the queue is automatically initiated. Control is passed to a program that processes the data in the queue; the program must issue repetitive READQ TD commands to deplete the queue.

When the queue has been emptied, a new ATI cycle begins. That is, a new task is scheduled for initiation when the specified trigger level is again reached, whether or not execution of the earlier task has ended. The exact point at which a new ATI cycle begins depends on whether or not the queue is defined as logically recoverable. If the queue is defined with a RECOVSTATUS of No or Physical, the new ATI cycle begins when the queue is read to QZERO. But if the queue is defined with a recoverability attribute of Logical, the new ATI cycle begins only after the task terminates after having read the queue to QZERO.

If an automatically initiated task does not empty the queue, access to the queue is not inhibited. The task may be normally or abnormally ended before the queue is emptied (that is, before a QZERO condition occurs in response to a READQ TD command). If the contents of the queue are to be sent to a terminal, and the previous task completed normally, the fact that QZERO has not been reached means that trigger processing has not been reset and the same task is reinitiated. A subsequent WRITEQ TD command does not trigger a new task if trigger processing has not been reset.

This section contains the following topics:

• Tuxedo /Q
  
• Architecture Design
  
• Triggering
  

This section has the following topics:

• CICS RuntimeResource Declaration
  
• /Q Configuration for TD Queue Intrapartition in CICS Runtime
  
• qopen Parameters
  

To enable TDQ motoring, ARTTDQ server should be activated.

*SERVERS
…
ARTTDQ SRVGRP=GRP02
SRVID=40
MIN=1 MAX=1
CLOPT="-o /home2/work9/demo/Logs/TUX/sysout/stdout_tdq -e /home2/work9/demo/Logs/TUX/sysout/stderr_tdq -r -- -s KIXR -l SIMPAPP"

Where:

*SERVERS

Tuxedo ubbconfig Keyword indicating the definition of Server Section.

SRVGRP

The Tuxedo Group Name to which ARTTDQ belongs.

SRVID

The identifier of a Tuxedo Server of ARTTDQ.

MIN=1 and MAX=1

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

CLOPT

A quoted text string passed to the server containing its parameters:

-o

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

-e

Indicates the following file is used for the error output messages of the servers.

-r

Is a Tuxedo parameter used to have statistical reports.

-s KIXR

Indicates the CICS Runtime name where the transaction runs is KIXR.

-l SIMAPP

Indicates that only the components of the SIMAPP group are to be selected at start up.

Unless you wish to use the DPL in a UNIX written application, check the technical specificities of the z/OS application

1. Check on z/OS, using the CEDA system transaction, if at least one remote program is defined in the z/OS CICS CSD file. Such programs have some of their fields of the REMOTE ATRIBUTES section filed:

   Listing 4‑30 Checking for Remote Programs

   DEF PROGR
   OVERTYPE TO MODIFY CICS RELEASE = 0610
   CEDA DEFine PROGram( )
   PROGram ==>
   Group ==>
   DEscription ==>
   ....
   REMOTE ATTRIBUTES
   DYnamic ==> No No ! Yes
   REMOTESystem ==> XXXX
   REMOTEName ==> YYYYYYYY
   Transid ==> ZZZZ
   EXECUtionset ==> Dplsubset Fullapi ! Dplsubset

   Where (CICS default values are underlined):

   DYNAMIC(YES|NO)

   The following parameters cannot be overridden in the CICS LINK API. This field is only relevant for DPL use when it is set to NO and the three following fields are empty.

   REMOTESYSTEM(name)

   Remote CICS region name. An empty field is not relevant with DYNAMIC(YES)

   REMOTENAME(name)

   Remote server program name. An empty field is not relevant with DYNAMIC(YES) because the default is the client program name (PROGram ==>).

   TRANSID(name)

   Remote mirror transaction. An empty field is not relevant with DYNAMIC(YES) because the default is the mirror system transaction CSMI.

   EXECUTIONSET(FULLAPI|DPLSUBSET)

   The DPL cannot use the full CICS API but only a subset. The DPLSUBSET parameter indicates explicit usage of a DPL subset of the CICS API, but note that this subset may also be sufficient to execute LINK in a non-DPL context without errors. On the other hand, this field may contain FULLAPI in a DPL context but does not ensure that no "Invalid Request errors" will follow if non-DPL API are used.

   As described above, in some cases, the Remote Attributes declaration may not exist or can be incomplete. The reason is that these fields establish only some of the default values, some of the previous parameters in bold in the example are not provided in the EXEC CICS LINK API.

2. Then check in the programs, inside the EXEC CICS LINK API:
   • If the names of the programs called in this order match the names of programs defined in the CSD with remote attributes partially or fully informed.
   • If these statement contain at least one of the optional remote parameters shown in italics in the following CICS LINK API (the others fields are not relevant for DPL).

Listing 4‑31 CICS LINK API For DPL

EXEC CICS LINK PROGRAM(…)
COMMAREA(…)
LENGTH(…)
DATALENGTH(…)
RETCODE(…)
SYSID(XXXX) : Remote CICS region name
SYNCONRETURN : Used for remote CICS syncpoint or rollback
TRANSID(XXXX) : Remote mirror transaction instead of the CSMI default
INPUTMSG(…)
INPUTMSGLEN(…)
END-EXEC

If at least one of your programs use the DPL, install and activate the ARTDPL server without changing your other settings.

To activate this server, modify your ubbconfig file to add this server to the *SERVERS section of the Tuxedo ubbconfig file. This server belongs to the same Server Group as the Transactions Servers ( ARTSTRN, ARTSTR1, ARTATRN, ARTATR1).

Listing 4‑32 ubbconfig File Example of a *SERVERS Section Describing the ARTDPL Server.

*SERVERS
…
ARTDPL SRVGRP=GRP02
SRVID=500
CONV=N
MIN=1 MAX=1 RQADDR=QKIXDPL REPLYQ=Y
CLOPT="-o /home2/work9/demo/Logs/TUX/sysout/stdout_dpl -e /home2/work9/demo/Logs/TUX/sysout/stderr_dpl -r -- -s KIXD -l SIMPAPP"
…

Where:

*SERVERS

Tuxedo ubbconfig Keyword indicating a Server Section definition.

SRVGRP

Is the Tuxedo Group Name to which ARTDPL belongs.

SRVID

Is the identifier of a Tuxedo Server of ARTDPL.

CONV=N

Indicates that this server operates in a non-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=QKIXDPL

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 following file is used for the standard output messages of the server.

-e

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

-r

Is a Tuxedo parameter used to provide statistical reports.

-s KIXD

Indicates the CICS Runtime name where the KIXD transaction is run.

-l SIMAPP

Indicates that only the components of the SIMPDPL group are to be selected at start up.

Use the Tuxedo tmadmin psr and psc commands to check that this server is running and that no new service is published:

Listing 4‑33 tmadmin Commands to Check ARTDPL Server

# tmadmin
...
 
> psr
Prog Name Queue Name Grp Name ID RqDone Load Done Current Service
--------- ---------- -------- -- ------ --------- --------------
ARTDPL QKIXDPL GRP02 500 0 0 ( IDLE )
ARTATR1 00012.00300 GRP02 300 0 0 ( IDLE )
ARTSTR1 00012.00200 GRP02 200 0 0 ( IDLE )
BBL 200933 KIXR 0 5 250 ( IDLE )
TMS_QM GQUEUE_TMS GQUEUE 30001 0 0 ( IDLE )
TMS_ORA GRP02_TMS GRP02 30001 0 0 ( IDLE )
ARTTCPL 00001.00101 TCP00 101 0 0 ( IDLE )
TMS_QM GQUEUE_TMS GQUEUE 30002 0 0 ( IDLE )
TMS_ORA GRP02_TMS GRP02 30002 0 0 ( IDLE )
TMS_ORA GRP02_TMS GRP02 30003 0 0 ( IDLE )
TMQUEUE 01000.01010 GQUEUE 1010 0 0 ( IDLE )
ARTCNX QCNX015 GRP01 15 0 0 ( IDLE )
TMQFORWARD 01000.01020 GQUEUE 1020 0 0 ( IDLE )
ARTSTRN QKIX110 GRP02 20 0 0 ( IDLE )
ARTATRN QKIXATR GRP02 30 0 0 ( IDLE )
ARTTSQ 00012.00040 GRP02 40 0 0 ( IDLE )
 
> psc
Service Name Routine Name Prog Name Grp Name ID Machine # Done Status
------------ ------------ --------- -------- -- ------- ------ ------
TMS TMS TMS_QM GQUEUE 30001 KIXR 0 AVAIL
TMS TMS TMS_ORA GRP02 30001 KIXR 0 AVAIL
TMS TMS TMS_QM GQUEUE 30002 KIXR 0 AVAIL
TMS TMS TMS_ORA GRP02 30002 KIXR 0 AVAIL
TMS TMS TMS_ORA GRP02 30003 KIXR 0 AVAIL
ASYNC_QSPACE TMQUEUE TMQUEUE GQUEUE 1010 KIXR 0 AVAIL
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 0 AVAIL
disconnect cnxsvc ARTCNX GRP01 15 KIXR 0 AVAIL
connect cnxsvc ARTCNX GRP01 15 KIXR 0 AVAIL
SA03 kixsvc ARTSTRN GRP02 20 KIXR 0 AVAIL
SA02 kixsvc ARTSTRN GRP02 20 KIXR 0 AVAIL
SA01 kixsvc ARTSTRN GRP02 20 KIXR 0 AVAIL
SA00 kixsvc ARTSTRN GRP02 20 KIXR 0 AVAIL
ASYNC_QUEUE ASYNC_QUEUE ARTATRN GRP02 30 KIXR 0 AVAIL
ASYNC_SA03 atrsvc ARTATRN GRP02 30 KIXR 0 AVAIL
ASYNC_SA02 atrsvc ARTATRN GRP02 30 KIXR 0 AVAIL
ASYNC_SA01 atrsvc ARTATRN GRP02 30 KIXR 0 AVAIL
ASYNC_SA00 atrsvc ARTATRN GRP02 30 KIXR 0 AVAIL
TSQUEUE tsqsvc ARTTSQ GRP02 40 KIXR 0 AVAIL
 
> quit
#

To allow an application to use distributed programs called in EXEC CICS LINK statements, these programs must be declared to CICS Runtime.

1. To declare REMOTE programs which can only use the DPL Subset of the CICS API:
   • In the programs.desc file, set REMOTESYSTEM (the 7th field of the csv format dataset), to remote SYSID name (KIXD in sample of Listing 4‑32).

     The default is local (empty field), meaning that local programs are declared because they can use the FULL CICS API

     In our Simple Application example, if we suppose that RSSAT000, RSSAT001 are remote and RSSAT002 and RSSAT003 are local, then the programs.desc file is set to:

     Listing 4‑34 Simple Application programs.desc Configuration of Remote Programs

     #PROGRAM;GROUP;DESCRIPTION;LANGUAGE;EXECKEY;STATUS;REMOTESYSTEM;REMOTENAME
     RSSAT000;SIMPAPP;Home Menu Program of Simple Application;COBOL; ;ENABLE;KIXD
     RSSAT001;SIMPAPP;Customer Detailed Inf Program of Simple Application;COBOL; ;ENABLE;KIXD
     RSSAT002;SIMPAPP;Customer Maintenance Program of the Simple Application;COBOL; ;ENABLE
     RSSAT003;SIMPAPP;Customer List of the Simple Application;COBOL; ;ENABLE

2. Shutdown and reboot Tuxedo.
3. Using the Tuxedo tmadmin psr and psc commands, check that new services for DPL programs are published and managed by ARTDPL: KIXD_RSSAT0001 and KIXD_RSSAT0003.

   Note:

   To avoid problems with homonyms, these distributed services have their names composed of the Tuxedo DOMAINID defined in the ubbconfig and the name of the program they manage.

Listing 4‑35 Using tmadmin Commands to Check DPL Services

{deimos:work9}-/home2/work9/demo/Logs/TUX/sysout# tmadmin
...
 
> psr
Prog Name Queue Name Grp Name ID RqDone Load Done Current Service
--------- ---------- -------- -- ------ --------- ---------------
ARTDPL QKIXDPL GRP02 500 0 0 ( IDLE )
ARTATR1 00012.00300 GRP02 300 0 0 ( IDLE )
ARTSTR1 00012.00200 GRP02 200 0 0 ( IDLE )
BBL 200933 KIXR 0 5 250 ( IDLE )
TMS_QM GQUEUE_TMS GQUEUE 30001 0 0 ( IDLE )
TMS_ORA GRP02_TMS GRP02 30001 0 0 ( IDLE )
ARTTCPL 00001.00101 TCP00 101 0 0 ( IDLE )
TMS_QM GQUEUE_TMS GQUEUE 30002 0 0 ( IDLE )
TMS_ORA GRP02_TMS GRP02 30002 0 0 ( IDLE )
TMS_ORA GRP02_TMS GRP02 30003 0 0 ( IDLE )
TMQUEUE 01000.01010 GQUEUE 1010 0 0 ( IDLE )
ARTCNX QCNX015 GRP01 15 0 0 ( IDLE )
TMQFORWARD 01000.01020 GQUEUE 1020 0 0 ( IDLE )
ARTSTRN QKIX110 GRP02 20 0 0 ( IDLE )
ARTATRN QKIXATR GRP02 30 0 0 ( IDLE )
ARTTSQ 00012.00040 GRP02 40 0 0 ( IDLE )
 
> psc
Service Name Routine Name Prog Name Grp Name ID Machine # Done Status
------------ ------------ --------- -------- -- ------- ------ ------
KIXD_RSSAT0+ dplsvc ARTDPL GRP02 500 KIXR 0 AVAIL
KIXD_RSSAT0+ dplsvc ARTDPL GRP02 500 KIXR 0 AVAIL
TMS TMS TMS_QM GQUEUE 30001 KIXR 0 AVAIL
TMS TMS TMS_ORA GRP02 30001 KIXR 0 AVAIL
TMS TMS TMS_QM GQUEUE 30002 KIXR 0 AVAIL
TMS TMS TMS_ORA GRP02 30002 KIXR 0 AVAIL
TMS TMS TMS_ORA GRP02 30003 KIXR 0 AVAIL
ASYNC_QSPACE TMQUEUE TMQUEUE GQUEUE 1010 KIXR 0 AVAIL
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 0 AVAIL
disconnect cnxsvc ARTCNX GRP01 15 KIXR 0 AVAIL
connect cnxsvc ARTCNX GRP01 15 KIXR 0 AVAIL
SA03 kixsvc ARTSTRN GRP02 20 KIXR 0 AVAIL
SA01 kixsvc ARTSTRN GRP02 20 KIXR 0 AVAIL
SA00 kixsvc ARTSTRN GRP02 20 KIXR 0 AVAIL
ASYNC_QUEUE ASYNC_QUEUE ARTATRN GRP02 30 KIXR 0 AVAIL
ASYNC_SA03 atrsvc ARTATRN GRP02 30 KIXR 0 AVAIL
ASYNC_SA01 atrsvc ARTATRN GRP02 30 KIXR 0 AVAIL
ASYNC_SA00 atrsvc ARTATRN GRP02 30 KIXR 0 AVAIL
TSM00004_TSQ tsqsvc ARTTSQ GRP02 40 KIXR 0 AVAIL
TSM00003_TSQ tsqsvc ARTTSQ GRP02 40 KIXR 0 AVAIL
TSM00002_TSQ tsqsvc ARTTSQ GRP02 40 KIXR 0 AVAIL
TSM00001_TSQ tsqsvc ARTTSQ GRP02 40 KIXR 0 AVAIL
TSM00000_TSQ tsqsvc ARTTSQ GRP02 40 KIXR 0 AVAIL
TSQUEUE tsqsvc ARTTSQ GRP02 40 KIXR 0 AVAIL
 
> quit
# .

To reduce the scope of the services listed to only those managed by ARTDPL (SRVID=500), use the Tuxedo psc command followed with the -i srvid parameter to restrict the display to a particular server id.

In our example, the srvid of the ARTDPL server is 500 as displayed just above.

Listing 4‑36 Using tmadmin Commands to Check Specific DPL Service in Verbose Mode

# tmadmin
...
 
> verbose
Verbose now on.
 
> psc -i 500
Service Name: KIXD_RSSAT003
Service Type: USER
Routine Name: dplsvc
Prog Name: /home2/work9/KIXEDO/bin/ARTDPL
Queue Name: QKIXDPL
Process ID: 1327244, Machine ID: KIXR
Group ID: GRP02, Server ID: 500
Current Load: 50
Current Priority: 50
Current Trantime: 30
Current Blocktime: 0
Current BUFTYPECONV: 0
Requests Done: 0
Current status: AVAILABLE
 
Service Name: KIXD_RSSAT001
Service Type: USER
Routine Name: dplsvc
Prog Name: /home2/work9/KIXEDO/bin/ARTDPL
Queue Name: QKIXDPL
Process ID: 1327244, Machine ID: KIXR
Group ID: GRP02, Server ID: 500
Current Load: 50
Current Priority: 50
Current Trantime: 30
Current Blocktime: 0
Current BUFTYPECONV: 0
Requests Done: 0
Current status: AVAILABLE
 
> quit
#

1. Contact your z/OS CICS Administrator to know the size of memory implemented. (For your information this value is defined with the parameter WRKAREA of the DFHSIT. The default value is 512 bytes and the size can vary from 0 to 3584 bytes). Another way is to calculate the biggest size of the data record contained in the programs addressing the CWA
2. Modify your ~/.profile UNIX system file to export a new CICS Runtime variable, KIX_CWA_SIZE, and set it to the value found in the WRKAREA of the DFHSIT. If this variable is not declared, note that the default value is 0 and the authorized interval from 0 to 32760 bytes.

   Example:

   KIX_CWA_SIZE=512

3. Modify your ~/.profile UNIX system file to export a new CICS Runtime variable, KIX_CWA_IPCKEY, and valorize it to a Unix IPC key to define the cross memory segment used as CWA.

   Example:

   KIX_CWA_ IPCKEY=200944

4. Restart Tuxedo to take all these changes into account.

The programs within a transaction run by ARTDPL now can access TWA with following steps:

1. Modify the CICS Runtime transactions.desc file to configure TWA Size needed for ARTDPL transaction.
   Listing 4‑41 Configuration of TWA for ARTDPL in the transactions.desc File

   #Transaction;Group;Description;Program; ; ; ; ; ; ;Status; ; ; ;Tranclass ;TWA Size
   CPMI;SIMPAPP;pg for simpapp;DFHMIRS; ; ; ; ; ; ;ENABLED; ; ; ; ;100

   DFHMIRS is the internal mirror program in CICS that handles inbound function shipping. In CICS RT, this mirror program should be defined under the transaction used to run the linked program in the transaction resource file if TWA is used. In the list, ARTDPL runs remote linked program under transaction named CPMI and it has TWA size equal to 100.

   Note:

   Users should not name application program as DFHMIRS
2. Restart the CICS Runtime Tuxedo servers and the modifications can be seen in ARTDPL stdout file.
   Listing 4‑42 stdout_dpl TWA Example

   |---------------------------------|
   | TRANSACTIONS loaded : < 1> |
   |----------------------------------------------|----|-|-|---|-|-|----------|-----|-|--------|-----|---|
   | | | | |C|C| |R|R| | |T| | | |
   |TRAN| GROUP | PROGRAM |ALIA|M|O|PRI|E|E| STATUS |TASK |R| TRAN | TWA |MAX|
   | | | | |D|N| |S|S| |DATA |A| CLASS | SIZ |ACT|
   | | | | |S|F| |S|T| |KEY |C| | |IVE|
   |----|----------|------------------------------|----|-|-|---|-|-|----------|-----|-|--------|-----|---|
   |CPMI|SIMPAPP |DFHMIRS | |N|N|001|N|N|ENABLED |USER |Y| |00100|999|
   |-----------------------------------------------------------------------------------------------------|

The ART CICS Transaction Trigger Monitor (ARTCKTI) behaves the same as the CICS CKTI transaction. It listens on one or multiple WebSphere MQ initiation queues, retrieves trigger messages when a trigger event occurs, and then forwards the trigger messages to the target transaction.

• Work Flow
  
• Command Configuration
  
• Configuring WebSphere MQ Servers to Trigger ART for CICS Transactions
  

Before rebuilding the CICS transaction servers, you need to prepare the WebSphere MQ RM Definitions, as discussed in this section. If ART for CICS transaction servers use different modes to access the WebSphere MQ, then you must perform the tasks described later in this section and upgrade Oracle Tuxedo after rebuilding the servers.

• Prepare WebSphere MQ RM Definitions
  
• Rebuild TMS_MQM Server
  
• Rebuild ART for CICS Transaction Servers
  
• Rebuild ARTCKTI Server
  
• Update Oracle Tuxedo UBBCONFIG and OPENINFO
  

For proper connection to WebSphere MQ, the sequence is MQCONN, MQOPEN, MQxxx (GET/PUT), MQCLOSE, and MQDISC. In mainframe CICS, MQCONN and MQDISC are often handled by CICS as resource management functions and applications only do MQOPEN/MQxxx/MQCLOSE.

To support this in ART for CICS, we use ART for CICS pre-processor to convert MQOPEN/MQCLOSE calls to KIX_MQxxxx wrappers, which then handle MQCONN and MQDISC under the covers. This approach also enables ART for CICS to handle connection issues and re-connect if necessary. Check the pre-processor output to verify that KIX_MQxxx calls are there.

In terms of the MQ wrapper, MQ wrapper can help CICS transaction to recycle or free the MQ connection if the CICS transaction does not do this itself. prepro-cics.pl introcues a switch MQ_wrapper to enable this MQ wrapper. For every application server (for example, ARTSTR*/ARTATR*/ARTDPL), CLOPT -m queue_manager_name is introduced to specify the target MQ Manager, because MQ wrapper can help to do the MQCONNECT before MQOPEN but MQCONNECT needs to know which MQ Manager that it should connect to. For more information, see MQ_wrapper and WebSphere MQ Queue Manager Name.

When using local WebSphere MQ client for remote connection to z/OS based MQ Manager, the EBCDIC-to-ASCII conversion is not automatically enabled. It can be enabled by setting MQGMO-CONVERT flag in MQGET options as shown in example below.

Listing 4‑45 Example for MQGMO-CONVERT

COMPUTE MQGMO-OPTIONS = MQGMO-WAIT
+ MQGMO-SYNCPOINT
+ MQGMO-FAIL-IF-QUIESCING
+ MQGMO-CONVERT
END-COMPUTE.

For MQPUT the ASCII-to-EBCDIC conversion is done automatically if MQMD-FORMAT is set to MQFMT-STRING. For example,

MOVE MQFMT-STRING TO MQMD-FORMAT.

When using local WebSphere MQ server, with channel defined as SENDER, transcoding can be done without program change by adding CONVERT (YES) on the channel definition.

Oracle Tuxedo ART Workbench adapts COBOL programs to target environment, in part by changing some mainframe numeric data types (BINARY/COMP) to compatible data type COMP-5, which is the native equivalent. This is transparent in COBOL applications.

However, on Linux, for Websphere MQ libraries this can cause an issue as they require the use of BINARY types in the parameters passed in MQ calls. Similar data type mapping is done by Pro*COBOL pre-processor.

Therefore, change the WebSphere MQ interface definitions from COMP-5 back to BINARY before the final compile stage. See an example of the changed MQ interface definitions (BINARY data type).

Listing 4‑46 Example of the Changed MQ Interface Definitions (BINARY Data Type)

01 QM-NAME PIC X(48) VALUE SPACES.
01 HCONN PIC S9(9) BINARY.
01 Q-HANDLE PIC S9(9) BINARY.
01 OPTIONS PIC S9(9) BINARY.
01 COMPLETION-CODE PIC S9(9) BINARY.
01 OPEN-CODE PIC S9(9) BINARY.
01 REASON-CODE PIC S9(9) BINARY.
01 CONN-REASON PIC S9(9) BINARY.
01 USER-DATA-LENGTH PIC S9(9) BINARY.
01 DATA-LENGTH PIC S9(9) BINARY.
01 TOTAL-NUM PIC S9(9) BINARY.

ART for CICS provides a system transaction, whose program name is DFHALST, to get and show application list for a user when doing multiple session management. The transaction calls a user plug-in to get the list.

You should provide this plug-in, and place the library in the correct library path so that DFHALIST can call it. For more information about this plug-in, see CICS Runtime Integration with Application List Transaction in Oracle Tuxedo Application Runtime for CICS Reference Guide.

The following topics describe how to configure the CICS Runtime Configuration file:

• Transaction Configuration File
  
• System Configuration File
  

You should enable security to do multiple session management. For more information, see Security Configuration of the CICS Runtime.

You should configure the following servers to UBBCONFIG. See the listing below for an example.

• ARTTCPL, specifying its -t option. For more information, ARTTCPL/ARTTCPH Configuration in Oracle Tuxedo Application Runtime for CICS Reference Guide.
• ARTCNX, specifying its SYSID.
• ARTSRM (to prevent the same user connects to ART for CICS via different terminals).
• ARTSTRN (to run application list transaction and user transactions).

Listing 4‑47 Example of Configuring UBBCONFIG

* SERVERS
ARTTCPL
SRVGRP=TCP00
SRVID=101
CLOPT=" -- -M 4 -m 1 -L //hostname:34582 -n //hostname:34583 -t ALST"
 
ARTCNX
SRVGRP=GRP01
SRVID=15
CONV=Y
MIN=1 MAX=1 RQADDR=QCNX015 REPLYQ=Y
CLOPT="-o /home2/work9/demo/LOGS/sysout/stdout_cnx -e /home2/work9/demo /LOGS/sysout/stderr_cnx -r -- -s KIXR "
 
ARTSRM
SRVGRP=GRP02
SRVID=18
MIN=1 MAX=1
CLOPT="-o /home2/work9/demo/LOGS/sysout/stdout_srm -e /home2/work9/demoLOGS/sysout/stderr_srm -r -- -s KIXR -l SIMPAPP"
 
ARTSTRN
SRVGRP=GRP02
SRVID=20
CONV=Y
MIN=2 MAX=10 RQADDR=QKIX110 REPLYQ=Y
CLOPT="-o /home2/work9/demo/LOGS/sysout/stdout_strn -e /home2/work9/demo/LOGS/sysout/stderr_strn -r -- -s KIXR -l SIMPAPP"

Boot the application, and connect to ART for CICS through a 3270 terminal. When you complete sign on, ART for CICS runs application list transaction (ALST) automatically, which shows you the application list.

Figure 4-5 ART for CICS Application List Transaction (ALST)

• Starting Sessions
  
• Switching Sessions
  
• Ending Sessions
  

CICS TCP/IP socket API is a collection of socket calls that enable you to perform the following primary communication functions between application programs.

• Set up and establish connections to other users on the network
• Send and receive data to and from other users
• Close down connections

In addition to these basic functions, these APIs enable you to:

• Interrogate the network system to get names and status of relevant resources
• Perform system and control functions as required

ART for CICS supports the above functions as well, providing a set of C APIs and extended COBOL APIs. The following table lists the supported C APIs; the last three functions are provided by ART for CICS while other functions can use OS socket library directly.

The following lists the supported extended COBOL APIs:

The image below shows the sequence of CICS Runtime commands and socket calls involved in setup. CICS Runtime commands are prefixed by EXEC CICS; all other numbered items in this figure are ART for CICS TCP/IP calls.

Figure 4-6 The Client-Listener-Server Application Set

In this case, "Client" might be running TCP/IP under the OS/2 operating system or one of the various UNIX operating systems such as AIX*. "CICS Runtime Server ARTCSKL" and "ARTATRN/ARTATR1" processes both run under ART for CICS TCP/IP.

• Client Call Sequence
  
• Listener Call Sequence
  
• User Transaction Running in ARTATRN/ARTATR1 Call Sequence
  

This chapter contains the following topics:

• Description
  
• ARTCSKL Input Format
  
• ARTCSKL Output Format
  

To use ART for CICS TCP/IP Socket Interface functions, you should

• Declare resources on ART for CICS TCP/IP socket listener configuration file (listener.desc). For more information, seeTCP/IP Socket Listener Configuration File (listener.desc) in Oracle Tuxedo Application Runtime for CICS Reference Guide.

• Configure CICS Runtime server ARTCSKL and ARTATRN/ARTATR1. CICS Runtime server ARTCSKL and ARTATRN/ARTATR1 should be configured on the same machine. For more information about ARTCSKL and ARTATRN/ARTATR1 servers, see Oracle Tuxedo Application Runtime for CICS Reference GuideOracle Tuxedo Application Runtime for CICS Reference Guide

It is required to configure ARTSRM. For more information, please refer to ARTSRM Configuration.

It is required to set environment variable ISC_ENABLE to YES. For more information, please refer to ISC_ENABLE.

The following configurations are required:

• system.desc
  
• transactions.desc and programs.desc
  
• terminals.desc (Optional)
  
• UBB Declaration
  
• Environment Variable Declaration
  

After a successful boot up, users can connect to ART CICS, and then logon screen prompts out for users to specify the CICS region (APPLID) to logon.

Figure 4-9 Logon Screen

ART CICS supports DTP connections in multiple ART CICS regions through APPC mapped and LUTYPE6.1 protocol. On this view, COBOL applications using DTP (APPC/LUTYPE6.1) verbs can be deployed to ART CICS directly after being translated by Oracle Tuxedo Application Rehosting Workbench.

ART CICS also supports integration with Oracle TMA to enable DTP connections between ART CICS region and Mainframe CICS region through APPC. Following is a typical end-to-end user case.

Figure 4-10 Typical End-to-End User Case

In this scenario, there are three ART CICS regions, KIXA, KIXB, and KIXC, among which KIXA and KIXB communicates with each other via APPC protocol, and KIXA and KIXC communicates with each other via LU61 protocol.

Besides, there is another CICS region called CICA on Mainframe, which communicates with either KIXA or KIXB via APPC protocol.

As shown in figure above, the conversations occur in these regions are:

• Conversations among ART CICS regions
  • APPC conversation, issued from the terminal in KIXA, to KIXB
    • KVA0 KIXB KVA5
    • KVA2 KIXB KVA5
  • LU61 conversation, issued from the terminal in KIXA, to KIXC
    • RV60 KIXC RV65
• Conversations between ART CICS region and Mainframe CICS region through TMA
  • APPC outbound conversation issued from the terminal in KIXA to CICA
    • KVA0 CICA KVA5
    • KVA2 CICA KVA5
  • APPC inbound conversation issued from the terminal in CICA to KIXB
    • KVA0 CRM1 KVA5
    • KVA2 CRM1 KVA5

  Note:

  CRM1 is a connection from CICA to TMA LU

• Configurations
  

On z/OS, asynchronous processing refers to a START command that starts a transaction on a remote system. ART CICS Runtime supports implementing this feature using the START command with a SYSID option.

The following sections describe the configuration tasks you need to perform:

• Defining Regions in system.desc
  
• Configuring ARTSRM Server
  
• Modifying the UBBCONFIG File
  

ART CICS Runtime supports invoking a synchronous transaction, which resides on a remote CICS system. To implement this feature, the following configurations are required:

• Configuring Environment Variables
  
• Defining Regions in system.desc
  
• Modifying the UBBCONFIG File
  

On z/OS, CICS programs can submit JCL/KSH job by the WRITEQ TD command and pass the JCL/KSH job statements to JES internal reader by TDQ. ART CICS Runtime supports this function by using the special TDQ definition and the internal service advertised by TuxJES system.

Before using this feature, make sure ART Batch Runtime and TuxJES environment is set up. For more information, refer to Using Tuxedo Job Enqueueing Service (TuxJES).

• Configuring the UBBCONFIG File
  
• Configuring tdqextra.desc
  

On z/OS, CICS programs can submit JCL/KSH job by SPOOLWRITE command and pass the JCL/KSH job statements to JES internal reader by SPOOL. ART for CICS supports this function by using the internal service advertised by TuxJES system.

Before using this feature, make sure ART Batch Runtime and TuxJES environment is set up. For more information, refer to Using Tuxedo Job Enqueueing Service (TuxJES).

• Configuring SPOOL Related Environment Variables
  

Follow this work flow to implement artcicsutil utility in End-to-End mode (use IPCP commend set here for example).

• Using ART for Workbench to convert JCL to KSH
  
• Configuring UBBCONFIG in CICS Runtime Domain
  
• Configuring Resource Files
  
• Configuring DMCONFIG in ART for CICS Domain and ART for Batch Domain
  

This use case describes the way to invoke artcicsutil utility in interactive mode. In this example, transaction EQDQ is started.

> artcicsutil -t native
> start EQDQ
start trans:
transaction ' EQDQ'
trmid ''
from ''
start trans done.

Before using either of the methods to implement printing, you need to perform the following configuration tasks:

1. Configure the printer terminal definition in typeterms.desc. Following is an example:

   Listing 4‑67 Example of Configuring Printer Terminal Definition in typeterms.desc

   [typeterm]
   name=IBM-3287-1
   color=YES
   defscreencolumn=80
   defscreenrow=24
   description="IBM 327x family printer"
   hilight=YES
   logonmsg=NO
   outline=NO
   swastatus=ENABLED
   uctran=NO
   userarealen=100

   Note:

   ART CICS does not support the alternate size for printer, so the following attributes must not be defined in typeterms.desc for IBM-3287-1: scrnsize=alternate, altscreenrow, and altscreencolumn
2. Configure the printer transactions to the class that will never be executed concurrently:

   For example:

   TRCLASS1;UNIGRP; A tranclass bidon for UNIGRP; 1
3. Configure the printer program definition to the ARTSTR1 program group in transactions.desc.

   For example:

   PRNT;UNIGRP;pg for ARTSTR1; PRNTPROG; ; ; ; ; ; ;ENABLED; ; ; ;TRCLASS1
4. Configure the printer program to the ARTSTR1 program group in programs.desc.

   For example:

   PRNTPROG;UNIGRP;pg for UNIGRP;COBOL; ;ENABLED

5. Define a printer terminal in terminals.desc to indicate the printer LUNAME and TERMID

   For example:

   [terminal]

   name=PRT1

   netname=CICSPRT1

   group=UNIGRP

6. Configure the printer program group to the ARTSTR1 program group using CLOPT -l option in UBBCONFIG

   For example:

   CLOPT="-o stdout_str1 -e stderr_str1 -r -- -s KIXR - UNIGRP"
7. Do one of the following to specify a printer device:
   • If you use a wc3270 client as the printer terminal, configure the terminal type to IBM-3287-1

     For example:

     -tn IBM-3287-1

   • If you use a PCOM client as the printer terminal, configure a LUNAME in the Telnet3270 interface and set the Session Type to Printer in the Session Parameters interface, as shown in following figures:

Figure 4-11 Configure a LUNAME

Figure 4-12 Setting the PCOM Session Type

The following figure depicts Printing with a START Command

Figure 4-13 Printing with a START Command

The figure above shows a typical user case. The procedure to implement printing with a START command in such scenario are as follows:

1. Configure the Pcomm terminal to connect to an external printer device.
2. Establish the connection from the Printer terminal to ART TCP with the LUNAME you specified previously.
3. Establish the connection from the Display terminal to ART CICS, and start a transaction A from the Display terminal.
4. Transaction A invokes an asynchronous transaction B with the START command, and specifies the TERMID as one of the LUNAME defined previously.
5. Transaction B invokes a BMS or terminal control command, then sends the command application data to the printer terminal, and finally the Printer terminal sends the print job to the connected external printer device for printing.

To implement printing with transient data, do the following:

1. Configure ATIFACILITY and FACILITYID in tdqintra.desc, as follows:
   Listing 4‑68 Example of Configuring ATIFACILITY and FACILITYID in tdqintra.desc

   # TDQUEUE;GROUP;DESCRIPTION;RECOVSTATUS;TRANSID;TRIGGERLEVEL;USERID;WAIT;WAITACTION;QSPACENAME;TRT;ATIFACILITY;FACILITYID
   MTI1;SIMPAPP;TDQ FOR PRINTER;;BBBB;1;;;;;;T;PRT2

2. Define PRT2 in terminals.desc
   For example:

   [terminal]
   name=PRT2
   netname=CICSPRT2
   group=UNIGRP

3. After ART CICS is started, establish the connection between PCOMM (printer with the specified LUNAME= CICSPRT2) and ART CICS.
4. For ATI users, configure a /Q as follows:

   qcreate MTI1 fifo none 2 30 1m 0m "TDI_TRIGGER -q queue_name -d space_name"

   When the ATI trigger level is reached, TDI_TRIGGER client will be invoked, and the -q and -d options will notify ART CICS to start a transaction associated queue_name and space_name on the terminal PRT2.

Convert your WSDL file into the Oracle Tuxedo metadata repository input file (MIF) using the Oracle SALT command utility, wsdlcvt. Specify its -C option to generate COPYBOOK. For more information, see Configuring an Oracle SALT Application..

Use cpy2record tool to generate RECORD definition from the COPYBOOK that the previous step generates, and export environment variable for RECORD. For more information, see Using a RECORD Typed Buffer.

Build SALT configuration file (using Oracle Tuxedo SALT utility wsloadcf), and loads service information into an Oracle Tuxedo service metadata repository (using tmloadrepos). For more information, see Configuring an Oracle SALT Application.

Add a service section in webservice.desc configuration file, specifying REQUEST and RESPONSE in webservice.desc. The following listing below shows an example:

Listing 4‑69 Example of webservice.desc Configuration

[DFH0XCMNOperation]
REQUEST=DFH0XCMNOperation
RESPONSE=DFH0XCMNOperationResponse
TRANSACTION=N

Configure the TMMETADATA and GWWS servers in the UBBCONFIG file. The following listing shows an example:

Listing 4‑70 Example of Adding TMMETADATA and GWWS in UBBCONFIG

*SERVERS
...
TMMETADATA SRVGRP=GROUP2 SRVID=2 CLOPT="-A -- -f pmu.repos"
GWWS SRVGRP=GROUP2 SRVID=3 CLOPT="-A -r -- -iGWWS1"

In Tuxedo SALT deployment file, configure REST outbound service for each HTTP endpoint you want to access. You should set "outputbuffer" (of "Service" element) to "CARRAY", and specify "enableCustomHTTPHeaders" and "enableHTTPRequestLine" properties to enable the support for WEB WRITE/READ HTTPHEADER, WEB EXTRACT HTTPMETHOD/QUERYSTRING/... and so on. The following listing is an example.

Also, you should define and load other required Tuxedo SALT configurations, such as WSDF and Metadata configuration. See SALT Deployment File Reference for more information.

Listing 4‑71 Example for Defining REST Outbound Service in SALT

<GWInstance id="GWWS1">
<Outbound>
<HTTP>
<Service name="TOUPPOST"
content-type="XML"
method="POST"
address="http://demobox:8080/ARTCICS/DEMOS/TOUPSVR"
outputbuffer="CARRAY"/>
</HTTP>
</Outbound>
<Properties>
<Property name="enableMultiEncoding" value="true"/>
<Property name="enableCustomHTTPHeaders" value="true"/>
<Property name="enableHTTPRequestLine" value="true"/>
</Properties>

Add an entry in URIMAP configuration file urimaps.desc. For example:

TOUPPOST;SIMPAPP; demo test; ENABLED ; /ARTCICS/DEMOS/TOUPSVR; HTTP ; CLIENT; demobox; 8080; ; TOUPPOST

Configure ART transaction servers to run user program, and configure Tuxedo SALT TMMETADATA and GWWS in UBBCONFIG. For example:

Listing 4‑72 Example for Modifying UBBCONFIG

ARTSTRN
SRVGRP=GRP02
SRVID=20
CONV=Y
MIN=1 MAX=1
CLOPT="-o /home/demo/restclnt/LOGS/sysout/stdout_strn -e /home/demo/restclnt/LOGS/sysout/stderr_strn -r -- -s KIXR -l SIMPAPP"
……
TMMETADATA SRVGRP=GROUP2 SRVID=2 CLOPT="-A -- -f artcics.repos"
GWWS SRVGRP=GROUP2 SRVID=3 CLOPT="-A -r -- -iGWWS1"

In Tuxedo SALT deployment file, configure REST inbound service you want to expose to HTTP client. You should set the "inputbuffer" (of "Method" element) to "CARRAY", specify "enableCustomHTTPHeaders" and "enableHTTPRequestLine" properties to enable support for WEB WRITE/READ HTTPHEADER, WEB EXTRACT HTTPMETHOD /QUERYSTRING/... and so on. The following listing is an example.

Also, you should define and load other required Tuxedo SALT configurations, such as WSDF and Metadata configuration. See the SALT Deployment File Reference for more information.

Listing 4‑73 Example for Defining REST Inbound Service in SALT

<GWInstance id="GWWS1">
<Inbound>
<HTTP>
<Network http="demobox:8080"/>
<Service name="ARTCICS/DEMOS/TOUPSVR">
<Method name="POST" service="KIXR_TOUPSVR" inputbuffer="CARRAY"/>
</Service>
</HTTP>
</Inbound>
<Properties>
<Property name="enableMultiEncoding" value="true"/>
<Property name="enableCustomHTTPHeaders" value="true"/>
<Property name="enableHTTPRequestLine" value="true"/>
</Properties>
</GWInstance>

Configure ARTDPL to run user web aware programs, and configure Tuxedo SALT TMMETADATA and GWWS in UBBCONFIG. For example:

Listing 4‑74 Example for Modifying UBBCONFIG

ARTDPL
SRVGRP=GRP02
SRVID=60
MIN=1 MAX=1
CLOPT="-o /home/demo/restsvr/LOGS/sysout/stdout_dpl -e /home/demo/restsvr/LOGS/sysout/stderr_dpl -r -- -s KIXR -l SIMPAPP"
……
TMMETADATA SRVGRP=GROUP2 SRVID=2 CLOPT="-A -- -f artcics.repos"
GWWS SRVGRP=GROUP2 SRVID=3 CLOPT="-A -r -- -iGWWS1"

• int ARTKIX__svrinit_callback(ARTKIX_SRVINIT_PARA*) (at Server Initiation)
• void ARTKIX__svrdone_callback() (at Server Shutdown)

We recommend you put this shared library under the directory where the CICS Runtime product is installed. (Environment variable $KIXDIR is used to declare this directory. Usually it is $KIXDIR/lib directory.) When you do it, do not remove this shared library from this directory when your Oracle Tuxedo Application Runtime for CICS is updating or migrating.

Oracle Tuxedo Application Runtime for CICS provides you a user header file called artkixcallback.h (published in directory $KIXDIR/include) to help you develop your shared library. It defines the following enumeration inside the header file.

Listing 4‑75 User Header File artkixcallback.h

typedef enum artkix_svrtype
{
e_ARTKIX_STR1, // for Synchronous Transaction server type
e_ARTKIX_STRN,
e_ARTKIX_ATR1, // this is for Asynchronous Transaction servers type
e_ARTKIX_ATRN,
e_ARTKIX_CTR1, // for Converse Management server type
e_ARTKIX_CTRN,
e_ARTKIX_WTR1, // for Non-3270s Terminal server type
e_ARTKIX_WTRN,
e_ARTKIX_DPL // for Distributed Program Link server type
} ARTKIX_SVRTYPE;

• int ARTKIX__svrinit_callback(ARTKIX_SRVINIT_PARA*) (at Server Initiation)
  
• void ARTKIX__svrdone_callback() (at Server Shutdown)
  

Include your customized C library in $LD_LIBRARY_PATH for Linux/Solaris (or $LIBPATH for AIX). This library will be loaded dynamically in the runtime.

If ART for CICS application servers cannot find any customized shared library in the above paths, this feature is disabled but these servers can still successfully start up.

If you want to create a shared memory used when ARTDPL server starts up, you need to create a shared library named libkixcallback.so, which exports two callback functions, and place the extended shared library under $KIXDIR/lib/ directory. For more information, see Create Shared Library libkixcallback.so.

When the ARTDPL server starts up, it searches this extended shared library under $KIXDIR/lib at first. If it cannot find it, it continues to search $LD_LIBRARY_PATH for Linux/Solaris (or $LIBPATH for AIX). After finding this shared library, the ARTDPL server loads it.

At this server initiation, you can create your shared memory. If the function fails, it returns nonzero and then the ARTDPL server cannot start up; if the function succeeds, it returns zero and then the ARTDPL server starts up as usual.

If you want to open some database tables on your Linux platform when an ARTDPL server starts up, you need to create a named libkixcallback.so shared library, which exports two callback functions, and make sure the pathname of this C shared library is included in $LD_LIBRARY_PATH environment variable. For more information, see Create Shared Library libkixcallback.so.

When the ARTDPL server starts up, it searches this customized shared library under $KIXDIR/lib. If it cannot find it, it continues to search under $LD_LIBRARY_PATH. After finding this shared library, the ARTDPL server loads it.

When the shared library is initiated, you can open your database tables. If the function fails, it returns nonzero and then the ARTDPL server cannot start up; if the function succeeds, it returns zero and then the ARTDPL server starts up as usual.

If ART for CICS user A wants to debug COBOL Program1 and ART for CICS user B wants to debug COBOL Program2, the two users should do the following:

1. Add COBOL debug information into kix_cobol_dbg.cfg configuration file.

   myAnimSrvID1;;;;; Program1

   myAnimSrvID2;;;;; Program2

2. Input anim command lines.
   • User A inputs the following command line from his/her terminal.

     anim %XmyAnimSrvID1

   • User B inputs the following command line from his/her terminal.

     anim %XmyAnimSrvID2

3. User A and B either start up their own ART for CICS application servers with the same Linux account which starts up the anim utility, or dynamically change the debug configuration resource file without restarting the ART for CICS servers.

   Note:

   The Linux user account that starts up the ART for CICS server must be the same as the Linux user account that runs the anim command line. Only the ANIMSRVID which the anim utility specifies will be debugged.

If one ART for CICS user wants to debug two different COBOL programs in one transaction (for example, if ART for CICS user wants to debug COBOL Program1 and COBOL Program2, and both programs are in the same transaction), do the following:

1. Add COBOL debug information into kix_cobol_dbg.cfg configuration file.

   myAnimSrvID1;;;;transaction1;

2. Input the following command line in one terminal, and then both programs can be debugged.

   anim %XmyAnimSrvID1

If one ART for CICS user wants to debug two different COBOL programs with START TRANSID command, do the following:

1. Add COBOL debug information into kix_cobol_dbg.cfg configuration file.

   myAnimSrvID1;;;;; program1

   myAnimSrvID2;;;;; program2

2. Input the following command lines in separate terminals respectively:

   anim %XmyAnimSrvID1

   anim %XmyAnimSrvID2

   When these two programs are launched by the ART for CICS application server, the user can debug both programs in separate terminals respectively.

If one ART for CICS user wants to debug two different COBOL programs with LINK command, do the following:

1. Add the following COBOL debug information into kix_cobol_dbg.cfg configuration file.

   anim %XmyAnimSrvID1

   anim %XmyAnimSrvID2

2. Input the following command lines in separate terminals respectively:

When two programs are launched by the ART for CICS application server, the user can debug both programs in separate terminals respectively.

Like other Tuxedo applications, CICS Runtime is managed by Tuxedo that records certain events and problems in a dedicated system log.

This log is the standard Tuxedo User Log (ULOG) whose name is contained in the system variable ULOGPFX of the Tuxedo ubbconfig file.

Example:

ULOGPFX="/home2/work9/demo/Logs/TUX/log/ULOG"

To switch your transaction from enabled to disabled, you have to modify the seventh field of this csv file, to change the previous value from an implicit (" " space(s)) or an explicit ENABLED status to the explicit DISABLED status.

After shutting down and booting the CICS Runtime Tuxedo servers, your modifications of one or more programs will be taken in account.

If you disable a program, when somebody wants to use it, the error messages displayed depend on the way that the application handles CICS errors.

Listing 4‑79 Example Simple Application SA02 COBOL Program Set to DISABLED in programs.desc

#PROGRAM;GROUP;DESCRIPTION;LANGUAGE; ; ;STATUS
RSSAT000;SIMPAPP; Home Menu Program of the Simple Application ;COBOL
RSSAT001;SIMPAPP; Customer Detailed Information Program of the Simple Application ;COBOL; ; ;ENABLED;
RSSAT002;SIMPAPP; Customer Maintenance Program of the Simple Application;COBOL; ; ;DISABLED;
RSSAT003;SIMPAPP; Customer List of the Simple Application ;COBOL

To enable a program, you have only to do the opposite, changing the STATUS field from DISABLED to ENABLED or " " (at least one space).

After shutting down and booting the CICS Runtime Tuxedo servers, your modifications of one or more programs take effect.

If you consult the logs of the different transactions servers or the CICS Runtime you will note the modification of the modified status in the stderr_* logs.

Just after the start up of this server, the logs shows (in italics) that this program is disabled.

Listing 4‑80 Log Report Showing Program Status

Groups loaded: <0001>
|----------|
| GROUP |
|----------|
|SIMPAPP |
|----------|
ARTSTRN: Read config done
|---------------------------------------------------|
| TRANCLASS loaded : < 2> |
|---------------------------------------------------|
| TRANCLASS | GROUP |MAXACTIVE|
|------------------------------|----------|---------|
|TRCLASS1 |SIMPAPP | 001|
|TRCLASS2 |SIMPAPP | 002|
|---------------------------------------------------|
|--------------------------------------------------|
| PROGRAMS loaded : < 4> |
|------------------------------------------------------------------|
| PROGRAM | GROUP |LANGUAGE|EXEC| STATUS |
| | | |KEY | |
|------------------------------|----------|--------|----|----------|
|RSSAT000 |SIMPAPP |COBOL |USER|ENABLED |
|RSSAT001 |SIMPAPP |COBOL |USER|ENABLED |
|RSSAT002 |SIMPAPP |COBOL |USER|DISABLED |
|RSSAT003 |SIMPAPP |COBOL |USER|ENABLED |
|------------------------------------------------------------------|
|---------------------------------|
| TRANSACTIONS loaded : < 4> |
|----------------------------------------------|----|-|-|---|-|-|----------|-----|-|--------|-----|---|
| | | | |C|C| |R|R| | |T| | | |
|TRAN| GROUP | PROGRAM |ALIA|M|O|PRI|E|E| STATUS |TASK |R| TRAN | TWA |MAX|
| | | | |D|N| |S|S| |DATA |A| CLASS | SIZ |ACT|
| | | | |S|F| |S|T| |KEY |C| | |IVE|
|----|----------|------------------------------|----|-|-|---|-|-|----------|-----|-|--------|-----|---|
|SA00|SIMPAPP |RSSAT000 | |N|N|001|N|N|ENABLED |USER |Y| |00000|999|
|SA01|SIMPAPP |RSSAT001 | |N|N|001|N|N|ENABLED |USER |Y| |00000|999|
|SA02|SIMPAPP |RSSAT002 | |N|N|001|N|N| ENABLED |USER |Y| |00000|999|
|SA03|SIMPAPP |RSSAT003 | |N|N|001|N|N|ENABLED |USER |Y| |00000|999|
|-----------------------------------------------------------------------------------------------------|
Warning: zero TSQMODEL loaded!!

Sometimes, you want to delete an application from a given machine either to definitely delete all its components or to move them to another machine. If all the resources used by your application were defined in one or more resource groups dedicated to your application, you have only to suppress these groups from CICS Runtime and eventually install them elsewhere.

Each CICS Runtime Tuxedo Server reads a list of groups to be selected and installed at start up, contained in its CLOPT options after the -l parameter. To remove or add group(s) from an application, you have only to remove or add theses groups from this list for each CICS Runtime Tuxedo server.

Your modifications on one or more programs take effect after shutting down and booting up the CICS Runtime Tuxedo servers.

ARTSTRN SRVGRP=GRP02
SRVID=20
CONV=Y
MIN=1 MAX=1 RQADDR=QKIX110 REPLYQ=Y
CLOPT="-o /home2/work9/demo/Logs/TUX/sysout/stdout_strn
-e /home2/work9/demo/Logs/TUX/sysout/stderr_strn -r -- -
s KIXR -l SIMPAPP"

If you want to add one or more groups, you have to concatenate these new groups to those previously defined, separating them with a ":" character.

ARTSTRN SRVGRP=GRP02
SRVID=20
CONV=Y
MIN=1 MAX=1 RQADDR=QKIX110 REPLYQ=Y
CLOPT="-o /home2/work9/demo/Logs/TUX/sysout/stdout_strn
-e /home2/work9/demo/Logs/TUX/sysout/stderr_strn -r -- -
s KIXR -l SIMPAPP:GROUP1:GROUP2"

Listing 4‑83 Example of Removing group1 in ARTSTRN Server

ARTSTRN SRVGRP=GRP02
SRVID=20
CONV=Y
MIN=1 MAX=1 RQADDR=QKIX110 REPLYQ=Y
CLOPT="-o /home2/work9/demo/Logs/TUX/sysout/stdout_strn
-e /home2/work9/demo/Logs/TUX/sysout/stderr_strn -r -- -
s KIXR -l SIMPAPP:GROUP2"

Each C program is loaded as a COBOL program and executed in COBOL runtime, so CICS C program support is COBOL production depended.

Restrictions and requirements for CICS/C support on ART CICS are listed as below:

• The EXEC CICS commands related to nonstructured exception handling are not supported, including:
  • HANDLE ABEND
  • HANDLE AID
  • HANDLE CONDITION
  • IGNORE CONDITION
  • PUSH HANDLE
  • POP HANDLE
• In a C application, every EXEC CICS command is treated as if it had NOHANDLE or RESP option specified.
• In a C application, every EXEC CICS command is treated as if it had NOHANDLE or RESP option specified.
• On Linux, file names and words are case-sensitive. If a header file name is in lowercase in C source file while such name in file system is in uppercase, errors will occur in compiling.
• Does not support packed decimal data.
• Does not support the use of CICS command in macros.
• Support CICS keywords in mixed case.
• Where CICS expects a fixed-length character string (such as a program name, map name, or queue name), you must pad the literal with blanks up to the required length if it is shorter than expected.
• Take care not to define a variable with a field name. That behavior will cause C compiler abend.
• /**/ is used for single line comments. Do not put a comment in the middle of an EXEC CICS command.
• ART CICS does not support argc, argv, and envp
• ART CICS provides two methods to access COMMAREA:
  • ADDRESS COMMAREA
  • Provide an extern global pointer __commptr declared by ART CICS pre-processor automatically. __commptr is system reserved; users cannot define it as other usages.
• ART CICS provides two methods to access EIB:
  • ADDRESS EIB
  • Provide an extern global pointer __eibptr declared by ART CICS pre-processor automatically. __eibptr is system reserved; users cannot define it as other usage.
• The EIB declarations are enclosed in #ifndef and #endif lines, but are not included in all translated files. ART CICS publishes header file dfheiblk.h to contain the definition of all the fields in the EIB. Each translated file just needs to include this header file and all actions are completed by pre-processor automatically.
• BMS screen attributes definitions: C versions of the DFHBMSCA and DFHAID files are supplied by CICS, and may be included by the application programmer when using BMS.
• The string handling functions in the C standard library use a null character as an end-of-string marker. Because CICS does not recognize a null as an end-of-string marker, customers must take care of it when using C functions, for example strcmp, to operate on CICS data areas.
• The string handling functions in the C standard library use a null character as an end-of-string marker. Because CICS does not recognize a null as an end-of-string marker, customers must take care of it when using C functions, for example strcmp, to operate on CICS data areas.
• ART CICS provides iscics() declared in cics.h as well, but users only need to modify makefile to include the header file path.
• Keep EXEC CICS as a whole in one line.
• Multiple CICS commands in one line is not support.
• #pragma will be automatically translated to comments.
• C function exit() will be translated to return.
• Keep C function main(), its parameter list, and parenthesis in one line. For example,

  void main(int argc, char **argv)

• COMMAREA should be a pointer. ART CICS only supports specifying a struct by pointer, not value.

The address of the EXEC interface block (EIB) is not passed as an argument to a C main function; however, users can use the following two methods to obtain the address of the EIB:

• Using ADDRESS EIB
• Using global pointer __eibptr which points to EIB

ART CICS provides prepro-cics-C.pl for CICS/COBOL APIs translation. For more information about prepro-cics-C.pl, please refer to prepro-cics-C.pl.

In order to make sure the C programs could be successfully loaded by COBOL runtime, please build C programs using COBOL compiler rather than gcc/g++.

Use cob to compile C source code as a callable shared object. Please note that dynamic library must have the same name as the C source file name in uppercase.

CPYINC=../includes
cob -z,CC zample_treated.c -o ZAMPLE.so -CC -I${CPYINC}